Callback API

Callback API for Verification Result Notification

POST VEGA_VERIFICATION_CALLBACK_API_PATH

Enclave Environment Variable:

Enter the Callback API endpoint in VEGA_VERIFICATION_CALLBACK_API_PATH field.

Callback API enables the asynchronous processing of verification. Following 5 APIs work asynchronously.

  • User Verification API

  • Transaction Result Report API

  • Error Report API

  • Risk Assessment with Chainalysis KYT API

  • Risk Assessment with Refinitiv WCO API

Here are five typical cases of enclave calling callback API.

  • Enclave received a result of the past requested verification (callbackType: VERIFICATION_RESULT)

  • Enclave received an originating VASP sending report of txHash or txID which is matched to specific verification (callbackType: TX_REPORT)

  • Enclave received an originating VASP sending error report of specific verification (callbackType: ERROR_REPORT)

  • Enclave received a result for a previously registered Chainalysis KYT request (callbackType: CHAINALYSIS_KYT_RESULT)

  • Enclave received a result for a previously registered Refinitiv WCO request (callbackType: REFINITIV_WCO_RESULT)

Response Time Requirement

The callback API must respond in 1 second after being called.

Implementation Policy

  • Callback API must return 200 OK status codes only.

  • API needs to respond in possibly the fastest timing, not processing complicated tasks.

  • Idempotent guaranteed implementation

    • Enclave can call callback API multiple times simultaneously to prevent data loss.

    • Therefore, the API developer needs to consider the duplicated case carefully. (e.g. Ignore duplicated requests after the first call)

Request Header

Field Name
Description

Authorization

Bearer <VEGA_VERIFICATION_AUTHORIZATION_TOKEN>

Request Body

Request Body Example for VERIFICATION_RESULT callbackType
{
  "callbackType": "VERIFICATION_RESULT",
  "data": {
    "verificationUuid": "64ab871b-14a3-47df-9b80-368e29fe8180",
    "verificationResult": "DENIED",
    "reason": "UNKNOWN-ADDRESS",
    "ivms101": {
      "originator": {
        "originatorPersons": [
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "James",
                    "secondaryIdentifier": "Din",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9a"]
      },
      "beneficiary": {
        "beneficiaryPersons": [
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Taylor",
                    "secondaryIdentifier": "Robbins",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": ["0xb0bFf9721871e22653358956cf59a5FdBF3D752F"]
      },
      "originatingVASP": {
        "legalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Lambda256",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "geographicAddress": [
            {
              "addressType": "GEOG",
              "postcode": "123123c",
              "townName": "Yeoksam-dong",
              "addressLine": ["sechogu street", "100-100"],
              "country": "KR"
            }
          ],
          "nationalIdentification": {
            "nationalIdentifier": "KR0001",
            "nationalIdentifierType": "RAID",
            "registrationAuthority": "RA000151"
          }
        }
      },
      "beneficiaryVASP": {
        "legalPerson": {
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Lambda256 Exchange",
                "legalPersonNameIdentifierType": "LEGL"
              }
            ]
          },
          "geographicAddress": [
            {
              "addressType": "GEOG",
              "postcode": "234234",
              "townName": "Yeoksam-dong",
              "addressLine": ["sechogu street", "100-100"],
              "country": "KR"
            }
          ],
          "nationalIdentification": {
            "nationalIdentifier": "123456",
            "nationalIdentifierType": "RAID",
            "registrationAuthority": "RA000677"
          }
        }
      }
    }
  }
}
Request Body Example for TX_REPORT callbackType
{
  "callbackType": "TX_REPORT",
  "data": {
    "verificationUuid": "64ab871b-14a3-47df-9b80-368e29fe8181",
    "txHash": "8a54d58ca4100112a5430818776d74898f2232770bae03046862575cb851a042",
    "vout": "2"
  }
}
Request Body Example for ERROR_REPORT callbackType
{
  "callbackType": "ERROR_REPORT",
  "data": {
    "verificationUuid": "64ab871b-14a3-47df-9b80-368e29fe8182",
    "result": "ERROR",
    "reason": "BLACKLISTED",
    "message": "Originator is included in the blacklist."
  }
}
Request Body Example for CHAINALYSIS_KYT_RESULT callbackType
{
  "callbackType": "CHAINALYSIS_KYT_RESULT",
  "data": {
    "verificationUuid": "69a310e6-810f-4a31-83d1-bcdafccf5304",
    "riskAssessment": {
      "chainalysisKYT": {
        "counterpartyVaspId": "15952089931162059995",
        "apiType": "ATTEMPT",
        "userId": "15952089931162059995",
        "direction": "OUTGOING",
        "network": "ETHEREUM",
        "asset": "ETH",
        "amount": "1",
        "usdPrice": "1820.17",
        "outputAddress": "bb3fd383d1c5540e52ef0a7bcb9433375793aeaf",
        "timestamp": "2023-05-18T12:39:44.000Z",
        "externalId": "79382ac9-c7be-3fab-ad56-8c61c654e2fc",
        "status": "PROCESSED",
        "alertCount": 1,
        "createdAt": "2023-05-18T12:39:46.000Z",
        "assessedAt": "2023-05-18T12:39:45.263Z"
      },
      "chainalysisKYTAlerts": [
        {
          "counterpartyVaspId": "15952089931162059995",
          "externalId": "79382ac9-c7be-3fab-ad56-8c61c654e2fc",
          "direction": "OUTGOING",
          "alertId": "118b8cc8-f579-11ed-b86d-a3210c6ca9b8",
          "alertLevel": "MEDIUM",
          "entityCategory": "high risk exchange",
          "serviceName": "HIGH RISK EXCHANGE: SimpleSwap.io bb3fd383d1c5540e52ef0a7bcb9433375793aeaf",
          "exposureType": "DIRECT",
          "alertAmount": "1820.17",
          "createdAt": "2023-05-18T12:39:52.461Z"
        }
      ]
    }
  }
}
Request Body Example for REFINITIV_WCO_RESULT callbackType
{
  "callbackType": "REFINITIV_WCO_RESULT",
  "data": {
    "verificationUuid": "69a310e6-810f-4a31-83d1-bcdafccf5304",
    "riskAssessment": {
      "refinitivWorldCheckOne": {
        "counterpartyVaspId": "15952089931162058999",
        "direction": "INCOMING",
        "caseSystemId": "5jb7r2c9xjfk1hoc95gfayv6m",
        "status": "PROCESSED",
        "matchStrength": "EXACT",
        "aggregatedSummaryResult": "{\"caseId\":\"69a310e6-810f-4a31-83d1-bcdafccf5304-INCOMING-1684413585757\", ... }}}",
        "createdAt": "2023-05-18T12:39:48.000Z",
        "assessedAt": "2023-05-18T12:39:57.834Z"
      }
    }
  }
}
Field Name
Data Type
Required
Description

