User Verification

User verification API

POST VEGA_VERIFICATION_API_PATH

Enclave Environment Value:

Enter the User Verification API endpoint in the VEGA_VERIFICATION_API_PATH field.

VASP performs both the roles of Originating VASP and Beneficiary VASP.
This API is invoked when VASP is acting as the Beneficiary VASP. It is called when a verification request for the Beneficiary is made before conducting a withdrawal from the Originating VASP to your VASP (Beneficiary VASP).
The API needs to handle the below:
- Verify the Beneficiary's name.
- Verify the Beneficiary's address (account number or wallet address).
- Verify KYC authentication.
- Verify AML authentication.
- Perform STR monitoring or sanction screening for the Originator.
- Beneficiary VASP may conduct additional filtering or verification processes for the provided personal information of the Originator/Beneficiary.
If User Verification is successfully completed, Beneficiary VASP can return additional personal information for the Beneficiary in the IVMS101 messaging format.

Response Time Requirement

This User Verification Request API should respond within 5 seconds at most.

Implementation Policy:

This is a guide to verifying beneficiary name when implementing user verification API.
- If the amount of virtual assets to be transferred is smaller than the amount set by the law, it is not subject to travel rules, so verification through VerifyVASP is not required.
- However, if you want to process all withdrawal requests through VerifyVASP, it is difficult to verify the user at the same level if the amount exceeds the amount set by the law or if it is not.
- The beneficiary VASP does not perform matching verification on the beneficiary's name if it is less than the amount stipulated by law (isExceedingThreshold is false).
When implementing the user verification API, all information requested by the originating VASP (requiredBeneficiaryInfo) must be entered.
- If the originating VASP does not have the requested information or does not want to provide it, it returns verificationResult as DENIED and reason as UNAVAILABLE-INFORMATION.
- Any information not requested by Originating VASP will not be filled out. Only fill in the information requested (in requiredBeneficiaryInfo).
- The beneficiary account number must be returned without modification. Changing your wallet address may result in incorrect deposits. If the deposit address is incorrect, a DENIED result should be returned.
When verifying originator in the user verification API, if the required personal information is insufficient, the following will be processed.
- Return verificationResult as DENIED and LACK-OF-INFORMATION as reason. It then returns a list of privacy codes indicating which information is missing in the message field.

Request Header

Field Name

Description

Authorization

Bearer <VEGA_VERIFICATION_AUTHORIZATION_TOKEN>

Request Body

assetInfo.network field is optional. In the case of a virtual asset that is distributed across multiple blockchain networks, such as USDT, which is distributed across Ethereum, BSC, and Solana, the following responses can be returned if the counter-VASP calls API without Network Field.
- The result can be returned as DENIED and the reason as UNKNOWN-NETWORK. However, if the counterparty VASP has not yet implemented network field, the success rate may decrease.
- Alternatively it can be assumed that the network in use is same as your VASP and return the verification result. In such cases, do take note that, if the network your VASP support is different from the counterparty VASP, the virtual asset may be transferred via a wrong network and may become unretrievable.
VASP can decide which response to return. Different policies on returning response to each counterparty VASP are available. Please consider various scenarios of returning response to counterparty VASP when implementing Network Field.

Request Body Examples

Request body for Natural Person

{
  "verificationUuid": "4bc03a8f-5679-4358-815c-906aae5557f4",
  "assetInfo": {
    "symbol": "ETH",
    "network": "Ethereum",
    "amount": "0.024",
    "isExceedingThreshold": true,
    "tradePrice": "2193200",
    "tradeCurrency": "KRW",
    "tradeISODatetime": "2022-02-06T23:13:43.513Z"
  },
  "requiredBeneficiaryInfo": "ACCOUNT_NUMBER,NATURAL_PERSON_NAME",
  "originatingVaspId": "123456789098765",
  "version": "1.0",
  "ivms101": {
    "originator": {
      "originatorPersons": [
        {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "James",
                  "secondaryIdentifier": "Din",
                  "nameIdentifierType": "LEGL"
                }
              ]
            }
          }
        }
      ],
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9a"]
    },
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "James",
                  "nameIdentifierType": "LEGL"
                }
              ]
            }
          }
        }
      ],
      "accountNumber": ["0xb0bFf9721871e22653358956cf59a5FdBF3D752F"]
    }
  }
}

Request Body for Legal Person (please select and use appropriate data fields that are aligned with your organization's policies.)

{
  "verificationUuid": "4g8745d4-1458-3548-458c-906aarkdoi9345",
  "assetInfo": {
    "symbol": "ETH",
    "amount": "0.743",
    "isExceedingThreshold": true,
    "tradePrice": "1845.45",
    "tradeCurrency": "USD",
    "tradeISODatetime": "2024-01-06T23:13:43.513Z"
  },
  "requiredBeneficiaryInfo": "ACCOUNT_NUMBER,LEGAL_PERSON_NAME,LEGAL_PERSON_NATIONAL_IDENTIFICATION,LEGAL_PERSON_COUNTRY_OF_REGISTRATION,LEGAL_PERSON_CUSTOMER_IDENTIFICATION,HEAD_OFFICE_GEOGRAPHIC_ADDRESS,LEGAL_PERSON_DATE_OF_BIRTH",
  "originatingVaspId": "123456789098765",
  "version": "1.0",
  "ivms101": {
    "originator": {
      "originatorPersons": [
        {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "VerifyVASP Pte. Ltd., ",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ],
              "localNameIdentifier": [
                {
                  "legalPersonName": "VerifyVASP Pte. Ltd.,",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType": "GEOG",
                "townName": "MAPLETREE ANSON",
                "addressLine": ["60 Anson Rd", "#17-00"],
                "country": "SG"
              }
            ],
            "nationalIdentification": {
              "nationalIdentifier": "458978-458756",
              "nationalIdentifierType": "RAID"
            },
            "customerIdentification": "1234569999",
            "countryOfRegistration": "SG",
            "dateOfBirth": "2010-03-02"
          }
        }
      ],
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9a"]
    },
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "VerifyVASP Pte. Ltd.,",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            }
          }
        }
      ],
      "accountNumber": ["0xb0bFf9721871e22653358956cf59a5FdBF3D752F"]
    }
  }
}

