Skip to main content
Search

Callback: Wallet Verify Result

Where should I integrate​

GTR sends callback type 18 when a Wallet Verify request reaches a result state.

The callback callbackData contains:

  • requestId: original Wallet Verify request id.
  • notifyResult: verification status, message, and stage.
  • walletName: wallet name surfaced by GTR when available.
  • metadata: caller-supplied metadata from the create verify request.
  • addressScreeningResult: address screening result. Only included for successful wallet verification when screening result is available.

About address screening result​

For Wallet Verify callback, addressScreeningResult is only included in the success callback.

  • If wallet verification succeeds, GTR may include addressScreeningResult in the callback payload.
  • If wallet verification fails or expires, addressScreeningResult will be null.

Case 1: Success​

If the wallet owner successfully completed verification, you can expect to receive below callback from GTR with callbackType:18 and verifyStatus:100000.

Once you receive this callback from GTR, you can continue the transfer.

{
  "requestId": "[REQUEST_ID]",
  "invokeVaspCode": "YOUR_VASP_CODE",
  "originatorVasp": "ORIGINATOR_VASP_CODE",
  "beneficiaryVasp": "BENEFICIARY_VASP_CODE",
  "callbackType": 18,
  "callbackData": {
    "requestId": "[REQUEST_ID]",
    "notifyResult": {
      "verifyStatus": 100000,
      "verifyMessage": "wallet signature verified",
      "verifyStage": "WALLET_OWNER_VERIFICATION"
    },
    "walletName": "UNKNOWN WALLET APP",
    "metadata": "{\"user_id\":\"123456\"}",
    "addressScreeningResult": {
      "screeningStatus": "COMPLETED",
      "message": "screening result present",
      "vaspEntityName": "Axchange UK",
      "vaspEntityId": "axchange-uk",
      "vaspCode": "axchangeukadjk",
      "riskTags": [
        "Exchange & Trading Platforms",
        "Centralized Exchange",
        "Unknown Wallet"
      ],
      "riskScore": 4.0
    }
  }
}

Case 2: Fail​

If the wallet owner failed verification, you can expect to receive below callback from GTR with callbackType:18 and verifyStatus:100001.

Once you receive this callback from GTR, you should stop the process or ask your user to retry.

In this fail callback, addressScreeningResult will not be included.

{
  "requestId": "[REQUEST_ID]",
  "invokeVaspCode": "YOUR_VASP_CODE",
  "originatorVasp": "ORIGINATOR_VASP_CODE",
  "beneficiaryVasp": "BENEFICIARY_VASP_CODE",
  "callbackType": 18,
  "callbackData": {
    "requestId": "[REQUEST_ID]",
    "notifyResult": {
      "verifyStatus": 100001,
      "verifyMessage": "wallet signature verification failed",
      "verifyStage": "WALLET_OWNER_VERIFICATION"
    },
    "walletName": "UNKNOWN WALLET APP",
    "metadata": "{\"user_id\":\"123456\"}",
    "addressScreeningResult": null
  }
}

Case 3: Expired​

If the wallet owner never performed any operations and the request was auto-expired by GTR, you can expect to receive below callback from GTR with callbackType:18 and verifyStatus:100031.

Once you receive this callback from GTR, you should cancel the process from your end.

In this expired callback, addressScreeningResult will not be included.

{
  "requestId": "[REQUEST_ID]",
  "invokeVaspCode": "YOUR_VASP_CODE",
  "originatorVasp": "ORIGINATOR_VASP_CODE",
  "beneficiaryVasp": "BENEFICIARY_VASP_CODE",
  "callbackType": 18,
  "callbackData": {
    "requestId": "[REQUEST_ID]",
    "notifyResult": {
      "verifyStatus": 100031,
      "verifyMessage": "Verification Timeout",
      "verifyStage": "WALLET_OWNER_VERIFICATION"
    },
    "walletName": "UNKNOWN WALLET APP",
    "metadata": "{\"user_id\":\"123456\"}",
    "addressScreeningResult": null
  }
}

Response Explained​

Your callback endpoint should return success after accepting the callback.

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