> For the complete documentation index, see [llms.txt](https://startbutton.gitbook.io/startbutton-product-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://startbutton.gitbook.io/startbutton-product-api/startbutton-api-doc/currency-conversion.md).

# Currency Conversion

<table><thead><tr><th width="224">Authorization</th><th>Set to Bearer SECRET_KEY</th></tr></thead><tbody><tr><td>Content-Type</td><td>Set value to <code>application/json</code></td></tr></tbody></table>

{% hint style="info" %}
The secret key can be gotten from the 'Settings' page on your Startbutton dashboard.&#x20;
{% endhint %}

Post a request to the URL below, where the base URL is determined by the environment you are in.

<details>

<summary>BaseUrl</summary>

Sandbox/PROD: <https://api.startbutton.tech&#x20>;

</details>

{% tabs %}
{% tab title="Endpoint" %}
POST: `{{baseurl}}/transaction`
{% endtab %}
{% endtabs %}

| Param          | Required? | Description                                       |
| -------------- | --------- | ------------------------------------------------- |
| "fromAmount"   | Yes       | This is the amount you want to convert "`from`"   |
| "toCurrency"   | Yes       | This is the currency you want to convert "`to`"   |
| "fromCurrency" | Yes       | This is the currency you want to convert "`from`" |

#### Sample code:

{% tabs %}
{% tab title="Required Param" %}

```
{
    "fromAmount": 1000,
    "toCurrency": "UGX",
    "fromCurrency": "NGN"
}
```

{% endtab %}
{% endtabs %}

#### Sample responses:

{% tabs %}
{% tab title="Success" %}

```
{
    "success": true,
    "message": "new transaction initialized",
    "data": [
        {
            "conversionTimeInHours": 24,
            "transactionReference": "77e27b0d16c8",
            "status": "initiated"
        }
    ]
}
```

{% endtab %}

{% tab title="Insufficient balance" %}

```
{
"success": false,
"message": "User has insufficient balance.",
"data": {}
}
```

{% endtab %}
{% endtabs %}

## **Webhook for Conversions**

{% hint style="info" %}
To learn how Webhook works, kindly see [here](/startbutton-product-api/startbutton-api-doc/webhook.md)
{% endhint %}

**Supported events for Conversion :**

1. conversion.successful
2. conversion.pending
3. conversion.failed

{% tabs %}
{% tab title="Successful " %}

```
{
  "event": "conversion.successful",
  "data": {
    "transaction": {
      "_id": "66xxxxxxxxxxxx",
      "transType": "conversion",
      "status": "successful",
      "fromAmount": 1000,
      "toAmount": 1593050,
      "fromCurrency": "USD",
      "toCurrency": "NGN",
      "merchantId": "65xxxxxxxxxx",
      "transactionReference": "dbxxxxxxx",
      "isRecurrent": false,
      "createdAt": "2024-08-25T23:44:33.513Z",
      "updatedAt": "2024-08-25T23:44:37.346Z",
      "amount": 100000,
      "currency": "USD",
      "feeAmount": null
    },
    "authorizationCode": null
  }
}
```

{% endtab %}

{% tab title="Pending " %}

```
{
  "event": "conversion.pending",
  "data": {
    "transaction": {
      "_id": "66cxxxxxxxxxxxx",
      "transType": "conversion",
      "status": "initiated",
      "fromAmount": 1000,
      "toAmount": 1593050,
      "fromCurrency": "USD",
      "toCurrency": "NGN",
      "merchantId": "65xxxxxxxxxxx",
      "transactionReference": "dbxxxxxxxx",
      "isRecurrent": false,
      "createdAt": "2024-08-25T23:44:33.513Z",
      "currency": "USD",
      "feeAmount": null
    },
    "authorizationCode": null
  }
}
```

{% endtab %}

{% tab title="Failed " %}

```
{
  "event": "conversion.failed",
  "data": {
    "transaction": {
      "_id": "66xxxxxxxxxxxxxxx",
      "transType": "conversion",
      "status": "failed",
      "merchantId": "65xxxxxxxxxxxxx",
      "transactionReference": "f1418761c7ab",
      "isRecurrent": false,
      "createdAt": "2024-08-23T08:41:32.036Z",
      "updatedAt": "2024-08-23T08:41:32.247Z",
      "amount": 1000000,
      "currency": "USD",
      "feeAmount": null
    },
    "authorizationCode": null
  }
}
```

{% endtab %}
{% endtabs %}