Skip to main content
POST
/
wallets
/
deposit
Deposit to wallet
curl --request POST \
  --url https://api.cartevo.co/api/v1/wallets/deposit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceWallet": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "currency": "XAF",
    "amount": 123,
    "feeAmount": 123,
    "totalAmount": 123
  },
  "destinationWallet": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "currency": "USD",
    "amount": 123
  },
  "exchangeRate": {
    "rate": 123,
    "fromCurrency": "XAF",
    "toCurrency": "USD"
  }
}
'
{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully"
}

​
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 or 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.

​
Request

​
Headers

NameRequiredDescription
AuthorizationYesBearer <access_token>
Content-TypeYesapplication/json

​
Body

FieldTypeRequiredDescription
sourceWallet.idstringYesUUID of the wallet to debit.
sourceWallet.currencystringYesThe source wallet’s currency. Sanity check.
sourceWallet.amountnumberYesThe amount to convert (in source currency). ≥ 0.01.
sourceWallet.feeAmountnumberYesConversion fee in source currency. ≥ 0.
sourceWallet.totalAmountnumberYesTotal to debit from source = amount + feeAmount.
destinationWallet.idstringYesUUID of the wallet to credit.
destinationWallet.currencystringYesDestination wallet’s currency.
destinationWallet.amountnumberYesConverted amount to credit (in destination currency). ≥ 0.01.
exchangeRate.ratenumberYesRate applied: destination_amount = source_amount × rate. ≥ 0.0001.
exchangeRate.fromCurrencystringYesMust equal sourceWallet.currency.
exchangeRate.toCurrencystringYesMust equal destinationWallet.currency.
{
  "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

{
  "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

Statusmessage exampleTrigger
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

cURL
curl -X POST https://api.cartevo.co/api/v1/wallets/deposit \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @deposit.json
Node.js (axios)
// 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}` } }
);

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

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.

​
sourceWallet
object
required
​
destinationWallet
object
required
​
exchangeRate
object
required

Response

Deposit successful

​
success
boolean
Example:

true

​
statusCode
integer
Example:

200

​
message
string
Example:

"Data retrieved successfully"