Skip to main content
Search

08-Pre-Transaction Full Flow

  • Pre-Transaction Approval - Complete Flow with Address Verification, PII Verification, and TXID Update.
  • GTR will send three consecutive callback requests: address verification (callbackType=6), PII verification (callbackType=4), and TXID update notification (callbackType=7).
  • The same requestId will be used across all three stages.
  • Your server should handle each stage sequentially and respond with the appropriate verification result.

GTR Request Sequence (GTR → VASP)​

  • Method: POST
  • Your Callback Endpoint: https://[YOUR_CALLBACK_URL]
  • Authentication:
    • mTLS (Mutual Transport Layer Security) - GTR will authenticate using client certificates
  • Header:
    • Content-Type: application/json

Stage 1: Address Verification​

  • Body:
{
    "requestId": "test-[RANDOM_ID]",
    "invokeVaspCode": "[YOUR_VASP_CODE]",
    "originatorVasp": "[TESTER_VASP_CODE]",
    "beneficiaryVasp": "[YOUR_VASP_CODE]",
    "callbackType": 6,
    "callbackData": {
        "requestId": "test-[RANDOM_ID]",
        "originatorVasp": "[TESTER_VASP_CODE]",
        "originatorVaspName": "[TESTER_VASP_NAME]",
        "ticker": "--YOU SHOULD NOT REFER THIS TICKER TO SEARCH YOUR USER--",
        "address": "[TEST_ADDRESS]",
        "tag": "[ADDRESS_TAG]",
        "network": "[NETWORK_SYMBOL]",
        "initiatorVasp": "[TESTER_VASP_CODE]"
    }
}

Stage 2: PII Verification​

  • Body:
{
    "requestId": "test-[RANDOM_ID]",
    "invokeVaspCode": "[YOUR_VASP_CODE]",
    "originatorVasp": "[TESTER_VASP_CODE]",
    "beneficiaryVasp": "[YOUR_VASP_CODE]",
    "callbackType": 4,
    "callbackData": {
        "requestId": "test-[RANDOM_ID]",
        "amount": "1000",
        "fiatPrice": "6.66",
        "fiatName": "USDT",
        "network": "[NETWORK_SYMBOL]",
        "ticker": "--YOU SHOULD NOT REFER TO THIS TICKER--",
        "tag": "[ADDRESS_TAG]",
        "address": "[TEST_ADDRESS]",
        "secretType": 1,
        "originatorVasp": "[TESTER_VASP_CODE]",
        "beneficiaryVasp": "[YOUR_VASP_CODE]",
        "initiatorVasp": "[TESTER_VASP_CODE]",
        "receiverVasp": "[YOUR_VASP_CODE]",
        "verificationDirection": 2,
        "piiSecuredInfo": {
            "initiatorKeyInfo": {
                "publicKey": "[INITIATOR_PUBLIC_KEY]"
            },
            "receiverKeyInfo": {
                "publicKey": "[YOUR_PUBLIC_KEY]"
            },
            "piiSecretFormatType": "FULL_JSON_OBJECT_ENCRYPT",
            "piiSpecVersion": "ivms101-2020",
            "secretAlgorithm": "ed25519_curve25519",
            "securedPayload": "[ENCRYPTED_PII_PAYLOAD]"
        }
    }
}

Stage 3: TXID Update Notification​

  • Body:
{
    "requestId": "test-[RANDOM_ID]",
    "invokeVaspCode": "[YOUR_VASP_CODE]",
    "originatorVasp": "[TESTER_VASP_CODE]",
    "beneficiaryVasp": "[YOUR_VASP_CODE]",
    "callbackType": 7,
    "callbackData": {
        "txId": "[BLOCKCHAIN_TX_ID]",
        "requestId": "test-[RANDOM_ID]"
    }
}

Hint:

  • callbackType: 6 → Address Verification, callbackType: 4 → PII Verification, callbackType: 7 → TXID Update
  • Do NOT use the ticker field to search for users
  • PII payload requires decryption using your private key with Curve25519
  • The same requestId is used across all three stages
  • Your server should respond within 30 seconds for each callback

Materials:

Expected Response Sequence (VASP → GTR)​

Your server should respond within 30 seconds for each callback. All responses should return HTTP Status Code 200.

Stage 1 Response: Address Verification Success​

When the address is found in your system, you should return:

  • verifyStatus: 100000 (success)
{
    "verifyStatus": 100000,
    "verifyMessage": "Address verification passed"
}

Stage 2 Response: PII Verification Success​

When the PII is successfully verified, you should return:

  • verifyStatus: 100000 (success)
  • verifyFields with each field's verification result
{
    "data": {
        "verifyStatus": 100000,
        "verifyMessage": "PII verification passed",
        "verifyFields": [
            {
                "type": "110026",
                "status": 1,
                "message": "matched"
            }
        ]
    }
}

Stage 3 Response: TXID Update Acknowledgment​

When the TXID update is received, you should return:

  • verifyStatus: 100000 (success)
{
    "verifyStatus": 100000,
    "verifyMessage": "TX ID update received successfully"
}

Test Validation​

Success Criteria:​

  • ✅ All three callback stages handled successfully
  • ✅ Each callback responds within 30 seconds
  • ✅ HTTP status code 200 returned for all stages
  • ✅ Address verification returns verifyStatus: 100000
  • ✅ PII decryption and verification returns appropriate field validation results
  • ✅ TXID update properly recorded in your system

Common Issues:​

  • ⚠️ Stage Sequence: Handle callbacks in the correct order; maintain request state across multiple callbacks
  • ⚠️ PII Decryption: Must properly decrypt the securedPayload using Curve25519 with your private key
  • ⚠️ TXID Storage: Store the final TXID for transaction completion
  • ⚠️ Ticker Reference: Do NOT use the ticker field to search for users