Skip to main content
Search

02-PII Verify Failed (Natural Person / Pre-Transaction)

  • Pre-Transaction Approval - PII Verification Failed for Natural Person beneficiary (KYC).
  • GTR will send three consecutive callback requests: address verification (callbackType=6), PII verification with encrypted KYC payload containing intentionally incorrect data (callbackType=4), and TXID update notification (callbackType=7).
  • Your server should decrypt the PII payload, verify the Natural Person fields, and return a failed verification. At minimum, the name field (110026) must be reported in verifyFields with status 2 (not matched). Unlike the other PII tests, this test requires verifyFields to be non-null and non-empty.
  • When responding, the returned IVMS payload should carry three sections — Originator, Beneficiary, and OriginatingVASP (the counterparty's VASP block). Keep the incoming Originator, Beneficiary, and OriginatingVASP blocks as received.

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": "[TESTER_KYC_ADDRESS]",
        "tag": "[TESTER_KYC_ADDRESS_TAG]",
        "network": "[TESTER_KYC_NETWORK_SYMBOL]",
        "initiatorVasp": "[TESTER_VASP_CODE]"
    }
}

Stage 2: PII Verification with Encrypted KYC Payload (Incorrect Data)​

  • 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": "[TESTER_KYC_NETWORK_SYMBOL]",
        "ticker": "--YOU SHOULD NOT REFER TO THIS TICKER--",
        "tag": "[TESTER_KYC_ADDRESS_TAG]",
        "address": "[TESTER_KYC_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_KYC_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": "[TESTER_KYC_TX_ID]",
        "requestId": "test-[RANDOM_ID]"
    }
}
  • callbackType: 6 → Address Verification, callbackType: 4 → PII Verification, callbackType: 7 → TXID Update
  • verificationDirection: 2 indicates Pre-Transaction scenario (beneficiary data verification)
  • The KYC payload contains intentionally incorrect Natural Person data
  • 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
  • Even with PII verification failure, the TXID update should still be processed

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

When the Natural Person KYC verification fails, you should return:

  • verifyStatus: 200003 (PII verification failed) — verifyStatus and verifyMessage are top-level fields, verifyFields is nested inside data.
  • verifyFields must be non-null and non-empty for this specific test case, with at least the name field (110026) having status 2 (not matched). Additional fields such as dateOfBirth (110025) or address (110045) are accepted but not required.
{
    "verifyStatus": 200003,
    "verifyMessage": "Natural Person KYC verification failed",
    "data": {
        "verifyFields": [
            {
                "type": "110026",
                "status": 2,
                "message": "name not matched"
            },
            {
                "type": "110025",
                "status": 2,
                "message": "dateOfBirth not matched"
            },
            {
                "type": "110045",
                "status": 2,
                "message": "address not matched"
            }
        ]
    }
}

Note: The data field is required (must be present and non-null). This is the only PII test case that additionally requires verifyFields itself to be non-empty.

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 verification returns verifyStatus: 200003 (PII verification failed)
  • ✅ KYC field validation returns failure result — at minimum the name field (110026) with status: 2 (this test requires verifyFields to be non-empty)
  • ✅ TXID update still processed despite PII failure

