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"
}
}
'import requests
url = "https://api.cartevo.co/api/v1/wallets/deposit"
payload = {
"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"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'}
})
};
fetch('https://api.cartevo.co/api/v1/wallets/deposit', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cartevo.co/api/v1/wallets/deposit",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cartevo.co/api/v1/wallets/deposit"
payload := strings.NewReader("{\n \"sourceWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"XAF\",\n \"amount\": 123,\n \"feeAmount\": 123,\n \"totalAmount\": 123\n },\n \"destinationWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"USD\",\n \"amount\": 123\n },\n \"exchangeRate\": {\n \"rate\": 123,\n \"fromCurrency\": \"XAF\",\n \"toCurrency\": \"USD\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cartevo.co/api/v1/wallets/deposit")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"sourceWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"XAF\",\n \"amount\": 123,\n \"feeAmount\": 123,\n \"totalAmount\": 123\n },\n \"destinationWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"USD\",\n \"amount\": 123\n },\n \"exchangeRate\": {\n \"rate\": 123,\n \"fromCurrency\": \"XAF\",\n \"toCurrency\": \"USD\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cartevo.co/api/v1/wallets/deposit")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sourceWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"XAF\",\n \"amount\": 123,\n \"feeAmount\": 123,\n \"totalAmount\": 123\n },\n \"destinationWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"USD\",\n \"amount\": 123\n },\n \"exchangeRate\": {\n \"rate\": 123,\n \"fromCurrency\": \"XAF\",\n \"toCurrency\": \"USD\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"statusCode": 200,
"message": "Data retrieved successfully"
}Wallets
Deposit Between Wallets (Currency Conversion)
Move funds from one of your wallets to another, with automatic currency conversion and fee deduction.
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"
}
}
'import requests
url = "https://api.cartevo.co/api/v1/wallets/deposit"
payload = {
"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"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'}
})
};
fetch('https://api.cartevo.co/api/v1/wallets/deposit', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cartevo.co/api/v1/wallets/deposit",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cartevo.co/api/v1/wallets/deposit"
payload := strings.NewReader("{\n \"sourceWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"XAF\",\n \"amount\": 123,\n \"feeAmount\": 123,\n \"totalAmount\": 123\n },\n \"destinationWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"USD\",\n \"amount\": 123\n },\n \"exchangeRate\": {\n \"rate\": 123,\n \"fromCurrency\": \"XAF\",\n \"toCurrency\": \"USD\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cartevo.co/api/v1/wallets/deposit")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"sourceWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"XAF\",\n \"amount\": 123,\n \"feeAmount\": 123,\n \"totalAmount\": 123\n },\n \"destinationWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"USD\",\n \"amount\": 123\n },\n \"exchangeRate\": {\n \"rate\": 123,\n \"fromCurrency\": \"XAF\",\n \"toCurrency\": \"USD\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cartevo.co/api/v1/wallets/deposit")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sourceWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"XAF\",\n \"amount\": 123,\n \"feeAmount\": 123,\n \"totalAmount\": 123\n },\n \"destinationWallet\": {\n \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"currency\": \"USD\",\n \"amount\": 123\n },\n \"exchangeRate\": {\n \"rate\": 123,\n \"fromCurrency\": \"XAF\",\n \"toCurrency\": \"USD\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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 usePOST /payment/collectorPOST /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
sourceWalletanddestinationWalletbelong to your company. - The
sourceWallethas at leasttotalAmountavailable. - You have a valid current exchange rate — typically obtained via
POST /company/exchange-rates/convert.
Request
Headers
| Name | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <access_token> |
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. |
{
"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
| 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
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}` } }
);
Related
POST /company/exchange-rates/convert— quote a conversion before applying.GET /wallets— verify the new balances after the deposit.
Authorizations
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.
⌘I