User Verification

User verification request

POST http://<enclave-endpoint>/v1/verifications

This API is for Originating VASP to request Beneficiary VASP on verifying Beneficiary

As the verification process works in an asynchronous manner, you can check the result by (1) polling (calling API repeatedly) the result by verificationUuid, or (2) implementing a callback VASP API enabling you to get the result notification.å

Callback option is recommended.

Request Body

Request Body Examples

{
  "keyType": "PerVerification",
  "beneficiaryVaspId": "17104899575711305197",
  "assetInfo": {
    "symbol": "BTC",
    "network": "Bitcoin",
    "amount": "0.024",
    "tradePrice": "100",
    "tradeCurrency": "KRW",
    "tradeISODatetime": "2022-04-20T05:59:42.506Z",
    "isExceedingThreshold": true
  },
  "requiredBeneficiaryInfo": "ACCOUNT_NUMBER,NATURAL_PERSON_NAME",
  "payload": {
    "version": "1.0",
    "ivms101": {
      "originator": {
        "originatorPersons": [
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "James",
                    "secondaryIdentifier": "Din",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              },
              "dateAndPlaceOfBirth": {
                "dateOfBirth": "1987-04-04",
                "placeOfBirth": "New York"
              }
            }
          }
        ],
        "accountNumber": ["1P8j2mhMszoC7P69oqZF2n8fLK3TL3wFgJ"]
      },
      "beneficiary": {
        "beneficiaryPersons": [
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Robbins",
                    "secondaryIdentifier": "Taylor",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": ["1G3qCGKP5dQtQ7secCPTCDPU9Wfjp9x3Hb"]
      }
    }
  }
}

Field Name	Data Type	Required	Description
keyType	string	true	A Public Key type which will be used to encrypt personal information One type of the three ”PerVasp”, “PerEoa”, and “PerVerification” can be chosen. BeneficiaryVASP needs to provide a Public Key corresponding to the key type chosen by the OriginatingVASP.
beneficiaryVaspId	string	true	The Vasp ID of the beneficiary VASP
requiredBeneficiaryInfo	string	true	A list of verification required personal information fields of the beneficiary, separated with comma(,)
assetInfo.symbol	string	true	The symbol of virtual asset
assetInfo.network	string	false	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	Transaction amount in virtual asset
assetInfo.isExceedingThreshold	boolean	true	Flag field showing whether the withdrawal request exceeds the amount the law states.
assetInfo.tradeCurrency	string	true	Legal currency code used when converting to legal currency (ISO 4217 standard)
assetInfo.tradePrice	string	true	Virtual asset amount converted in legal currency. If there is no market price of the VASP, convert via the market price API of other VASPs.
assetInfo.tradeISODatetime	string	true	The standard time at which VA was converted into legal currency in any ISO date-time format
payload	object	true	Information about Originator, Beneficiary, OI, BI IVMS101 format.
payload.version	string	true	A version regarding the IVMS101 message format.
payload.ivms101	object	true	Information about the originator and the beneficiary in ivms101 format Refer to the IVMS101 message protocol. Refer to the IVMS101 message guide document.

Response Body

Success case

Response Body Examples

• 200 OK

{
  "verificationUuid": "8557f2b2-985e-431f-8d52-75c2e5a01e46",
  "createdAt": "2022-04-20T05:59:45.306Z"
}

Field Name	Data Type	Required	Description
verificationUuid	string	true	User verification request ID
createdAt	date	true	Datetime of verification requested

• There are 2 available options to get the verification result.

  • polling : Repeatedly asking for results via Verification Result API while the process is done.

  • Callback API : Implementing the callback API on VASP side and set it as an environment variable in order to make the enclave call the API to notify the result.

Error Codes

Missing mandatory parameter case

Response Body Examples

• 400 Bad Request

{
  "code": "MISSING-REQUIRED-BENEFICIARY-INFO",
  "message": "`requiredBeneficiaryInfo` is required."
}

The invalid value of parameters

Response Body Examples

• 400 Bad Request

{
  "code": "INVALID-REQUIRED-BENEFICIARY-INFO",
  "message": "'requiredBeneficiaryInfo' is required 'ACCOUNT_NUMBER'"
}

The case of using a non-alliance member VASP ID.

Response Body Examples

• 400 Bad Request

{
  "code": "ALLIANCE-NOT-FOUND",
  "message": "Alliance is not found in given vendor"
}

The case of the beneficiaryVaspId of VASP is in inactive status.

Response Body Examples

• 400 Bad Request

{
  "code": "ALLIANCE-NOT-ACTIVE",
  "message": "Alliance is not active now"
}

The case the request processing exceeds the timeout.

Response Body Examples

• 408 Request Timeout

{
  "code": "REQUEST-TIMEOUT",
  "message": "timeout of 5000ms exceeded"
}

Links

IVMS101 Codes for types of personal information fields

• Refer below link to find available codes for the requiredBeneficiaryInfo field in the request payload.

IVMS101 Personal Data Fields