VerifyVASP
Search
K
Comment on page

Callback API

post
VEGA_VERIFICATION_CALLBACK_API_PATH
Callback API for Verification Result Notification
Enclave Environment Variable:
Enter the Callback API endpoint in VEGA_VERIFICATION_CALLBACK_API_PATH field.
Callback API enables the asynchronous preocessing of verification. Following 3 APIs work asynchronously.
  • User Verification API
  • Transaction Result Report API
  • Error Report API
Here are three typical cases of enclave calling callback API.
  • Enclave recieved a result of the past requested verficiation (callbackType: VERIFICATION_RESULT)
  • Enclave recieved an originating VASP sending report of txHash or txID which is matched to specific verification (callbackType: TX_REPORT)
  • Enclave recieved an originating VASP sending error report of specific verification (callbackType: ERROR_REPORT)
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 Examples
  • VERIFICATION_RESULT
{
"callbackType": "VERIFICATION_RESULT",
"data": {
"verificationUuid": "64ab871b-14a3-47df-9b80-368e29fe8180",
"verificationResult": "UNKNOWN",
"reason": "Unknown address",
"ivms101": {
"originator": {
"originatorPersons": [
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "Jamse",
"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 Exchage",
"legalPersonNameIdentifierType": "LEGL"
}
]
},
"geographicAddress": [
{
"addressType": "GEOG",
"postcode": "234234",
"townName": "Yeoksam-dong",
"addressLine": ["sechogu street", "100-100"],
"country": "KR"
}
],
"nationalIdentification": {
"nationalIdentifier": "123456",
"nationalIdentifierType": "RAID",
"registrationAuthority": "RA000677"
}
}
}
}
}
}
  • TX_REPORT
{
"callbackType": "TX_REPORT",
"data": {
"verificationUuid": "64ab871b-14a3-47df-9b80-368e29fe8181",
"txHash": "0x9fd7afd46e4402c7197b4d8deb0199fcf7c1f57ef70c339f403a1cqwerc31c28"
}
}
  • ERROR_REPORT
{
"callbackType": "ERROR_REPORT",
"data": {
"verificationUuid": "64ab871b-14a3-47df-9b80-368e29fe8182",
"result": "ERROR",
"reason": "BLACKLISTED",
"message": "Originator is included in the blacklist."
}
}
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.
    • Value must be one of "VERIFICATION_RESULT", "TX_REPORT", "ERROR_REPORT".
    • 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
  • 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-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 probloems in sanction screening
    UNVERIFIED-KYC
    DENIED
    -
    User KYC required
    MISMATCHED-NAME
    DENIED
    -
    Name mismatch
    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.)