# Currency conversion API

## Usage

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

<figure><img src="https://1419689564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFdTKNedABvGBtqJRHWA0%2Fuploads%2FPsTtd3CHTOHQG7NGeuRi%2FScreen%20Shot%202023-12-27%20at%2017.31.31.png?alt=media&#x26;token=497c5e24-22b1-433e-a059-1a76e63a65f8" alt="" width="563"><figcaption><p>Conversion flow</p></figcaption></figure>

* Step 1: Merchant calls [GetExchangeRate API](https://docs.neox.vn/docs/disbursement/integration/get-exchange-rate-api) 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](https://docs.neox.vn/docs/disbursement/event-notification#notifies-about-currency-exchanged).

## API

* Path: */v2/dib/exchange/{srcCurrency}-(dstCurrency}*
* Method: POST
* Request: Content-Type: application/json&#x20;
* 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="../event-notification#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>