Convert Currency (Quote) - Cartevo Documentation

Amount conversion

curl --request POST \
  --url https://api.cartevo.co/api/v1/company/exchange-rates/convert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromCurrency": "XAF",
  "toCurrency": "USD",
  "amount": 1000
}
'

{
  "success": true,
  "data": {
    "convertedAmount": 1.63,
    "rate": 0.00163,
    "exchangeRateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

POST

company

exchange-rates

convert

Amount conversion

curl --request POST \
  --url https://api.cartevo.co/api/v1/company/exchange-rates/convert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromCurrency": "XAF",
  "toCurrency": "USD",
  "amount": 1000
}
'

{
  "success": true,
  "data": {
    "convertedAmount": 1.63,
    "rate": 0.00163,
    "exchangeRateId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

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

Name	Required	Description
`Authorization`	Yes	`Bearer <access_token>`
`Content-Type`	Yes	`application/json`

Body

Field	Type	Required	Constraints	Description
`amount`	number	Yes	> `0`	Amount to convert, in `fromCurrency` units.
`fromCurrency`	string	Yes	Exactly 3 chars (ISO 4217)	Source currency.
`toCurrency`	string	Yes	Exactly 3 chars (ISO 4217)	Target currency.

{
  "amount": 600000,
  "fromCurrency": "XAF",
  "toCurrency": "USD"
}

Response

200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "Conversion quoted successfully",
  "data": {
    "convertedAmount": 1000,
    "rate": 0.001667,
    "exchangeRateId": "er_5b7c9d2e4f6a8b1c3d5e7f9a",
    "fromCurrency": "XAF",
    "toCurrency": "USD"
  }
}

Field	Type	Description
`convertedAmount`	number	The result: `amount × rate`, in `toCurrency` units.
`rate`	number	Multiplier: `convertedAmount = amount × rate`. So `1 fromCurrency = rate × toCurrency`.
`exchangeRateId`	string	Identifier of the rate version used. Pass to `POST /wallets/deposit` to apply this exact rate.
`fromCurrency`	string	Echoes the request.
`toCurrency`	string	Echoes the request.

Worked example

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

convertedAmount = 600000 × 0.001667 = 1000.20 USD

Error responses

Status	`message` example	Trigger
`400`	`"No exchange rate configured for XAF → USD"`	Your company has no configured rate for the requested pair.
`400`	`"fromCurrency must be exactly 3 characters"`	Field validation failed.
`400`	`"User does not belong to any company"`	Token has no associated company (rare; should not happen for partner tokens).

Code examples

cURL

curl -X POST https://api.cartevo.co/api/v1/company/exchange-rates/convert \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 600000,
    "fromCurrency": "XAF",
    "toCurrency": "USD"
  }'

Node.js (axios)

const { data } = await axios.post(
  "https://api.cartevo.co/api/v1/company/exchange-rates/convert",
  { amount: 600000, fromCurrency: "XAF", toCurrency: "USD" },
  { headers: { Authorization: `Bearer ${token}` } }
);
console.log(`${data.data.convertedAmount} USD at rate ${data.data.rate}`);

POST /wallets/deposit — apply a quote and actually move funds.
Glossary → Wallet

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

Show child attributes

​Overview

​When to use it

​Where rates come from

​Quote validity

​Prerequisites

​Request

​Headers

​Body

​Response

​200 — Success

​Worked example

​Error responses

​Code examples

​Related

Authorizations

Body

Response

Overview

When to use it

Where rates come from

Quote validity

Prerequisites

Request

Headers

Body

Response

200 — Success

Worked example

Error responses

Code examples

Related