PII Verification Callback

Version: 3.0.0

Method

POST

Url

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

This callback API endpoint is for PII verification. Initiator will send you encrypted PII via GTR and you will need to decrypt the payload with your own private key and verify the received PII with your KYC/KYB datasource from multiple perspectives.

Authentication

No authentication

Path Parameters

No path parameters

Query Parameters

No query parameters

Request Body (Optional)

Schema

	Property	Type	Required	Description
	address	String	No
	addressType	Integer	No
	amount	String	No
	beneficiaryPublicKey	String	No
	beneficiaryVasp	String	No
	beneficiaryVaspName	String	No
	emptyPiiSchema	String	No
	encryptedPayload	String	No
	fiatName	String	No
	fiatPrice	String	No
	hashSalt	String	No
	initiatorExpectVerifyFields	Array<String>	No
	initiatorPublicKey	String	No
	initiatorVasp	String	No
	network	String	No
	originatorExpectVerifyFields	Array<String>	No
	originatorPublicKey	String	No
	originatorVasp	String	No
	originatorVaspName	String	No
	piiSecuredInfo	Object	No
Property Type Description encryptionParams Object The parameters for shared encryption/decryption info, it depends to the algorithm type, if no necessary, please leave it blank or empty Property Type Description ecies Object required if you're using ecies algorithm (ecies_secp384r1_tubitak) should refer to this structure Property Type Description ephemeralPublicKey String initiatorKeyInfo Object initiatorKeyInfo is the direction of Travel Rule Initiator, if you're the initiator, this key should be yours, if you're the receiver (callback server), this is the counter-party VASP's public key that can use to decrypt the PII and encrypt the PII back. Property Type Description publicKey String publicKey is the key-parameters for encryption according to the selected algorithm. If the key already be base64 like (Curve25519) 0szeNNub/IGoe623JCGD4B4bH8I94FozOeZjv1dKlXQ=, then no need to do anything, the PEM format like (RSA) -----BEGIN CERTIFICATE-----, no need to remove it, keep it and bring out instead. piiSecretFormatType String PiiSecretFormatType piiSpecVersion String PIISpecVersionType receiverKeyInfo Object receiverKeyInfo is the direction of Travel Rule Receiver, if you're the initiator, this key must set to the counter-party (targetVasp) VASP's publicKey, if you're the receiver (callback server), this key should be your public key. Property Type Description publicKey String publicKey is the key-parameters for encryption according to the selected algorithm. If the key already be base64 like (Curve25519) 0szeNNub/IGoe623JCGD4B4bH8I94FozOeZjv1dKlXQ=, then no need to do anything, the PEM format like (RSA) -----BEGIN CERTIFICATE-----, no need to remove it, keep it and bring out instead. secretAlgorithm String AlgorithmType securedPayload String encrypted payload for PII
	receiverPublicKey	String	No
	receiverVasp	String	No
	requestId	String	No
	secretType	Integer	No
	tag	String	No
	ticker	String	No
	travelruleId	String	No
	txId	String	No
	verificationDirection	Integer	No
	verifyMessage	String	No
	verifyStatus	Integer	No

Example

{
  "beneficiaryVasp": "string",
  "initiatorExpectVerifyFields": [
    "string"
  ],
  "originatorExpectVerifyFields": [
    "string"
  ],
  "verifyMessage": "string",
  "emptyPiiSchema": "string",
  "travelruleId": "string",
  "txId": "string",
  "originatorVasp": "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"
  },
  "receiverPublicKey": "string",
  "network": "string",
  "hashSalt": "string",
  "fiatName": "string",
  "verifyStatus": 0,
  "requestId": "string",
  "beneficiaryVaspName": "string",
  "fiatPrice": "string",
  "tag": "string",
  "beneficiaryPublicKey": "string",
  "verificationDirection": 0,
  "initiatorVasp": "string",
  "amount": "string",
  "encryptedPayload": "string",
  "ticker": "string",
  "address": "string",
  "addressType": 0,
  "receiverVasp": "string",
  "originatorPublicKey": "string",
  "secretType": 0,
  "originatorVaspName": "string",
  "initiatorPublicKey": "string"
}

Responses

Status 200

OK

JSON Content

Schema

	Property	Type	Description
	data	Object
Property Type Description encryptedPayload String initiatorPublicKey String piiSecuredInfo Object Property Type Description encryptionParams Object The parameters for shared encryption/decryption info, it depends to the algorithm type, if no necessary, please leave it blank or empty Property Type Description ecies Object required if you're using ecies algorithm (ecies_secp384r1_tubitak) should refer to this structure Property Type Description ephemeralPublicKey String initiatorKeyInfo Object initiatorKeyInfo is the direction of Travel Rule Initiator, if you're the initiator, this key should be yours, if you're the receiver (callback server), this is the counter-party VASP's public key that can use to decrypt the PII and encrypt the PII back. Property Type Description publicKey String publicKey is the key-parameters for encryption according to the selected algorithm. If the key already be base64 like (Curve25519) 0szeNNub/IGoe623JCGD4B4bH8I94FozOeZjv1dKlXQ=, then no need to do anything, the PEM format like (RSA) -----BEGIN CERTIFICATE-----, no need to remove it, keep it and bring out instead. piiSecretFormatType String PiiSecretFormatType piiSpecVersion String PIISpecVersionType receiverKeyInfo Object receiverKeyInfo is the direction of Travel Rule Receiver, if you're the initiator, this key must set to the counter-party (targetVasp) VASP's publicKey, if you're the receiver (callback server), this key should be your public key. Property Type Description publicKey String publicKey is the key-parameters for encryption according to the selected algorithm. If the key already be base64 like (Curve25519) 0szeNNub/IGoe623JCGD4B4bH8I94FozOeZjv1dKlXQ=, then no need to do anything, the PEM format like (RSA) -----BEGIN CERTIFICATE-----, no need to remove it, keep it and bring out instead. secretAlgorithm String AlgorithmType securedPayload String encrypted payload for PII preflightCheckMessage String preflightCheckStatus String receiverPublicKey String requestId String verifyFields Array<Object> Property Type Description [*].message String message of match [*].status Integer VerifyFieldStatus [*].type String IvmsFieldEnum
	verifyMessage	String
	verifyStatus	Integer

Example

{
  "data": {
    "encryptedPayload": "string",
    "verifyFields": [
      {
        "message": "string",
        "type": "110026",
        "status": 1
      }
    ],
    "requestId": "string",
    "initiatorPublicKey": "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"
    },
    "preflightCheckStatus": "string",
    "receiverPublicKey": "string",
    "preflightCheckMessage": "string"
  },
  "verifyStatus": 0,
  "verifyMessage": "string"
}

Status HTTP Status: 200, VerifyStatus: 100000

JSON Content

Schema

	Property	Type	Description
	data	Object
Property Type Description No properties
	verifyMessage	String
	verifyStatus	Integer

Example

{
  "data": {},
  "verifyStatus": 0,
  "verifyMessage": "string"
}

• 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:

• You are required fill in your VASP info into PII's BeneficiaryVASP(If you're in the deposit side) or OriginatingVASP(If you're in the withdrawal side)
• You are required to fill in verifyFields to let the Travel Rule initiator knows the matching/mismatching status of each specific PII fields.
• 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"}

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