Skip to main content
Search

10-Pre-Transaction PII Notification(Receive Only)

  • Pre-Transaction Approval - Receive PII Notification without Field-Level Verification.
  • GTR will send two consecutive callback requests: address verification (callbackType=6) and PII notification (callbackType=4).
  • The same requestId will be used across both stages.
  • Your server should decrypt and persist the PII payload. No field-level verification is required — if decryption succeeds, return verifyStatus: 100000; if decryption fails, return verifyStatus: 200002.

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 Notification​

  • 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]"
        }
    }
}

Hint:

  • callbackType: 6 → Address Verification, callbackType: 4 → PII Notification (receive only, no field-level verification)
  • 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 both stages
  • Your server should respond within 30 seconds for each callback
  • This test only requires you to decrypt and persist the PII data — no verifyFields comparison is needed

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 Receive Acknowledgment​

When the PII payload is successfully decrypted and persisted, you should return:

  • verifyStatus: 100000 (success)
{
    "verifyStatus": 100000,
    "verifyMessage": "PII received successfully"
}

If PII decryption fails, return:

  • verifyStatus: 200002 (PII decryption failed)
{
    "verifyStatus": 200002,
    "verifyMessage": "PII decryption failed"
}

Test Validation​

Success Criteria:​

  • ✅ Both callback stages handled successfully
  • ✅ Each callback responds within 30 seconds
  • ✅ HTTP status code 200 returned for all stages
  • ✅ Address verification returns verifyStatus: 100000
  • ✅ PII payload successfully decrypted and persisted
  • ✅ PII receive acknowledgment returns verifyStatus: 100000

Common Issues:​

  • ⚠️ PII Decryption: Must properly decrypt the securedPayload using Curve25519 with your private key
  • ⚠️ No Verification Required: This test only requires receive and persist — do not return verifyFields
  • ⚠️ Stage Sequence: Handle callbacks in the correct order; maintain request state across callbacks
  • ⚠️ Ticker Reference: Do NOT use the ticker field to search for users