# 08-Asset-Transfer-Data-Request



08-Asset-Transfer-Data-Request [#08-asset-transfer-data-request]

In cases where a transfer with TXID lacks Travel Rule data, preventing the beneficiary VASP from processing the deposit, the beneficiary VASP will call 'Asset Transfer Data Request' API to get the Travel Rule data. Implement the API to handle this request.

Endpoint [#endpoint]

`PUT` `/v1/verification/tx`

API action specification [#api-action-specification]

1. Query for the transaction based on `txid`.
2. Find the information for the withdrawal. The data should include following as '**Asset Transfer Authorization**': `currency`, `amount`, `historicalCost`, `tradePrice`, `tradeCurrency`, `isExceedingThreshold` .
3. Decrypt the payload with your pubkey.
4. Retrieve data from the beneficiary VASP using the asset information, `Beneficiary` information, and `BeneficiaryVASP` information.
5. Just as the 'Asset Transfer Authorization', fill in the `Originator` and `OriginatingVASP` field of the payload base on the originating user information.
6. Store the asset transfer details in the database and assign a status value. It can be designated as either normal or error.
7. Generate a response message based on the results of verifying the contents of the request message. At this point, create the `Originator` and `OriginatingVASP`objects using the KYC information of the originating user, similar to sending an 'Asset Transfer Authorization' request, copy the `Beneficiary`, `BeneficiaryVASP` object directly from the request.

> 📘 **When the originator's KYC information is not available**
>
> If the originator has not completed KYC and identity information is not available, set the 'reasonType' to 'LACK\_OF\_INFORMATION' and provide a detailed reason in 'reasonMsg' in the response to the 'asset transfer data request'. (e.g., 'The user did not finish KYC.')

Request Parameters [#request-parameters]

Body Parameters [#body-parameters]

> **Info**: 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               | Type   | Required | Description                                            |
| :----------------- | :----- | :------- | :----------------------------------------------------- |
| transferId         | string | Required | UUID sent by the Beneficiary VASP requesting the data. |
| txid               | string | Required | Transaction ID (TXID).                                 |
| beneficiaryAddress | string | Required | Beneficiary's wallet address.                          |
| payload            | string | Required | Encrypted ivms101 payload.                             |

**transferId**: The UUID sent by the Beneficiary VASP requesting the data. It should be stored for mutual management purposes.

***

**txid**: It is a unique value used to identify a specific transaction executed on the blockchain for virtual asset transfer. It is unique and generated by the blockchain.

***

**beneficiaryAddress**: Beneficiary's wallet address. Attach secondary addresses like tag or memo after a ':' delimiter.

***

**payload**: An object for containing IVMS101 messages. Please refer to the \[04-IVMS101] page.

Response [#response]

Fields [#fields]

| Name                 | Type   | Description                                    |
| :------------------- | :----- | :--------------------------------------------- |
| result               | string | Request result (`normal`, `error`).            |
| reasonType           | string | Reason code if error (e.g., `NOT_FOUND_TXID`). |
| reasonMsg            | string | Detailed message.                              |
| transferId           | string | The `transferId`.                              |
| currency             | string | Currency symbol.                               |
| amount               | string | Transferred amount.                            |
| historicalCost       | string | Acquisition cost.                              |
| tradePrice           | string | Value in fiat currency.                        |
| tradeCurrency        | string | Fiat currency code.                            |
| isExceedingThreshold | string | `true` if exceeds Travel Rule threshold.       |
| payload              | string | Encrypted ivms101 response message.            |

**result**: Result for a request.

-`normal`: When the request was processed correctly.

-`error`: When the request was not processed. Please designate 'reasonType'.

***

**reasonType**: When the result value is error, a value which identifies the detailed reason.

-`NOT_FOUND_TXID`: When the cannot be found

-`LACK_OF_INFORMATION`: When a required field of IVMS101 was missing.

※If the originator has not completed KYC and their identity information is missing, use 'LACK\_OF\_INFORMATION' as the 'reasonType' in response to the 'asset transfer data request' and include a detailed reason in 'reasonMsg' (e.g., 'The user did not finish KYC.').

-`UNKNOWN`: Others.

***

**reasonMsg**: Describe a detailed message explaining the reasonType.

***

**transferId**: 'transferId' from 'Asset Transfer Data Request' API.

***

**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 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. Please refer to 'tradePrice' calculation below.

***

**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 CodeVASP team! For more details, please refer to the FAQ page.

***

**isExceedingThreshold**: Indicates whether the tradePrice exceeds the Travel Rule threshold specified by law.

***

**payload**: This is an object to contain IVMS101 message. Please refer to \[04-IVMS101] page.

> 📘 'tradePrice' calculation
>
> In the "tradePrice" field, you should enter the value calculated by multiplying the quantity of the asset by its price in fiat currency. In the "tradeCurrency" field, you should specify the type of fiat currency.
> For example, if you are transferring 2 BTC and the price at that moment is 42,708 USD, then the total price is 42,708 USD \* 2 = 85,416 USD. In this case, you value should be as follows:
>
> "tradePrice": "85416",
> "tradeCurrency": "USD",

Examples [#examples]

Request [#request]

```json
{
    "txid" : "311BFF73D9B7969CCF1042186180159C724FAB59013A7A034A93E5FB9D6BAFE6",
    "beneficiaryAddress" : "address:tag",
    "transferId" : "b09c8d00-8da9-11ec-b909-0242ac120002",
    "payload": "encrypted ivms101 payload(Beneficiary.Object,BeneficiaryVASP.Object)"
}
```

Response [#response-1]

```json
{
    "result" : "normal",
    "transferId" : "b09c8d00-8da9-11ec-b909-0242ac120002",
    "currency": "BTC",
    "amount": "0.1",
    "historicalCost": "",
    "tradePrice": "10000",
    "tradeCurrency": "KRW",
    "isExceedingThreshold": "true",
    "payload": "encrypted ivms101 payload"
}
```