Refund API Overview

The Refund API lets a BeneficiaryVASP request the return of a received virtual-asset transfer and coordinate the refund with the OriginatorVASP through GTR.

Required implementation roles: OriginatorVASP and BeneficiaryVASP

The requestId identifies the refund throughout the complete flow. If the original transfer was processed by GTR, use that transfer's requestId; GTR checks that the caller is the recorded BeneficiaryVASP and that the original transaction ID and beneficiary address match. A refund can also be opened without a prior GTR Travel Rule record by identifying the OriginatorVASP in originatorVaspInfo.vaspCode.

Roles and responsibilities

Step	Actor	Responsibility
Submit refund	BeneficiaryVASP	Identify the original transfer, amount, reason, and OriginatorVASP.
Review refund	OriginatorVASP	Accept the request and provide a refund destination, or reject it with a reason.
Execute refund	BeneficiaryVASP	After acceptance, transfer the assets to the supplied address.
Notify refund transaction	BeneficiaryVASP	Send the refund transaction ID and actual refunded value to GTR.
Cancel	BeneficiaryVASP	Cancel a refund that should no longer proceed.

Standard flow

Cancellation flow

The BeneficiaryVASP may cancel a non-terminal refund. GTR then sends callback type 22 to the OriginatorVASP with decision: CANCEL and the cancellation reason.

API and callback list

Direction	Name	Endpoint or callback type	Receiving/acting role
VASP to GTR	Submit refund	POST /api/verify/v3/refund/submit	BeneficiaryVASP
VASP to GTR	Submit decision	POST /api/verify/v3/refund/decision	OriginatorVASP
VASP to GTR	Notify refund TXID	POST /api/verify/v3/refund/notify-tx	BeneficiaryVASP
VASP to GTR	Cancel refund	POST /api/verify/v3/refund/cancel	BeneficiaryVASP
GTR to VASP	Refund request query	callbackType: 21	OriginatorVASP
GTR to VASP	Refund decision/cancellation	callbackType: 22	BeneficiaryVASP for a decision; OriginatorVASP for a cancellation
GTR to VASP	Refund TXID notification	callbackType: 23	OriginatorVASP

State rules

• requestId is limited to 128 characters and must remain unchanged across all steps.
• A decision can be submitted only for a pending refund request.
• A refund transaction can be notified only after an ACCEPT decision.
• REJECT, successful TXID notification, and cancellation are terminal outcomes.
• Reusing a requestId for another refund is rejected. Safe retries of an already completed identical action may return success without repeating the callback.