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

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"]
    }
  }
}

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"]
    }
  }
}

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

Links

About IVMS101 Format Definition

IVMS101 Message Guide

IVMS101 Codes for types of personal information

• Visit the below page for requiredBeneficiaryInfo field in Request Body.

• If the error reason of LACK-OF-INFORMATION is returned, refer to the below page for the message field.