Common Issues:​

  • ⚠️ PII Decryption: Must properly decrypt the securedPayload using Curve25519 with your private key
  • ⚠️ Wrong verifyStatus: Must return 200003 for PII verification failure, not a HTTP error code
  • ⚠️ Stage Sequence: Even with PII failure, the TXID update callback should still be processed
  • ⚠️ Ticker Reference: Do NOT use the ticker field to search for users
  • ⚠️ Three IVMS Sections Required in Response: The response payload should carry Originator, Beneficiary, and OriginatingVASP (the counterparty's VASP block) — keep them as received. Even though the field-level verification target is only the Beneficiary person, the Originator person block must still ship out end-to-end so both regulators can trace the full counterparty picture. BeneficiaryVASP (your own side) is not required in the response for BFOC.

Appendix A: IVMS 101 KYC Data​

Note: This JSON is used for testing validation failures. The Beneficiary section contains intentionally incorrect data.

The following JSON structure will be encrypted and sent as securedPayload:

{
    "ivms101": {
        "OriginatingVASP": {
            "originatingVASP": {
                "legalPerson": {
                    "name": {
                        "nameIdentifier": [
                            {
                                "legalPersonName": "Originator VASP Company Name - VVVV Inc.",
                                "legalPersonNameIdentifierType": "LEGL"
                            }
                        ]
                    },
                    "nationalIdentification": {
                        "nationalIdentifierType": "RAID",
                        "registrationAuthority": "RA000388 (i.e: 香港公司註冊處核發 Hong Kong Company Registry Approved, For more please check: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list)",
                        "countryOfIssue": "HK",
                        "nationalIdentifier": "69104532 (i.e: Your Company ID from authroity)"
                    },
                    "geographicAddress": [
                        {
                            "country": "HK",
                            "townName": "Hong Kong",
                            "addressType": "GEOG",
                            "addressLine": [
                                "Please fill your address here"
                            ]
                        }
                    ],
                    "countryOfRegistration": "HK"
                }
            }
        },
        "Originator": {
            "accountNumber": [
                ""
            ],
            "originatorPersons": [
                {
                    "naturalPerson": {
                        "dateAndPlaceOfBirth": {
                            "dateOfBirth": "1986-11-21",
                            "placeOfBirth": "New York City"
                        },
                        "name": {
                            "localNameIdentifier": [
                                {
                                    "nameIdentifierType": "LEGL",
                                    "primaryIdentifier": "Satoshi",
                                    "secondaryIdentifier": "Nakamoto"
                                }
                            ],
                            "nameIdentifier": [
                                {
                                    "nameIdentifierType": "LEGL",
                                    "primaryIdentifier": "Satoshi",
                                    "secondaryIdentifier": "Nakamoto"
                                }
                            ]
                        },
                        "geographicAddress": [
                            {
                                "addressType": "GEOG",
                                "streetName": "Potential Street",
                                "buildingNumber": "123",
                                "buildingName": "Cheese Hut",
                                "postCode": "91361",
                                "townName": "Thousand Oaks",
                                "countrySubDivision": "California",
                                "country": "US"
                            }
                        ],
                        "nationalIdentification": {
                            "nationalIdentifier": "024181096",
                            "nationalIdentifierType": "RAID",
                            "registrationAuthority": "RA000589"
                        },
                        "customerIdentification": "0xA3a8C1C840A8C2049472065b2664E01E0e8A8b67",
                        "countryOfResidence": "US"
                    }
                }
            ]
        },
        "Beneficiary": {
            "beneficiaryPersons": [
                {
                    "naturalPerson": {
                        "dateAndPlaceOfBirth": {
                            "placeOfBirth": "WRONG_PLACE",
                            "dateOfBirth": "1900-01-01"
                        },
                        "name": {
                            "localNameIdentifier": [
                                {
                                    "nameIdentifierType": "LEGL",
                                    "primaryIdentifier": "WRONG_FIRST_NAME",
                                    "secondaryIdentifier": "WRONG_LAST_NAME"
                                }
                            ],
                            "nameIdentifier": [
                                {
                                    "nameIdentifierType": "LEGL",
                                    "primaryIdentifier": "WRONG_FIRST_NAME",
                                    "secondaryIdentifier": "WRONG_LAST_NAME"
                                }
                            ]
                        },
                        "geographicAddress": [
                            {
                                "addressType": "GEOG",
                                "streetName": "Wrong Street",
                                "buildingNumber": "000",
                                "buildingName": "Wrong Building",
                                "postCode": "00000",
                                "townName": "Wrong City",
                                "countrySubDivision": "Wrong State",
                                "country": "XX"
                            }
                        ],
                        "nationalIdentification": {
                            "nationalIdentifier": "WRONG_ID_NUMBER",
                            "nationalIdentifierType": "RAID",
                            "registrationAuthority": "INVALID_AUTH"
                        }
                    }
                }
            ],
            "accountNumber": [
                "0xb7f9a622c34652cd8f54de97a15281b98a8114ac"
            ]
        },
        "BeneficiaryVASP": {
            "beneficiaryVASP": {
                "legalPerson": {
                    "name": {
                        "nameIdentifier": [
                            {
                                "legalPersonName": "Originator VASP Company Name - VVVV Inc.",
                                "legalPersonNameIdentifierType": "LEGL"
                            }
                        ]
                    },
                    "nationalIdentification": {
                        "nationalIdentifierType": "RAID",
                        "registrationAuthority": "RA000388 (i.e: 香港公司註冊處核發 Hong Kong Company Registry Approved, For more please check: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list)",
                        "countryOfIssue": "HK",
                        "nationalIdentifier": "69104532 (i.e: Your Company ID from authroity)"
                    },
                    "geographicAddress": [
                        {
                            "country": "HK",
                            "townName": "Hong Kong",
                            "addressType": "GEOG",
                            "addressLine": [
                                "Please fill your address here"
                            ]
                        }
                    ],
                    "countryOfRegistration": "HK"
                }
            }
        }
    }
}