Review an asset transfer authorization request and return the result.
POST
/v1/beneficiary/transfer
A VASP who wants to transfer an asset requests the beneficiary VASP for asset transfer authorization prior to transferring an asset. You shall implement an API to process a request for authorization to transfer this asset.
API Specification
- Decrypt the encrypted payload with its own private key.
- You can check the information of an asset to be transferred, the
Originator
information, and theOriginatingVASP
information, and decide whether to allow the transfer of this asset. Requests from VerifyVASP, theoriginatingVASP
object is outside payload. Please overwrite inside payload -> ivms101. - Check that the beneficiary's address information contained in
Beneficiary
is an address that can actually be received.- ❗️Refer Verify Wallet Address page for how to verify address.
- If there is the beneficiary name in
Beneficiary
, check that it matches the owner of the corresponding address as well. Name information includes both first name and last name only ifprimaryIdentifier
has been defined.- ❗️Refer IVMS 101 Names for how to verify names.
- If necessary, perform sanction screening for the beneficiary address as well.
- Based on this content, store the asset transfer information in DB and assign a
status
value.verified
ordenied
- Create a response based on the result of checking the content of a request message. At this time, use
Originator
,OriginatingVASP
andBeneficiary
object by copying the objects from the request, and create theBeneficiaryVASP
object based on the information of the beneficiary VASP.
Request
For the originator's personal information, as of March 25, 2022, only an individual's name is to be sent for the individual, and only information on the legal person and representative name is to be sent for the legal person.
Name | Required | Type |
---|---|---|
transferId | Required | string |
currency | Required | string |
amount | Required | string |
historicalCost | Optional | string |
tradePrice | Required | string |
tradeCurrency | Required | string |
isExceedingThreshold | Required | string |
originatingVasp | Optional | string |
payload | Required | string |
address | Optional | string |
tag | Optional | string |
network | Optional | string |
transferId: This is a unique identification number for the asset transfer details created by a VASP which wants to transfer an asset. The client who sends a request generates and sends a UUID v4 value.
currency: This is a symbol of the virtual asset you want to transfer. (This is case insensitive.)
amount: This is the total volume of virtual assets you want to transfer
historicalCost: This is an acquisition cost of the virtual asset to be transferred (The requirements of Korea National Tax Service. However, it is not used yet.)
tradePrice: This is the amount of the virtual asset transfer converted to a type of legal tender. If there is no its own price information, convert this using the price API of other VASP.
tradeCurrency: This is a legal tender code, which follows the ISO 4217 standard used when converting to a legal tender. The following currencies can be entered: 'KRW', 'USD', 'EUR', 'JPY', 'CNY', 'GBP', 'CAD', 'AUD', 'HKD', 'SGD'. If you need to use any other currency code, please inform the CODE team! For more details, please refer to the Developer FAQ page.
isExceedingThreshold: Indicates whether the tradePrice
exceeds the Travel Rule threshold specified by law.
This field is input as true
or false
, and if the field value is true
, the Beneficiary
name in the request is compared with the actual name of the Beneficiary
who owns the virtual asset address.
If the field value is true and the Beneficiary
name is missing or different in the request, a 'denied' response is sent.
originatingVasp: For requests from other solutions, an originatingVASP object may be outside payload. In this case, please overwrite the originatingVASP
object outside payload to the ivms101 message of the payload area.
payload: This is an object to contain IVMS101 message. Please refer to IVMS101 Type page.
address: Wallet address of the beneficiary. Since some VASPs integrated with other solutions may required this field, please refer to the Interoperability with Other Protocols page.
tag: Include this if a Tag or Memo exists (e.g., XRP). Since some VASPs integrated with other solutions may required this field, please refer to the Interoperability with Other Protocols page.
network: This is included to distinguish when a single coin exists on multiple networks. Since some VASPs integrated with other solutions may required this field, please refer to the Interoperability with Other Protocols page.
{
"transferId": "string",
"currency": "string",
"amount": "string",
"historicalCost": "",
"tradePrice": "1000001",
"tradeCurrency": "KRW",
"isExceedingThreshold": "true",
"originatingVasp": {},
"payload": "encrypted ivms101 payload"
}
Response
Name | Required | Type |
---|---|---|
result | Required | string |
reasonType | Optional | string |
reasonMsg | Optional | string |
transferId | Required | string |
beneficiaryVasp | Optional | string |
payload | Required | string |
result: This is a result of the previous authorization of the virtual asset.
-verified
: Authorize.
-denied
: Deny to transfer an asset
reasonType: For denied, the type corresponding to the reason.
-NOT_FOUND_ADDRESS
: This is a case where a virtual asset address cannot be found.
-NOT_SUPPORTED_SYMBOL
: This is a currency symbol which cannot be traded.
-NOT_KYC_USER
: This is a case where the owner did not process KYC verification.
-INPUT_NAME_MISMATCHED
: The beneficiary name sent in the request message does not match the actual owner's name.
-SANCTION_LIST
: Virtual asset addresses or owners are subject to the sanction of the beneficiary VASP.
-LACK_OF_INFORMATION
: This is a case where there is no the information necessary to make an asset transfer decision.
-UNKNOWN
: This refers to other reasons.
reasonMsg: message describing the reasonType
transferId: A unique ID is required to track the status of transaction from an asset transfer authorization request through subsequent processes. The client who sends a request generates and sends UUID.
payload(Required): This is an object to contain IVMS101 message. Please refer to IVMS101 Type page.
{
"result": "string",
"reasonType": "",
"reasonMsg": "",
"transferId": "string",
"beneficiaryVasp": {},
"payload": "encrypted ivms101 payload"
}