> ## 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. # Deposit Between Wallets (Currency Conversion) > Move funds from one of your wallets to another, with automatic currency conversion and fee deduction. ## Overview `POST /wallets/deposit` moves funds **between two wallets you own**, applying currency conversion and a fee. The `sourceWallet` is debited by `totalAmount` (`amount + feeAmount`); the `destinationWallet` is credited by the converted `amount`. This endpoint is used to internally rebalance your wallets — for example, to convert XAF you collected into USD before issuing cards. > **Note:** This endpoint is **not** a customer-facing payment endpoint. To charge a mobile-money account use [`POST /payment/collect`](/api-reference/endpoint/post-payment-collect) or [`POST /wallets/fund`](/api-reference/endpoint/post-wallets-fund). ## When to use it * Convert an XAF/XOF/CDF balance to USD so you can issue cards. * Internally rebalance funds between currency-segregated wallets you own. ## Prerequisites * Both `sourceWallet` and `destinationWallet` belong to your company. * The `sourceWallet` has at least `totalAmount` available. * You have a valid current exchange rate — typically obtained via [`POST /company/exchange-rates/convert`](/api-reference/endpoint/post-convert). ## Request ### Headers | Name | Required | Description | | --------------- | -------- | ----------------------- | | `Authorization` | Yes | `Bearer ` | | `Content-Type` | Yes | `application/json` | ### Body | Field | Type | Required | Description | | ---------------------------- | ------ | -------- | ---------------------------------------------------------------------- | | `sourceWallet.id` | string | Yes | UUID of the wallet to debit. | | `sourceWallet.currency` | string | Yes | The source wallet's currency. Sanity check. | | `sourceWallet.amount` | number | Yes | The amount to convert (in source currency). ≥ `0.01`. | | `sourceWallet.feeAmount` | number | Yes | Conversion fee in source currency. ≥ `0`. | | `sourceWallet.totalAmount` | number | Yes | Total to debit from source = `amount + feeAmount`. | | `destinationWallet.id` | string | Yes | UUID of the wallet to credit. | | `destinationWallet.currency` | string | Yes | Destination wallet's currency. | | `destinationWallet.amount` | number | Yes | Converted amount to credit (in destination currency). ≥ `0.01`. | | `exchangeRate.rate` | number | Yes | Rate applied: `destination_amount = source_amount × rate`. ≥ `0.0001`. | | `exchangeRate.fromCurrency` | string | Yes | Must equal `sourceWallet.currency`. | | `exchangeRate.toCurrency` | string | Yes | Must equal `destinationWallet.currency`. | ```json theme={null} { "sourceWallet": { "id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890", "currency": "XAF", "amount": 600000, "feeAmount": 6000, "totalAmount": 606000 }, "destinationWallet": { "id": "w9z8y7x6-w5v4-3210-zyxw-vu0987654321", "currency": "USD", "amount": 1000 }, "exchangeRate": { "rate": 0.001667, "fromCurrency": "XAF", "toCurrency": "USD" } } ``` ## Response ### 200 — Deposit successful ```json theme={null} { "success": true, "statusCode": 200, "message": "Deposit completed successfully", "data": { "transaction_id": "txn_dep_1a2b3c4d5e6f7890", "source_wallet_id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890", "destination_wallet_id": "w9z8y7x6-w5v4-3210-zyxw-vu0987654321", "amount_debited": 606000, "amount_credited": 1000, "fee_amount": 6000, "rate": 0.001667, "from_currency": "XAF", "to_currency": "USD", "completed_at": "2026-05-09T10:15:00.000Z" } } ``` ### Error responses | Status | `message` example | Trigger | | ------ | -------------------------------------------------------- | --------------------------------------------------------------- | | `400` | `"Insufficient source wallet balance"` | Source wallet balance \< `totalAmount`. | | `400` | `"Currency mismatch"` | One of the `currency` fields doesn't match its wallet. | | `400` | `"Invalid totalAmount"` | `totalAmount` ≠ `amount + feeAmount`. | | `403` | `"Only authenticated users can perform wallet deposits"` | Token is a system-level token rather than a user token. | | `404` | `"Wallet not found"` | One of the wallet IDs is invalid or belongs to another company. | ## Code examples ```bash cURL theme={null} curl -X POST https://api.cartevo.co/api/v1/wallets/deposit \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @deposit.json ``` ```js Node.js (axios) theme={null} // 1. Get a fresh quote const quote = await axios.post( "https://api.cartevo.co/api/v1/company/exchange-rates/convert", { fromCurrency: "XAF", toCurrency: "USD", amount: 600000 }, { headers: { Authorization: `Bearer ${token}` } } ); // 2. Apply the conversion await axios.post( "https://api.cartevo.co/api/v1/wallets/deposit", { sourceWallet: { id: xafWalletId, currency: "XAF", amount: 600000, feeAmount: 6000, totalAmount: 606000 }, destinationWallet: { id: usdWalletId, currency: "USD", amount: quote.data.data.toAmount }, exchangeRate: { rate: quote.data.data.rate, fromCurrency: "XAF", toCurrency: "USD" }, }, { headers: { Authorization: `Bearer ${token}` } } ); ``` ## Related * [`POST /company/exchange-rates/convert`](/api-reference/endpoint/post-convert) — quote a conversion before applying. * [`GET /wallets`](/api-reference/endpoint/get-wallets) — verify the new balances after the deposit. ## OpenAPI ````yaml POST /wallets/deposit openapi: 3.1.0 info: title: Cartevo API description: Essential endpoints for wallets, transactions, customers and conversion. version: 1.0.0 servers: - url: https://api.cartevo.co/api/v1 security: - bearerAuth: [] paths: /wallets/deposit: post: summary: Deposit to wallet description: Deposit funds to a wallet requestBody: required: true content: application/json: schema: type: object description: >- Wallet-to-wallet transfer with currency conversion. The amount is debited from the source wallet (including fees) and the converted amount credited to the destination wallet. properties: sourceWallet: type: object properties: id: type: string format: uuid description: Source wallet ID. currency: type: string example: XAF amount: type: number description: Amount to convert from the source wallet. feeAmount: type: number description: Fee charged on the transfer. totalAmount: type: number description: Total debited from the source wallet (amount + fee). required: - id - currency - amount - feeAmount - totalAmount destinationWallet: type: object properties: id: type: string format: uuid description: Destination wallet ID. currency: type: string example: USD amount: type: number description: Converted amount credited to the destination wallet. required: - id - currency - amount exchangeRate: type: object properties: rate: type: number description: Exchange rate applied. fromCurrency: type: string example: XAF toCurrency: type: string example: USD required: - rate - fromCurrency - toCurrency required: - sourceWallet - destinationWallet - exchangeRate responses: '200': description: Deposit successful content: application/json: schema: $ref: '#/components/schemas/StandardResponse' '400': description: Bad request - invalid amount or wallet components: schemas: StandardResponse: type: object properties: success: type: boolean example: true statusCode: type: integer example: 200 message: type: string example: Data retrieved successfully securitySchemes: bearerAuth: type: http scheme: bearer ````