User Account Verification

User Account Verification API

POST VEGA_VERIFICATION_ACCOUNT_API_PATH

Enclave Environment Variable:

Enter the User Account Verification API endpoint in VEGA_VERIFICATION_ACCOUNT_API_PATH field.

Every VASP can be either the originating and beneficiary VASP

This API is called when the VASP performs the role of the beneficiary VASP.

The API is called to verify that the beneficiary address (wallet address, account number) entered by the originator belongs to the beneficiary address (and VASP).

Response Time Standard

This API must respond in 1 second.

Implementation Standards

• IVMS101 format of beneficiary information.

• This API only verifies the existence of a wallet address and name. KYC or Sanction Screening process is not covered by this API.

• This API is designed for only for single account verification. In order to verify multiple accounts, make one of this API call per account.

• For a corporation account, if there are multiple representatives but only one is matched, the result will be returned as VERIFIED.

Request Header

Field Name	Description
Authorization	Bearer <VEGA_VERIFICATION_AUTHORIZATION_TOKEN>

Request Body

Request Body Examples

• When only verifying the beneficiary's wallet address

{
  "originatingVaspId": "15952089931162060684",
  "symbol": "ETH",
  "network": "Ethereum",
  "version": "1.0",
  "ivms101": {
    "beneficiary": {
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
    }
  }
}

• When verifying the beneficiary's name and wallet address (when withdrawing more than the mandated threshold of the jurisdiction)

{
  "originatingVaspId": "15952089931162060684",
  "symbol": "ETH",
  "network": "Ethereum",
  "version": "1.0",
  "ivms101": {
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "Taylor",
                  "secondaryIdentifier": "Robbins",
                  "nameIdentifierType": "LEGL"
                }
              ]
            }
          }
        }
      ],
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
    }
  }
}

• When verifying the wallet address of a legal person

{
  "originatingVaspId": "15952089931162060684",
  "symbol": "ETH",
  "network": "Ethereum",
  "version": "1.0",
  "ivms101": {
    "beneficiary": {
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
    }
  }
}

• When verifying the name and wallet address of a legal person (when withdrawing more than the mandated threshold of the jurisdiction)

{
  "originatingVaspId": "15952089931162060684",
  "symbol": "ETH",
  "network": "Ethereum",
  "version": "1.0",
  "ivms101": {
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "A Company",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            }
          }
        },
        {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "Taylor",
                  "secondaryIdentifier": "Robbins",
                  "nameIdentifierType": "LEGL"
                }
              ]
            }
          }
        }
      ],
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
    }
  }
}

Field Name	Data Type	Required	Example	Description
originatingVaspId	string	true	"15952089931162060684"	Verification requester VASP ID
symbol	string	true	"ETH"	Symbol of Virtual Asset.
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)
version	string	true	"1.0"	IVMS101 format version (use 1.0 currently)
ivms101	object	true	-	Verification information in IVMS101 format
ivms101.beneficiary	object	true	-	Beneficiary information object
ivms101.beneficiary.beneficiaryPersons	array	false	[{"naturalPerson":{"name":{"nameIdentifier":[{"primaryIdentifier":"Taylor","secondaryIdentifier":"Robbins","nameIdentifierType":"LEGL"}]}}}]	The name information of beneficiary: this field is required when the amount exceeds the legal threshold. If presented, the name must be matched to the wallet owner's name.
ivms101.beneficiary.accountNumber	array	true	[”0x5811001506550d8356a215be229c15b6ef371a9a”]	The wallet address of the beneficiary. The type of the field is an array but it is NOT allowed to pass multiple accounts in it: use this API just for single account verification and call multiple times if required.

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

Response Body

Response Body Examples

• 200 OK

{
  "accountVerificationResult": "VERIFIED",
  "verifiedAt": "2022-03-03T21:52:08.092Z"
}

• 200 OK

{
  "accountVerificationResult": "DENIED",
  "reason": "UNKNOWN-SYMBOL",
  "verifiedAt": "2022-03-03T21:52:08.092Z"
}

Field Name	Data Type	Required	Example	Description
accountVerificationResult	string	true	"DENIED"	The result of the verification
reason	string	false	"UNKNOWN-ADDRESS"	The reason field means that the detailed error code for when accountVerificationResult is DENIED
verifiedAt	string	true	"2022-03-03T21:52:08.092Z"	The verification datetime

• accountVerificationResult field can be "VERIFIED" or "DENIED"

  • VERIFIED: Successfully verified account in beneficiary VASP.

  • DENIED: Unknown account or name, not verified on beneficiary VASP side.

• reason field specification is as follows.

  • The field is valid only when result 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
MISMATCHED-NAME	DENIED	-	Name mismatch
UNDEFINED-ERROR	DENIED	Error description	Undefined errors

Links

A guideline to the ways to enter IVMS101 information

IVMS101 Message Format Guide