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

PreviousVASP API ReferenceNextUser Verification

Last updated