Field Name

Data Type

Required

Example

Description

verificationUuid

string

true

"4bc03a8f-5679-4358-815c-906aae5557f4"

Unique identifier of the verification request

assetInfo

object

true

Refer to the example below

Information of the virtual asset

assetInfo.symbol

string

true

“ETH”

VA. Virtual Asset. The symbol of the virtual asset

assetInfo.network

string

false

"Ethereum"

The name of the blockchain network on which the VA will be transferred (see the 'NETWORK field guide' under the 'Supplement' menu for details)

assetInfo.amount

string

true

“0.024”

The amount of virtual asset

assetInfo.isExceedingThreshold

boolean

true

true or false

Flag field showing whether the withdrawal exceeds the amount the law states ($1,000 or 1,000,000 KRW).

assetInfo.tradePrice

string

true

“2439800”

The amount of VA converted into legal currency

assetInfo.tradeCurrency

string

true

“KRW”

The currency code used to convert VA into legal currency

assetInfo.tradeISODatetime

string

true

“2022-02-06T23:13:43.513Z”

The time at which VA was converted into legal currency. In any ISO date-time format.

requiredBeneficiaryInfo

string

true

"NATURAL_PERSON_NAME,ACCOUNT_NUMBER"

List of Beneficiary's personal information fields required by the Originating VASP (refer to the user personal information type codes in the Links section at the bottom of the page).

originatingVaspId

string

true

"123456789098765"

vasp ID of the Originating VASP

version

string

true

“1.0”

version information of the ivms101 format (Currently 1.0)

ivms101

object

true

Information of the originator and beneficiary in ivms101 format. Refer to the IVMS101 specification document and guide document.

ivms101.originator

object

true

Originator Information

ivms101.beneficiary

object

true

Beneficiary Information

ivms101.beneficiary.beneficiaryPersons

array

true

Personal information of the beneficiary.

ivms101.beneficiary.accountNumber

array

true

[”0x5811001506550d8356a215be229c15b6ef371a9a”]

Account information of the beneficiary (wallet address)

Response Body

Response Body Examples

Response Body for Natural Person - 200 OK

{
  "result": "VERIFIED",
  "reason": "OK",
  "message": "",
  "ivms101": {
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "James",
                  "nameIdentifierType": "LEGL"
                }
              ],
              "localNameIdentifier": [
                {
                  "primaryIdentifier": "김재원",
                  "nameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType": "GEOG",
                "townName": "Seoul",
                "addressLine": ["14 Teheran-ro 4-gil, Gangnam-gu", "4th floor"],
                "country": "KR"
              }
            ],
            "nationalIdentification": {
              "nationalIdentifier": "12345-67890",
              "nationalIdentifierType": "IDCD"
            },
            "customerIdentification": "1234569999",
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "1985-03-14",
              "placeOfBirth": "Nonsan"
            },
            "countryOfResidence": "KR"
          }
        }
      ],
      "accountNumber": ["0xb0bFf9721871e22653358956cf59a5FdBF3D752F"]
    }
  }
}

Response Body for both Natural Person and Legal Person - 200 OK

{
  "result": "DENIED",
  "reason": "UNVERIFIED-KYC"
}

Response Body for Legal Person (please select and use appropriate data fields that are aligned with your organization's policies.) - 200 OK

{
  "result": "VERIFIED",
  "reason": "OK",
  "message": "",
  "ivms101": {
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "VerifyVASP Pte. Ltd.,",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ],
              "localNameIdentifier": [
                {
                  "legalPersonName": "VerifyVASP Pte. Ltd.,",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType": "GEOG",
                "townName": "MAPLETREE ANSON",
                "addressLine": ["60 Anson Rd", "#17-00"],
                "country": "SG"
              }
            ],
            "nationalIdentification": {
              "nationalIdentifier": "458978-458756",
              "nationalIdentifierType": "RAID"
            },
            "customerIdentification": "145864658",
            "countryOfRegistration": "SG",
            "dateOfBirth": "2010-03-02"
          }
        }
      ],
      "accountNumber": ["0xb0bFf9721871e22653358956cf59a5FdBF3D752F"]
    }
  }
}

Field Name

Data Type

Required

Example

Description

result

string

true

“VERIFIED”

User verification result. Refer to the explanation below.

reason

string

true

“OK”

Error code displaying the reason if verification fails. "OK" if successful.

message

string

false

Message description for the error code

version

string

false

"1.0”

Version information of the IVMS101 format

ivms101

object

true

The beneficiary information which is defined in IVMS101 format. More information can be added upon the information sent from the originating VASP.

ivms101.beneficiary

object

true

Beneficiary information

ivms101.beneficiary.beneficiaryPersons

array

true

Personal information of the beneficiary

ivms101.beneficiary.accountNumber

array

true

Account information of the beneficiary

result field specification is as follows.
- One of “VERIFIED”, ”DENIED” and ”ERROR”.
- VERIFIED: Verification is successful, and there is no problem with the user.
- DENIED: The wallet addresses are correct, but one of the users (including the originator) has a problem (e.g. lack of KYC credential).
- ERROR: Other undefined errors.
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 having 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
Undefined errors

User Verification