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 (Optional)

Schema

address

RequiredString

address is beneficiary address (in all scenario)

Min Length1

Max Length256

Example

E9aX7TbJqvLwzC1f8rYpBnGks3M0QHjVxODUZ_WRmT2yXoLp

amount

RequiredString

amount is corresponding to the ticker, the amount of the coin in this transfer, this amount should be string (Reference: Longest AVAX should be decimal(28,18) / numeric(28,18))

Min Length0

Max Length64

Example

0.000000000000000008

beneficiaryVasp

RequiredString

perspective of money transfer direction, beneficiary means who receive the money

Min Length0

Max Length32

Example

(GTR VASP Code)

beneficiaryVaspName

RequiredString

perspective of money transfer direction, beneficiary means who receive the money

Min Length0

Max Length128

Example

(GTR VASP Name)

fiatName

RequiredString

fiatName is the currency unit of equality amount of coin, should convert to stable coin (USDT, EURC, USDC...etc) / real world fiat currency like (USD, EUR, NZD, GBP, HKD, CNY, JPY, TRY...etc), please prior to choose fiat currency.

Min Length0

Max Length64

Example

USD

fiatPrice

RequiredString

fiatPrice is the equality amount of coin, the price ratio is always changing, just make sure you convert when the time you initiate the request.

Min Length0

Max Length64

Example

84.12

initiatorExpectVerifyFields

OptionalArray<String>

The PII Info that you expect to be verify, GTR will matches the results if the targetVasp has verified. The verify type code has distinguish by different direction like Originator and Beneficiary. The PII Type code can refer to:

Example

["110026", "110025", "110045", "100031"] *(110026: Beneficiary Natural Person Name, 110025: Beneficiary Natural Person Date of Birth, 110045: Beneficiary Natural Person National ID, 100031: Originator Natural Person Address Lines),

initiatorVasp

RequiredString

the vasp who initiate this request

Min Length0

Max Length32

Example

[vaspCode]

network

RequiredString

Network name in short symbol, the reference can check the table.

Min Length0

Max Length64

Example

XRP

originatorVasp

RequiredString

perspective of money transfer direction, originator means who send the money

Min Length0

Max Length32

Example

(GTR VASP Code)

originatorVaspName

RequiredString

perspective of money transfer direction, originator means who send the money

Min Length0

Max Length128

Example

(GTR VASP Name)

[+]piiSecuredInfo

RequiredObject

PiiSecuredInfo

Example

(Refer to inner structure)

receiverVasp

RequiredString

the vasp who will receive this request

Min Length0

Max Length32

Example

[vaspCode]

requestId

RequiredString

requestId is the unique id for all transaction, the same travelrule-request invoke process flow should be using same requestId, the recommend format is: "[YOUR_VASP_NAME]-[UUIDv4]"

Min Length4

Max Length64

Pattern

[\w\d_=-]+

Example

testexchange-189e9948-64c7-4a6c-bb4f-859c173321c5

tag

OptionalString

some of network like XRP required to input address tag (memo)

Min Length0

Max Length64

Example

466489710

ticker

RequiredString

ticker (coin) is the symbol of coin money, could refer to CMC

Min Length0

Max Length64

Example

USDT

txId

RequiredString

*if the travel rule is after on chain, then the txId is required. the tx id format type can check the table.

Min Length0

Max Length256

Example

d1029841dacb031098288b257b628a967eb963bbaccf954506ad0694219497a4

verificationDirection

RequiredInteger (int32)

direction is travelrule direction. verifyDirection: 1 (After On Chain), verifyDirection: 2 (Before On Chain), Perspective if from your system, 1 means you're Beneficiary that receive funds, and you send the Originator KYC/B (IVMS) to check, 2 means you're Originator that you want to send the funds, and you send the Beneficiary KYC/B (IVMS) to check.

verifyMessage

OptionalString

Min Length0

Max Length4096

verifyStatus

OptionalInteger (int32)

Example

{
  "initiatorVasp": "[vaspCode]",
  "amount": "0.000000000000000008",
  "ticker": "USDT",
  "address": "E9aX7TbJqvLwzC1f8rYpBnGks3M0QHjVxODUZ_WRmT2yXoLp",
  "beneficiaryVasp": "(GTR VASP Code)",
  "initiatorExpectVerifyFields": "[\"110026\", \"110025\", \"110045\", \"100031\"] *(110026: Beneficiary Natural Person Name, 110025: Beneficiary Natural Person Date of Birth, 110045: Beneficiary Natural Person National ID, 100031: Originator Natural Person Address Lines), ",
  "verifyMessage": "string",
  "receiverVasp": "[vaspCode]",
  "txId": "d1029841dacb031098288b257b628a967eb963bbaccf954506ad0694219497a4",
  "originatorVasp": "(GTR VASP Code)",
  "piiSecuredInfo": "(Refer to inner structure)",
  "network": "XRP",
  "fiatName": "USD",
  "verifyStatus": 0,
  "requestId": "testexchange-189e9948-64c7-4a6c-bb4f-859c173321c5",
  "beneficiaryVaspName": "(GTR VASP Name)",
  "fiatPrice": "84.12",
  "originatorVaspName": "(GTR VASP Name)",
  "tag": "466489710",
  "verificationDirection": 0
}

Responses

Status 200

OK

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

RequiredInteger (int32)

VerifyStatus

Example

100000

Example

{
  "data": {
    "encryptedPayload": "string",
    "verifyFields": [
      {
        "message": "string",
        "type": "110026",
        "status": 1
      }
    ],
    "requestId": "testexchange-189e9948-64c7-4a6c-bb4f-859c173321c5",
    "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": 100000,
  "verifyMessage": "string"
}

Status HTTP Status: 200, VerifyStatus: 200002

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

RequiredInteger (int32)

VerifyStatus

Example

100000

Example

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

Status HTTP Status: 200, VerifyStatus: 200003

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

RequiredInteger (int32)

VerifyStatus

Example

100000

Example

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

Status HTTP Status: 200, VerifyStatus: 100000

JSON Content

Schema

[+]data

OptionalObject

verifyMessage

OptionalString

verifyStatus

RequiredInteger (int32)

VerifyStatus

Example

100000

Example

{
  "data": {},
  "verifyStatus": 100000,
  "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"}