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.)