Startbutton Product API
  • Startbutton API doc
    • Get Started
    • Accept Payments
    • Server-to-Server Integration
      • S2S Integration for Virtual Accounts
        • S2S Virtual account (NGN)
        • S2S Virtual account (GHS)
        • S2S EFT (ZAR)
      • S2S Integration for Mobile Money
        • S2S MoMo (KES and GHS)
        • S2S MoMo (TZS and UGX)
        • S2S MoMo (RWF)
        • S2S MoMo XOF and XAF
    • Re-charge Card
    • Subscriptions
    • Payment Links
    • Currency Conversion
    • Get Wallet Balance
    • Transfer
      • Bank List
    • Security Measures.
      • IP Whitelisting
    • Webhook
    • Transaction Status
    • Get FX Rate
    • Under and Overpayments
    • Refunds
      • Refund Transaction Status (TSQ)
    • Available Currencies
    • FAQs
  • Advanced Security
    • Signed Payload for Transfer Requests.
Powered by GitBook
On this page
  1. Startbutton API doc

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-dev.startbutton.tech

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:

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

Sample responses:

{
    "success": true,
    "message": "new transaction initialized",
    "data": {
        "conversionTimeInHours": 24,
        "transactionReference": "cexxxxx",
        "status": "initiated"
    }
}
{
"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

{
  "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
  }
}
{
  "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
  }
}
{
  "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
  }
}
PreviousPayment LinksNextGet Wallet Balance

Last updated 2 months ago