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 ISO 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

Links

About IVMS101 Format Definition

About IVMS101 Standard

IVMS101 Message Guide

IVMS101 Message Format 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.

IVMS101 Personal Data Fields