04-PII Verify Failed (Legal Person / Pre-Transaction)
- Pre-Transaction Approval - PII Verification Failed for Legal Person beneficiary (KYB).
- GTR will send three consecutive callback requests: address verification (
callbackType=6), PII verification with encrypted KYB payload containing intentionally incorrect data (callbackType=4), and TXID update notification (callbackType=7). - Your server should decrypt the PII payload, verify the Legal Person fields, and return a failed verification. At minimum, the legal person name field (
111001) must be reported inverifyFieldswithstatus2 (not matched). - When responding, the returned IVMS payload should carry three sections —
Originator,Beneficiary, andOriginatingVASP(the counterparty's VASP block). Keep the incomingOriginator,Beneficiary, andOriginatingVASPblocks 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 KYB 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_KYB_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 UpdateverificationDirection: 2indicates Pre-Transaction scenario (beneficiary data verification)- The KYB payload contains intentionally incorrect Legal Person data
- Do NOT use the
tickerfield to search for users - PII payload requires decryption using your private key with Curve25519
- The same
requestIdis 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:
- Receiver Callback API 1: Address Verification
- Callback API 3: PII Verification
- Callback API 5: Update TX ID
- Authentication & mTLS Setup
- Callback Server Setup Guide
- Python Callback Server Example
- Golang Callback Server Example
- Cipher Curve25519 Guideline
- IVMS 101 Guidelines
- PII Verification Methods
- PII Verify Fields
- List of Networks
- Pre-Transaction Travel Rule Overview
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 Legal Person KYB verification fails, you should return:
verifyStatus: 200003 (PII verification failed) —verifyStatusandverifyMessageare top-level fields,verifyFieldsis nested insidedata.verifyFieldsshould include at least the legal person name field (111001) withstatus2 (not matched). Additional fields such ascountryOfRegistration(111022) orgeographicAddress(111003) are accepted but not required.
{
"verifyStatus": 200003,
"verifyMessage": "Legal Person KYB verification failed",
"data": {
"verifyFields": [
{
"type": "111001",
"status": 2,
"message": "legalPersonName not matched"
},
{
"type": "111022",
"status": 2,
"message": "countryOfRegistration not matched"
},
{
"type": "111003",
"status": 2,
"message": "geographicAddress not matched"
}
]
}
}
Note: The data field is required (must be present and non-null).
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) - ✅ KYB field validation returns failure result — at minimum the legal person name field (
111001) withstatus: 2 - ✅ TXID update still processed despite PII failure
Common Issues:
- ⚠️ PII Decryption: Must properly decrypt the
securedPayloadusing Curve25519 with your private key - ⚠️ Wrong verifyStatus: Must return
200003for 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, andOriginatingVASP(the counterparty's VASP block) — keep them as received. Even though the field-level verification target is only theBeneficiary(Legal Person), theOriginatorperson 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 KYB Data
Note: This JSON is used for testing validation failures. The Beneficiary section contains intentionally incorrect Legal Person 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": [
{
"legalPerson": {
"name": {
"nameIdentifier": [
{
"legalPersonName": "Simulation Business Company Inc.",
"legalPersonNameIdentifierType": "LEGL"
}
]
},
"countryOfRegistration": "",
"nationalIdentification": {
"nationalIdentifier": "",
"nationalIdentifierType": "",
"countryOfIssue": "",
"registrationAuthority": ""
},
"geographicAddress": [
{
"addressType": "",
"postCode": "",
"townName": "",
"addressLine": [
""
],
"country": ""
}
]
}
},
{
"naturalPerson": {
"dateAndPlaceOfBirth": {
"placeOfBirth": "US",
"dateOfBirth": "1986-11-21"
},
"name": {
"localNameIdentifier": [
{
"nameIdentifierType": "LEGL",
"primaryIdentifier": "Satoshi",
"secondaryIdentifier": "Nakamoto"
}
],
"nameIdentifier": [
{
"nameIdentifierType": "LEGL",
"primaryIdentifier": "Satoshi",
"secondaryIdentifier": "Nakamoto"
}
]
}
}
}
],
"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"
}
}
}
}
}