PII Verification Callback

Version: 3.0.0

Method

POST

Url

https://{YOUR_SERVICE_URL}/(pii verify: 4)

This API endpoint is for PII verification, initiator will send you encrypted PII via GTR, you have to decrypt use your own private key and check the KYC/KYB in different direction. For you (in callback perspective), if you're deposit side, the verificationDirection = 2, you check the Beneficiary info is correct or not, please use the address+tag in the request payload to identify your customer, do not use the address in the PII to identify customer. If you're withdraw side, the verificationDirection = 1, you need to check the Originator info is correct or not. after verify, you put in your VASP(Company) info into pii's BeneficairyVASP(If you're deposit) or OriginatingVASP(If you're withdraw) and encrypt send back, also to send back the verifyFields to let the initiator knows the status of matching. Also, the preflightCheck and be also response here to let initiator know whether you will accept the transaction or not (Only suitable for the scenario of before-on-chain, you're beneficiary).

Authentication

No authentication

Path Parameters

No path parameters

Query Parameters

No query parameters

Request Body (Required)

Schema

address

OptionalString

addressType

OptionalInteger (int32)

amount

OptionalString

beneficiaryPublicKey

OptionalString

beneficiaryVasp

OptionalString

Min Length0

Max Length32

beneficiaryVaspName

OptionalString

Min Length0

Max Length128

emptyPiiSchema

OptionalString

encryptedPayload

OptionalString

fiatName

OptionalString

fiatPrice

OptionalString

hashSalt

OptionalString

initiatorExpectVerifyFields

OptionalArray<String>

initiatorPublicKey

OptionalString

initiatorVasp

OptionalString

network

OptionalString

originatorExpectVerifyFields

OptionalArray<String>

originatorPublicKey

OptionalString

originatorVasp

OptionalString

Min Length0

Max Length32

originatorVaspName

OptionalString

Min Length0

Max Length128

[+]piiSecuredInfo

OptionalObject

receiverPublicKey

OptionalString

receiverVasp

OptionalString

requestId

OptionalString

secretType

OptionalInteger (int32)

tag

OptionalString

ticker

OptionalString

travelruleId

OptionalString

txId

OptionalString

verificationDirection

OptionalInteger (int32)

verifyMessage

OptionalString

verifyStatus

OptionalInteger (int32)

Example

{
  "beneficiaryVasp": "string",
  "initiatorExpectVerifyFields": [
    "string"
  ],
  "verifyMessage": "string",
  "travelruleId": "string",
  "txId": "string",
  "originatorVasp": "string",
  "receiverPublicKey": "string",
  "piiSecuredInfo": {
    "piiSpecVersion": "ivms101-2020",
    "secretAlgorithm": "ecies_secp256r1",
    "receiverKeyInfo": "(Refer to inner structure)",
    "initiatorKeyInfo": "(Refer to inner structure)",
    "securedPayload": "(base64 or other format's encrypted raw text)",
    "encryptionParams": "(Refer to inner structure)",
    "piiSecretFormatType": "FULL_JSON_OBJECT_ENCRYPT"
  },
  "network": "string",
  "hashSalt": "string",
  "fiatName": "string",
  "verifyStatus": 0,
  "requestId": "string",
  "beneficiaryVaspName": "string",
  "fiatPrice": "string",
  "tag": "string",
  "beneficiaryPublicKey": "string",
  "verificationDirection": 0,
  "initiatorVasp": "string",
  "encryptedPayload": "string",
  "amount": "string",
  "ticker": "string",
  "address": "string",
  "addressType": 0,
  "receiverVasp": "string",
  "originatorPublicKey": "string",
  "secretType": 0,
  "originatorVaspName": "string",
  "initiatorPublicKey": "string"
}

Responses

Status HTTP Status: 200, VerifyStatus: 200002

default response

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

OptionalInteger (int32)

Example

{
  "verifyStatus": 200002,
  "verifyMessage": "Decrypt failed"
}

Status HTTP Status: 200, VerifyStatus: 200003

default response

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

OptionalInteger (int32)

Example

{
  "verifyStatus": 200003,
  "verifyMessage": "PII Verification Failed"
}

Status HTTP Status: 200, VerifyStatus: 100000

default response

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

OptionalInteger (int32)

Example

{
  "verifyStatus": 100000,
  "verifyMessage": "Verify Success"
}

• If your VASP is in the deposit side(it is an inbound transaction to you), the verificationDirection will be 2:

  • you need to check beneficiary_address + tag in the request to identify your customer.

• If your VASP is in the withdrawal side(it is an outbound transaction to you), the verificationDirection will be 1:

  • you need to match the Originator info in the PII payload you received with your owned KYC data.

Before you respond:

• The returned IVMS payload should carry three sections, depending on verificationDirection:
  • AFOC / Post-transaction (verificationDirection=1) — include Originator, Beneficiary, and BeneficiaryVASP (the counterparty's VASP block).
  • BFOC / Pre-transaction (verificationDirection=2) — include Originator, Beneficiary, and OriginatingVASP (the counterparty's VASP block).
• The Originator and Beneficiary person blocks are always both required regardless of direction — even though the field-level verification target is only one of them (Originator in AFOC, Beneficiary in BFOC), both person blocks must ship end-to-end so each side's regulator can trace the full counterparty picture. Keep the incoming blocks untouched.
• You are required to fill in verifyFields inside data to let the Travel Rule initiator know the matching/mismatching status of each specific PII field.
• You can also include prefightCheck status to let initiator know whether you will accept this transaction or not (Only suitable when your VASP is the Beneficiary VASP in a pre-transaction situation).

Response Example 1: Success

HTTP Status: 200, VerifyStatus: 100000

{"verifyStatus": 100000, "verifyMessage": "Verify Success", "data": {"verifyFields": [{"type": "110026", "status": 1, "message": "name matched"}]}}

This response indicates that the PII verification was successful.

Response Example 2: Decryption Fail

HTTP Status: 200, VerifyStatus: 200002

{"verifyStatus": 200002,"verifyMessage": "Decrypt failed"}

This response indicates that the PII decryption failed using your private key.

Response Example 3: PII Verification Fail

HTTP Status: 200, VerifyStatus: 200003

{"verifyStatus": 200003,"verifyMessage": "PII Verification Failed"}