> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert XAF/XOF Wallet to USD

> Convert funds from a XAF or XOF wallet into your USD wallet, with the exchange rate and fee computed and verified server-side.

## 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`. |

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

## Response

### 200 — Conversion successful

```json theme={null}
{
  "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

```bash cURL theme={null}
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
  }'
```

```js Node.js (axios) theme={null}
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);
```

## Related

* [`POST /partner/wallets/preview-conversion`](/api-reference/endpoint/post-wallet-conversion-preview) — preview the rate/fee before converting.
* [`GET /wallets`](/api-reference/endpoint/get-wallets) — list your wallets and their IDs.
* [`GET /wallet/usd-balance`](/api-reference/endpoint/get-wallet-usd-balance) — check your USD balance after conversion.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.