Preview Wallet Conversion

Overview

POST /partner/wallets/preview-conversion is a read-only calculation: it returns the exchange rate, gross/net amounts, and fee for converting amount (in the source wallet’s currency) into the destination USD wallet, computed from your company’s configured exchange rate and fee tables. No funds are moved. Call this before POST /partner/wallets/xaf-usd-conversion to show the converted amount to your own user before they confirm.

When to use it

You want to show “You will receive ~$X” before a user confirms a top-up of their USD wallet.
You want to check the current rate without committing to a conversion.

Prerequisites

An active wallet in XAF or XOF, and an active USD wallet, both belonging to your company.
An exchange rate configured for your company (contact support if POST returns a 400 about a missing rate).

Request

Headers

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

Body

Field	Type	Required	Constraints / format
`source_wallet_id`	string	Yes	UUID of a wallet in `XAF` or `XOF`.
`destination_wallet_id`	string	Yes	UUID of your `USD` wallet.
`amount`	number	Yes	Amount to convert, in the source currency, `> 0`.

{
  "source_wallet_id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "destination_wallet_id": "w9f8e7d6-c5b4-3210-fedc-ba0987654321",
  "amount": 50000
}

Response

200 — Preview

{
  "sourceCurrency": "XAF",
  "destinationCurrency": "USD",
  "rate": 640,
  "sourceAmount": 50000,
  "grossAmount": 78.13,
  "feeAmount": 0.5,
  "netAmountToCredit": 77.63
}

Field	Type	Description
`rate`	number	Current exchange rate (destination currency → source currency, e.g. `1 USD = 640 XAF`).
`grossAmount`	number	`sourceAmount / rate`, before fee.
`feeAmount`	number	Fee charged on the destination side (USD), per your fee configuration.
`netAmountToCredit`	number	`grossAmount - feeAmount` — what would actually be credited.

Error responses

Status	`message` example	Trigger
`400`	`"Conversions are only allowed from XAF or XOF wallets. Source wallet currency: ..."`	`source_wallet_id` is not a XAF/XOF wallet.
`400`	`"Conversions can only be made to USD wallets. Destination wallet currency: ..."`	`destination_wallet_id` is not a USD wallet.
`400`	`"Source wallet not found"` / `"Destination wallet not found"`	Wallet ID doesn’t exist or doesn’t belong to your company.
`400`	`"No active exchange rate found for USD to XAF. Please contact support."`	No exchange rate configured for your company.

Code examples

cURL

curl -X POST https://api.cartevo.co/api/v1/partner/wallets/preview-conversion \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_wallet_id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "destination_wallet_id": "w9f8e7d6-c5b4-3210-fedc-ba0987654321",
    "amount": 50000
  }'

POST /partner/wallets/xaf-usd-conversion — actually perform the conversion.
GET /wallets — list your wallets and their IDs.

API documentation

Auth

Cards

Customers

Wallets

Payment Collection

Webhook

Overview

When to use it

Prerequisites

Request

Headers

Body

Response

200 — Preview

Error responses

Code examples

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Body

​Response

​200 — Preview

​Error responses

​Code examples

​Related

Overview

When to use it

Prerequisites

Request

Headers

Body

Response

200 — Preview

Error responses

Code examples

Related