Convert XAF/XOF Wallet to USD

Overview

POST /partner/wallets/xaf-usd-conversion debits amount (in the source wallet’s currency) from the source wallet’s payin_balance, and credits the converted amount — minus any destination fee — to your USD wallet’s balance. Unlike the dashboard’s internal wallet-transfer flow, this endpoint takes only the amount: the exchange rate and fee are computed and applied entirely server-side, from your company’s configured rate and fee tables. There is nothing for you to calculate or pass in beyond the amount. Currently this is the only supported conversion corridor: XAF or XOF → USD. Other currency pairs are not available through this endpoint.

When to use it

Phase “fund your USD wallet” in an integration: convert local-currency float (XAF/XOF) into USD to fund card issuance.

Prerequisites

An active wallet in XAF or XOF with sufficient payin_balance, and an active USD wallet, both belonging to your company.
An exchange rate configured for your company.

Request

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <access_token>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Any string unique to this conversion attempt. Retrying with the same key returns the original result instead of converting twice — recommended for network retries.

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 — Conversion successful

{
  "success": true,
  "message": "Wallet conversion successful",
  "data": {
    "reference": "CONVERT_1759399200000_a1b2c3d4e5f6",
    "sourceWallet": {
      "id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "currency": "XAF",
      "balanceBefore": 100000,
      "balanceAfter": 50000,
      "amountDebited": 50000
    },
    "destinationWallet": {
      "id": "w9f8e7d6-c5b4-3210-fedc-ba0987654321",
      "currency": "USD",
      "balanceBefore": 0,
      "balanceAfter": 77.63,
      "grossAmount": 78.13,
      "feeAmount": 0.5,
      "netAmountCredited": 77.63
    },
    "exchangeRate": {
      "rate": 640,
      "fromCurrency": "USD",
      "toCurrency": "XAF"
    }
  }
}

Field	Type	Description
`data.reference`	string	Unique reference for this conversion. Use for reconciliation.
`data.sourceWallet.amountDebited`	number	Amount removed from the source wallet’s `payin_balance`.
`data.destinationWallet.netAmountCredited`	number	Amount actually added to the USD wallet’s `balance` (after fee).
`data.exchangeRate.rate`	number	Rate applied (`1 <fromCurrency> = <rate> <toCurrency>`).

Error responses

Status	`message` example	Trigger
`400`	`"Amount must be positive"`	`amount <= 0`.
`400`	`"Cannot transfer to the same wallet"`	`source_wallet_id` equals `destination_wallet_id`.
`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`	`"Insufficient payin_balance in source wallet. Available: X, Required: Y"`	Not enough balance to cover the requested amount.
`400`	`"No active exchange rate found for USD to XAF. Please contact support."`	No exchange rate configured for your company.
`429`	Rate limited	More than 20 conversions/minute from the same API token.

Code examples

cURL

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

Node.js (axios)

const { randomUUID } = require("crypto");

const { data } = await axios.post(
  "https://api.cartevo.co/api/v1/partner/wallets/xaf-usd-conversion",
  {
    source_wallet_id: "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
    destination_wallet_id: "w9f8e7d6-c5b4-3210-fedc-ba0987654321",
    amount: 50000,
  },
  {
    headers: {
      Authorization: `Bearer ${token}`,
      "Idempotency-Key": randomUUID(),
    },
  }
);
console.log(data.data.destinationWallet.netAmountCredited);

POST /partner/wallets/preview-conversion — preview the rate/fee before converting.
GET /wallets — list your wallets and their IDs.
GET /wallet/usd-balance — check your USD balance after conversion.

API documentation

Auth

Cards

Customers

Wallets

Payment Collection

Webhook

Overview

When to use it

Prerequisites

Request

Headers

Body

Response

200 — Conversion successful

Error responses

Code examples

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Body

​Response

​200 — Conversion successful

​Error responses

​Code examples

​Related

Overview

When to use it

Prerequisites

Request

Headers

Body

Response

200 — Conversion successful

Error responses

Code examples

Related