Integration Overview
Business Scenario
GTR 2.0 Travel Rule request could cover 2 situations:
| Type | Description | Roles |
|---|---|---|
| Pre-transaction Travel Rule | - The transaction has not yet been submitted to the blockchain. - This is usually part of a Withdrawal process. - Before transfer transaction executed, Originator VASP initiates a Travel Rule request with encrypted PII payload and sends to Beneficiary VASP to ask for the verification. | Travel Rule Initiator: Originator Travel Rule Receiver & Verifier: Beneficiary VASP |
| Post-transaction Travel Rule | - The transaction has already been recorded on the blockchain. - This is usually part of a Deposit process. - After receiving a deposit transaction, Beneficiary VASP initiates a Travel Rule request with encrypted PII payload and sends to Originator VASP to ask for the verification. | Travel Rule Initiator: Beneficiary Travel Rule Receiver & Verifier: Originator VASP |
In GTR world,
| Name | Description |
|---|---|
| Originator VASP | The VASP that sends the crypto assets |
| Beneficiary VASP | The VASP that receives crypto assets |
| Originator | The specific legal person / natural person who sends the crypto assets (the withdrawal user) |
| Beneficiary | The specific legal person / natural person who receives the crypto assets (the deposit user) |
| Travel Rule Initiator VASP | The VASP that initiates a Travel Rule request by calling GTR REST API |
| Travel Rule Receiver VASP | The VASP that receives the callbacks from GTR (usually be WebHook Server) |
Pre-transaction Travel Rule
Implement as an Initiator
In this case: when a customer on your VASP initiates a transfer of assets to another VASP but the transaction has not yet been sent to the blockchain, your VASP takes on the role of both the Originator VASP and the Travel Rule Request Initiator VASP. Before the blockchain transaction takes place, your VASP is responsible for preparing and sending the PII payload to the Beneficiary VASP.
| Your VASP would be | Your Counterparty VASP would be |
|---|---|
| - the Originator VASP. | - the Beneficiary VASP. |
| - the Travel Rule Initiating VASP which is responsible for collecting PII info and sharing with your counterparty. | - the Travel Rule Receiving VASP which is expected to verify the correctness of PII info received from you. |
In this scenario, 2 verification steps will be gone through for your Travel Rule requests.
| Verification Name | Description |
|---|---|
| Address Verification | your counterparty VASP will verify and confirm whether their VASP owns this specific wallet address. |
| PII Verification | your counterparty VASP will verify and confirm whether PII fields you sent matches with their customer's KYC information. |
Flow Diagram
- Let your user select Beneficiary VASP and fill in the Beneficiary Info.
- Initiate Pre-transaction travel rule by the selected
vaspCode. - Invoke the endpoint One Step Travel Rule API (Initiator API 1) to initiate a travel rule request.
- Wait for GTR to call back your service of the Address verification and PII Verification result. If Address Verification failed, your PII won't be sent to your counterparty.
- Once you received verification result from GTR, make your final decision of executing transfer transaction on blockchain or cancel / reject the withdrawal request.
- If asset transfer is executed on the blockchain, call Report TX ID to notify GTR
and your counterparty VASP of the actual blockchain
tx_id. - If Travel Rule succeed however you still decide to cancel or reject this withdrawal request, explicitly telling GTR to terminate Travel Rule via endpoint End Travel Rule.
Implement as a Receiver
In this case: when your counterparty VASP sends you a Travel Rule request before transaction initialized on the blockchain, and in this request, it specifies that a customer from your VASP is expected to receive assets from the counterparty VASP.
So in this scenario, your VASP acts as both the Beneficiary VASP and the Travel Rule Request Receiving VASP which means your VASP is likely to receive the PII payload and is responsible for completing the verification process.
| Your VASP would be | Your Counterparty VASP would be |
|---|---|
| - the Beneficiary VASP. | - the Originator VASP. |
| - the Travel Rule Receiving VASP which is responsible for PII verifying received from your counterparty. | - the Travel Rule Initiating VASP which is responsible for collecting PII info and sharing with you. |
In this scenario, 2 verification steps need to be completed by your VASP:
| Verification Name | Description |
|---|---|
| Address Verification | this step requires your VASP to verify and confirm whether your VASP owns this specific wallet address. |
| PII Verification | this step requires your VASP to verify and confirm whether your received PII fields matches with your customer's KYC information. |
Flow Diagram
- [Your Counterparty] Initiate travel rule request
- [You] You will firstly receive a callback of Address Verification.
- [You] If you respond Address Verification passed, you will receive a callback of PII Verification.
- [Your Counterparty] Transfer assets on the blockchain or cancel / reject the withdrawal request.
- [You] If your counterparty executes the transaction on the blockchain, you will receive an update of actual
tx_idvia Notify TX ID - [You] If your counterparty cancels or rejects this withdrawal request, you will receive an update of Travel Rule End
Post-transaction Travel Rule
Implement as an Initiator
In this case: when your VASP has received assets from a counterparty VASP, and you subsequently request PII verification from that counterparty because there is no Travel Rule record associated with this blockchain transaction, your VASP as the Beneficiary VASP of this asset transfer, becomes the Travel Rule Request Initiating VASP. As such, your VASP is responsible for initiating the Travel Rule request, preparing and sending the PII payload to your counterparty.
| Your VASP would be | Your Counterparty VASP would be |
|---|---|
| - the Beneficiary VASP. | - the Originator VASP. |
| - the Travel Rule Initiator VASP which is responsible for collecting PII info and sharing with your counterparty. | - the Travel Rule Receiver VASP which is responsible for PII verifying received from you. |
In this scenario, 2 verification steps will be gone through for your Travel Rule requests.
| Verification Name | Description |
|---|---|
| TXID Verification | your counterparty VASP will verify and confirm whether their VASP owns this specific blockchain tx_id. |
| PII Verification | your counterparty VASP will verify and confirm whether PII fields you sent matches with their customer's KYC information. |
Flow Diagram
- Let your user select Originator VASP and fill in the Originator Info.
- Initiate Post-transaction travel rule by the selected
vaspCode. - Invoke the endpoint One Step Travel Rule API (Initiator API 1) to initiate a travel rule request.
- Wait for GTR to call back your service of the TXID verification and PII Verification result. If TXID Verification failed, your PII won't be sent to your counterparty.
- Once you received verification result from GTR, make your final decision of continuing or cancel / reject this deposit request.
Implement as a Receiver
In this case: when your VASP received a Travel Rule request from your counterparty VASP after a transaction had already taken place, and in this request, it indicates that a customer from your VASP was the originator of this asset transfer. Your VASP can expect to receive PII payload and is responsible for completing the verification process.
| Your VASP would be | Your Counterparty VASP would be |
|---|---|
| - the Originator VASP. | - the Beneficiary VASP. |
| - the Travel Rule Receiving VASP which is responsible for PII verifying received from your counterparty. | - the Travel Rule Initiating VASP which is responsible for collecting PII info and sharing with you. |
In this scenario, 2 verification steps need to be completed by your VASP:
| Verification Name | Description |
|---|---|
| TXID Verification | this step requires your VASP to verify and confirm whether your VASP owns this specific blockchain tx_id. |
| PII Verification | this step requires your VASP to verify and confirm whether your received PII fields matches with your customer's KYC information. |
Flow Diagram
- [Your Counterparty] Initiate travel rule request
- [You] You will firstly receive a callback of TXID Verification.
- [You] If you respond TXID Verification passed, you will receive a callback of PII Verification.
- [Your Counterparty] Your counterparty will make final decision of continuing their deposit process or reject.
API Reference Full Table
Implementing as a Travel Rule Initiator:
| Step | Pre-transaction Travel Rule | Post-transaction Travel Rule |
|---|---|---|
| Get VASP List | ✅ | ✅ |
| Do Address Routing | ✅ | ✅ |
| Get VASP Detail | ✅ | ✅ |
| One Step Initiate Travel Rule | ✅ | ✅ |
| Submit TXID | ✅ | ❌ |
| End Travel Rule | ✅ | ❌ |
Implementing as a Travel Rule Receiver:
| Step | Pre-transaction Travel Rule | Post-transaction Travel Rule |
|---|---|---|
| Receive Address Verify Callback | ✅ | ❌ |
| Receive TXID Verification Callback | ❌ | ✅ |
| Receive PII Verification Callback | ✅ | ✅ |
| Receive TXID Notify Callback | ✅ | ❌ |
| Receive Travel Rule End Notify Callback | ✅ | ❌ |
Parameters
There are some parameters in GTR specification for all VASPs:
| Name | Description |
|---|---|
| Request Timeout | 15 seconds |
| Response Timeout | 15 seconds |
| Content Type | JSON |
| Authorization | Bearer Token or App Token |
| UniqueID | requestId |
Retry same requestId if verification failed | NOT ALLOWED (Only if Internal Server Error). Please initiate another travel rule with a new requestId |
| RequestId format | [PREFIX]-UUIDv4 |
| How long should I keep the log | 30 days |
Callback API
Your service is only required to provide single endpoint for GTR to send you callback request. Callback URL is configurable on GTR website.
The callback request payload looks like:
{
"requestId": "[REQUEST-ID]",
"invokeVaspCode": "[Invoker VASP Code]",
"originatorVasp": "[Originator VASP Code]",
"beneficiaryVasp": "[Beneficiary VASP Code]",
"callbackType": 0,
"callbackData": {
}
}
| Name | Description |
|---|---|
requestId | The requestId from the Travel Rule Initiator VASP. The same Travel Rule will use the same requestId. If you see any parameter named requestId, it refers to the same thing. |
invokeVaspCode | The VASP that will receive this callback. This is useful if your brand operates multiple local exchanges and they all share the same callback endpoint. You can use this invokeVaspCode to route traffic to the corresponding logic. |
originatorVasp | Sender VASP in a crypto assets transfer. |
beneficiaryVasp | Receiver VASP in a crypto assets transfer. |
callbackType | A number to distinguish callback request type since single callback endpoint is shared across all callback requests. |
callbackData | For different callbackType, callbackData could be different structure. |