Submit a Refund Request

The BeneficiaryVASP calls this endpoint to request a refund from the OriginatorVASP. GTR records the request and attempts to send REFUND_REQUEST_QUERY (callbackType: 21) to the OriginatorVASP.

Required implementation role: BeneficiaryVASP

• Your role: BeneficiaryVASP
• Counterparty: OriginatorVASP
• Endpoint: POST /api/verify/v3/refund/submit

Request example

curl --location --request POST '/api/verify/v3/refund/submit' \
  --cert-type P12 --cert ./certificate.p12:'[CERTIFICATE_PASSWORD]' \
  --header 'Authorization: Bearer [LOGIN_TOKEN]' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "refundBasicInfo": {"requestId": "beneficiary-exchange-550e8400-e29b-41d4-a716-446655440000"},
    "blockchainTransaction": {
      "network": "ETH", "ticker": "USDT", "txId": "0x4ab1...91ef"
    },
    "refundDeclaredValue": {"amount": "125.50"},
    "beneficiaryAddress": {"address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72", "tag": ""},
    "refundReason": {
      "reasonType": "ORIGINATOR_TRAVEL_RULE_INCOMPLETE",
      "reason": "Originator information could not be verified"
    },
    "originatorVaspInfo": {"vaspCode": "originator-vasp-code"}
  }'

Parameters

Field	Required	Description
refundBasicInfo.requestId	Yes	Unique refund identifier, maximum 128 characters. For a refund with a prior GTR Travel Rule record, use the original request ID.
blockchainTransaction.network	Yes	Network of the original transfer. Use a value from the Network List.
blockchainTransaction.ticker	Yes	Asset ticker of the original transfer. Use a value from the Ticker List.
blockchainTransaction.txId	Yes for processing	Original on-chain transaction ID. It must match the prior Travel Rule record when one exists.
refundDeclaredValue.amount	Yes	Requested refund amount denominated in the asset specified by blockchainTransaction.ticker. Provide it as a decimal string greater than 0.
beneficiaryAddress.address	Yes	Address that received the original transfer, maximum 255 characters.
beneficiaryAddress.tag	No	Address tag or memo, maximum 64 characters.
refundReason.reasonType	Yes	UNIDENTIFIED_ORIGINATOR, ORIGINATOR_TRAVEL_RULE_INCOMPLETE, SCREENING_CHECK_TRIGGERED, or OTHER.
refundReason.reason	No	Human-readable details, maximum 1,024 characters. Recommended, especially with OTHER.
originatorVaspInfo.vaspCode	Yes	GTR VASP code of the OriginatorVASP. Required to route a refund without a prior Travel Rule record and checked against the existing record when applicable.

For prior Travel Rule transfers, the authenticated caller must be the recorded BeneficiaryVASP, and txId, beneficiary address, and tag must match the original record.

Success response

{
  "verifyStatus": 100000,
  "verifyMessage": "refund request has been sent",
  "data": null
}

Callback type 21 is optional for the OriginatorVASP. An unavailable callback receiver does not undo a successfully created refund request.

What happens next

After the BeneficiaryVASP submits the refund request, the OriginatorVASP receives the Refund Request Query callback and reviews the request.