> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/disbursement/integration/currency-conversion-api.md).

# Currency conversion API

## Usage

* This is the API to convert a currency to VND.
* Sequence Diagram

<figure><img src="/files/UcDu8AMBEcSycZiutU9D" alt="" width="563"><figcaption><p>Conversion flow</p></figcaption></figure>

* Step 1: Merchant calls [GetExchangeRate API](/docs/disbursement/integration/get-exchange-rate-api.md) to get list of exchange rates.
* Step 2: Merchant call Exchange API. If returned status is PASSED, NeoX will process

  the request and notify the result via [webhook](/docs/disbursement/integration/event-notification.md#notifies-about-currency-exchanged).

## API

* Path: */v2/dib/exchange/{srcCurrency}-(dstCurrency}*
* Method: POST
* Request: Content-Type: application/json
* Url Params:

  *srcCurrency*: Currency code supported by NeoX.

  *dstCurrency*: Only support VND in this version.

Ex: */v2/dib/exchange/USD-VND*

### Request

<table><thead><tr><th width="159.33333333333334">Parameter</th><th width="130">Data Type</th><th width="100" data-type="checkbox">Require</th><th>Description</th></tr></thead><tbody><tr><td>requestId</td><td>String</td><td>true</td><td><p>UUID is generated by merchant. (Unique)</p><p>Exp:“90e7340b-5cbe-4ce7-886f-55181040af4f”</p></td></tr><tr><td>amount</td><td>Number</td><td>true</td><td>The amount</td></tr><tr><td>currency</td><td>String</td><td>true</td><td>The currency of the amount (srcCurrency or dstCurrency) is used for calculating the origin amount and target amount</td></tr><tr><td>description</td><td>String (256)</td><td>false</td><td>Description</td></tr></tbody></table>

### Response

<table><thead><tr><th width="139.33333333333334">Field name</th><th width="203">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>code</td><td>Number</td><td>System’s error code</td></tr><tr><td>message</td><td>String</td><td>Error description</td></tr><tr><td>data</td><td>Object</td><td>Exchange response data below.</td></tr></tbody></table>

Exchange response data:

<table><thead><tr><th width="137.33333333333334">Field name</th><th width="206">Data Type</th><th>Description</th></tr></thead><tbody><tr><td>requestId</td><td>String</td><td>requestId in the exchange request.</td></tr><tr><td>status</td><td>String</td><td><em>PASSED</em>: Request successfully. Wait for result notification through <a href="/pages/OfdtvWaTdlaGsfu11tPF#notifies-about-currency-exchanged">webhook</a>.<br><em>FAILED</em>: Submit request failed.</td></tr><tr><td>code</td><td>Number</td><td>Logic's error code</td></tr></tbody></table>