callbackType

string

true

A value that distinguishes how the Callback API was invoked in a given situation. (Refer to the explanation below)

The data format varies depending on the callbackType. (Refer to the sample code above)

data

object

true

The data format varies depending on the callbackType. (Refer to the sample code above)

  • callbackType field specification is as follows.

    • VERIFICATION_RESULT: Callback for result notification of past verification request

    • TX_REPORT: Callback for transaction result report from originating VASP

    • ERROR_REPORT: Callback for error report from originating VASP

    • CHAINALYSIS_KYT_RESULT: Callback for result of risk assessment with Chainalysis KYT API

    • REFINITIV_WCO_RESULT: Callback for result of risk assessment with Refinitiv WCO API

  • data.reason field specification is as follows.

  • The field is valid only when result the field is DENIED.

  • Refer to the below table for the message field value.

reason (string)
result (string)
message (string)
Description

UNKNOWN-SYMBOL

DENIED

The value of symbol name (which is not supported in VASP)

Unknown or not supported asset symbol

UNKNOWN-NETWORK

DENIED

The value of network name (which is not supported in VASP)

Unknown or not supported blockchain network (i.e. symbol matches but network does not)

UNKNOWN-ADDRESS

DENIED

The unknown wallet address

Unknown wallet address to the VASP

LACK-OF-INFORMATION

DENIED

A comma(,) separated required but missing personal information fields list

Verification denied due to lack of personal information

UNAVAILABLE-INFORMATION

DENIED

A comma(,) separated undeliverable personal information field list

Requested personal information cannot be transferred for processing

BLACKLISTED

DENIED

-

Verification denied by problems in sanction screening

UNVERIFIED-KYC

DENIED

-

User KYC required

MISMATCHED-NAME

DENIED

-

Name mismatch

NOT-ALLOWED

DENIED

The reason why it is not allowed

The originating VASP reject the user's withdrawal request for any reason.

UNDEFINED-ERROR

DENIED

Error description

Unexpected exceptional case happens

BENEFICIARY-ACCOUNT-NOT-MATCHED

ERROR

-

Beneficiary address is mismatched by VASP

REQUEST-TIMEOUT

ERROR

-

Verification processing exceeds the timeout limit

Response Body

Response Body Examples

  • 200 OK

{
  "result": true
}
Field Name
Data Type
Required
Example
Description

result

boolean

true

true

The Result value. (An error is not returned.)

PreviousTransaction Status QueryNextDecrypting Database Encryption Key

Last updated