Currency Conversion

With a single endpoint, you can convert between any 2 available currencies.

Authorization	Set to Bearer SECRET_KEY
Content-Type	Set value to application/json

The secret key can be gotten from the 'Settings' page on your Startbutton dashboard.

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

BaseUrls

PROD : https://api.startbutton.tech

DEV/ Staging: https://api.startbutton.builditdigital.co

Endpoint

POST: {{baseurl}}/transaction

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:

Required Param

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

Sample responses:

Success

{
    "success": true,
    "message": "new transaction initialized",
    "data": {
        "conversionTimeInHours": 24,
        "transactionReference": "cexxxxx",
        "status": "initiated"
    }
}

Insufficient balance

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

Webhook for Conversions

To learn how Webhook works, kindly see here

Supported events for Conversion :

1. conversion.successful

2. conversion.pending

3. conversion.failed

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
  }
}

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
  }
}

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
  }
}