Skip to main content
POST
Amount conversion

Overview

POST /company/exchange-rates/convert returns a quote for converting an amount between two currencies, using the exchange rates configured for your company. This call is read-only — it does not move any money. To execute a conversion, follow up with POST /wallets/deposit, passing the rate returned here.

When to use it

  • Show a customer or operator the converted amount before they confirm a wallet-to-wallet conversion.
  • Compute the destination amount before calling POST /wallets/deposit.

Where rates come from

The rate returned is your company’s configured rate for the (fromCurrency, toCurrency) pair, not a system-wide market rate. If you have not configured a rate, the call returns 400. Configure rates via the dashboard (or via the company exchange-rate management endpoints).

Quote validity

The returned quote includes an exchangeRateId reflecting the rate version used. Quotes do not have a built-in expiry, but Cartevo treats stale rates conservatively — if the underlying rate is updated, the original exchangeRateId is no longer accepted by POST /wallets/deposit. Treat quotes as good for a few minutes and re-quote before applying for long-running flows.

Prerequisites

  • Authenticated as a company user.
  • An exchange rate is configured for the (fromCurrency, toCurrency) pair.

Request

Headers

Body

Response

200 — Success

Worked example

For amount = 600000 XAF, fromCurrency = "XAF", toCurrency = "USD", with rate = 0.001667:

Error responses

Code examples

cURL
Node.js (axios)

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
fromCurrency
string
required
Example:

"XAF"

toCurrency
string
required
Example:

"USD"

amount
number
required
Example:

1000

Response

200 - application/json

Conversion result

success
boolean
Example:

true

data
object