Skip to main content
Search

Callback - Retrieve PII

When your counterparty accesses the PII Retrieval Link from email, your VASP will receive this callback request with callbackType=12.

Request & Response​

Once your counterparty VASP uses the link in the email to retrieve PII, GTR will send you the following request with callbackType=12 to your callback endpoint that configured on GTR Dashboard.

{
  "requestId": "[ORIGIN REQUEST ID]",
  "invokeVaspCode": "[YOUR VASP CODE]",
  "originatorVasp": "[YOUR VASP CODE]",
  "beneficiaryVasp": "[BENEFICIARY NAME: important - this is just a name, not an id]",
  "callbackType": 12,
  "callbackData": {
    "requestId": "[ORIGIN REQUEST ID]",
    "beneficiaryAddress": {
      "address": "[ADDRESS]",
      "addressType": 0,
      "tag": "[TAG: IF APPLICABLE]"
    },
    "blockchainTransaction": {
      "blockHash": "",
      "blockId": "",
      "network": "[NETWORK SYMBOL]",
      "ticker": "[TICKER SYMBOL]",
      "txId": "[ON CHAIN TX ID]",
      "txIdType": 0,
      "vin": "",
      "vout": ""
    },
    "direction": 2,
    // will be fixed as 2, as this is usually a Pre-transaction situation
    "initiatorKeyInfo": {
      "algorithmType": "ed25519_curve25519",
      // fixed as ed25519_curve25519
      "keyInfo": {
        "publicKey": "[COUNTER-PARTY VASP PUBLIC KEY, USE THIS TO ENCRYPT PII]"
      }
    }
  }
}
  • When you receive the callback request, please search your customer's PII from your in-house KYC database by txId, beneficiaryAddress.address to find the originator person of this transfer.
  • Once you find the exact originator, use that specific customer's PII to fill into Originator of IVMS payload and encrypt.
  • You should run the encryption algorithm ed25519_curve25519 with your counterparty's temporary Public Key in initiatorKeyInfo.keyInfo.publicKey.
  • Put the encrypted result into securedPayload.

Response A: Success​

If this callback request is processed successfully on your side, GTR expects a response with HTTP Status=200 and verifyStatus=100000 from you.

{
    "data": {
        "piiSecuredInfo": {
            "encryptionParams": {}, // leave it empty
            "initiatorKeyInfo": {
                "publicKey": "[PUT COUNTER-PARTY PUBLIC KEY HERE]"
            },
            "piiSecretFormatType": "FULL_JSON_OBJECT_ENCRYPT", // fixed
            "piiSpecVersion": "ivms101-2020", // fixed
            "receiverKeyInfo": {
                "publicKey": "[PUT YOUR PUBLIC KEY HERE]"
            },
            "secretAlgorithm": "ed25519_curve25519", // fixed
            "securedPayload": "[PUT YOUR ENCRYPTED PII HERE]"
        }
    },
    "verifyMessage": "Verification Success",
    "verifyStatus": 100000
}

Response B: Fail​

If you encountered some issue when running encryption, please provide the failure reason in verifyMessage and return the HTTP Status=200 and verifyStatus=200002.

{
  "data": null,
  "verifyMessage": "cannot encrypt",
  "verifyStatus": 200002
}

If the failure you encountered is not in the encryption steps, you can return a more general status as verifyStatus=100008.

{
  "data": null,
  "verifyMessage": "internal server failed",
  "verifyStatus": 100008
}