Fund Wallet (Mobile Money)

Fund wallet

curl --request POST \
  --url https://api.cartevo.co/api/v1/wallets/fund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 1.01,
  "currency": "XAF",
  "phone": "237600000000",
  "operator": "mtn",
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "trxId": "<string>",
  "reason": "<string>",
  "reason_category": "<string>"
}
'

import requests

url = "https://api.cartevo.co/api/v1/wallets/fund"

payload = {
    "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "amount": 1.01,
    "currency": "XAF",
    "phone": "237600000000",
    "operator": "mtn",
    "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "trxId": "<string>",
    "reason": "<string>",
    "reason_category": "<string>"
}
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({
    walletId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    amount: 1.01,
    currency: 'XAF',
    phone: '237600000000',
    operator: 'mtn',
    userId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    trxId: '<string>',
    reason: '<string>',
    reason_category: '<string>'
  })
};

fetch('https://api.cartevo.co/api/v1/wallets/fund', 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/fund",
  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([
    'walletId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'amount' => 1.01,
    'currency' => 'XAF',
    'phone' => '237600000000',
    'operator' => 'mtn',
    'userId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'trxId' => '<string>',
    'reason' => '<string>',
    'reason_category' => '<string>'
  ]),
  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/fund"

	payload := strings.NewReader("{\n  \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 1.01,\n  \"currency\": \"XAF\",\n  \"phone\": \"237600000000\",\n  \"operator\": \"mtn\",\n  \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"trxId\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"reason_category\": \"<string>\"\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/fund")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 1.01,\n  \"currency\": \"XAF\",\n  \"phone\": \"237600000000\",\n  \"operator\": \"mtn\",\n  \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"trxId\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"reason_category\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/wallets/fund")

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  \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 1.01,\n  \"currency\": \"XAF\",\n  \"phone\": \"237600000000\",\n  \"operator\": \"mtn\",\n  \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"trxId\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"reason_category\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "transaction": {
      "id": "7d1cdfa3-9904-4a17-bce5-092554170c0e",
      "amount": 5000,
      "amount_with_fee": 5100,
      "fee_amount": 100,
      "net_amount": 5000,
      "currency": "XAF",
      "status": "PENDING",
      "type": "FUND",
      "category": "WALLET",
      "operator": "mtn",
      "phone_number": "650695112",
      "reference": "<string>",
      "order_id": "<string>",
      "wallet_balance_before": 10000,
      "wallet_balance_after": 15000,
      "created_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    },
    "paymentResult": {
      "orderId": "order_123456",
      "providerResponse": {}
    },
    "feeInfo": {
      "feeAmount": 100,
      "feePercentage": 0.02,
      "totalAmount": 5100
    }
  }
}

POST

wallets

fund

Fund wallet

curl --request POST \
  --url https://api.cartevo.co/api/v1/wallets/fund \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 1.01,
  "currency": "XAF",
  "phone": "237600000000",
  "operator": "mtn",
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "trxId": "<string>",
  "reason": "<string>",
  "reason_category": "<string>"
}
'

import requests

url = "https://api.cartevo.co/api/v1/wallets/fund"

payload = {
    "walletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "amount": 1.01,
    "currency": "XAF",
    "phone": "237600000000",
    "operator": "mtn",
    "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "trxId": "<string>",
    "reason": "<string>",
    "reason_category": "<string>"
}
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({
    walletId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    amount: 1.01,
    currency: 'XAF',
    phone: '237600000000',
    operator: 'mtn',
    userId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    trxId: '<string>',
    reason: '<string>',
    reason_category: '<string>'
  })
};

fetch('https://api.cartevo.co/api/v1/wallets/fund', 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/fund",
  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([
    'walletId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'amount' => 1.01,
    'currency' => 'XAF',
    'phone' => '237600000000',
    'operator' => 'mtn',
    'userId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'trxId' => '<string>',
    'reason' => '<string>',
    'reason_category' => '<string>'
  ]),
  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/fund"

	payload := strings.NewReader("{\n  \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 1.01,\n  \"currency\": \"XAF\",\n  \"phone\": \"237600000000\",\n  \"operator\": \"mtn\",\n  \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"trxId\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"reason_category\": \"<string>\"\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/fund")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 1.01,\n  \"currency\": \"XAF\",\n  \"phone\": \"237600000000\",\n  \"operator\": \"mtn\",\n  \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"trxId\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"reason_category\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cartevo.co/api/v1/wallets/fund")

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  \"walletId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount\": 1.01,\n  \"currency\": \"XAF\",\n  \"phone\": \"237600000000\",\n  \"operator\": \"mtn\",\n  \"userId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"trxId\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"reason_category\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "transaction": {
      "id": "7d1cdfa3-9904-4a17-bce5-092554170c0e",
      "amount": 5000,
      "amount_with_fee": 5100,
      "fee_amount": 100,
      "net_amount": 5000,
      "currency": "XAF",
      "status": "PENDING",
      "type": "FUND",
      "category": "WALLET",
      "operator": "mtn",
      "phone_number": "650695112",
      "reference": "<string>",
      "order_id": "<string>",
      "wallet_balance_before": 10000,
      "wallet_balance_after": 15000,
      "created_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    },
    "paymentResult": {
      "orderId": "order_123456",
      "providerResponse": {}
    },
    "feeInfo": {
      "feeAmount": 100,
      "feePercentage": 0.02,
      "totalAmount": 5100
    }
  }
}

Overview

POST /wallets/fund tops up a wallet by charging a mobile-money account. It is functionally similar to POST /payment/collect but is wallet-centric: you specify which wallet to credit by ID rather than by (country, currency). The call returns immediately with a transaction record; the final outcome reaches you asynchronously (operator OTP / USSD may be required).

When to use it

Top up a specific wallet from your own funds (e.g. via your treasury phone).
Use when you already know the wallet you want to credit (rather than letting Cartevo route by country/currency).

For end-user collection (charging your customers), use POST /payment/collect instead.

Prerequisites

The target wallet must belong to your company and be is_active: true.
The mobile-money account must have sufficient balance to cover amount plus the operator’s fee.

Request

Headers

Name	Required	Description
`Authorization`	Yes	`Bearer <access_token>`
`Content-Type`	Yes	`application/json`

Query parameters

Name	Type	Required	Description
`purpose`	string	No	Free-form description that appears in the dashboard.

Body

Field	Type	Required	Constraints / format
`walletId`	string	Yes	The wallet to credit (UUID).
`amount`	number	Yes	Minimum `0.01`. Major currency unit of the wallet’s `currency`.
`currency`	string	Yes	Must match the target wallet’s currency. Sanity check.
`operator`	string	No	Mobile-money operator (`mtn`, `orange`, `moov`, `wave`, etc.). Defaults to `mtn`.
`phone`	string	No	Phone number to charge. Country code + local number, no `+` (e.g. `237670000000`).
`userId`	string	No	Internal user ID for audit trail (filled by the platform if omitted).
`trxId`	string	No	Idempotency key. Auto-generated UUID if omitted (you lose idempotency).
`otpCode`	string	No	One-time code the payer generates on their phone, required by some operators (notably Orange Burkina Faso and Orange Senegal). See the Orange Money workflow below.

{
  "walletId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "amount": 5000,
  "currency": "XAF",
  "operator": "mtn",
  "phone": "237670000000",
  "trxId": "FUND-2026-001"
}

Orange Money workflow (Burkina Faso & Senegal)

For Orange Money in Burkina Faso and Senegal, the payer must generate a one-time code (OTP) themselves and you submit it in otpCode:

The payer dials the Orange USSD code to generate the OTP:
- Burkina Faso: *144*4*6*<amount># (where <amount> is the amount)
- Senegal: #144*391#
The payer gives you the OTP.
You call POST /wallets/fund with operator: "orange", the Orange phone number, and the OTP in otpCode.

{
  "walletId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "amount": 1000,
  "currency": "XOF",
  "operator": "orange",
  "phone": "22670000000",
  "otpCode": "123456",
  "trxId": "FUND-2026-002"
}

The OTP is short-lived and single-use. If it expires the funding fails — the payer generates a fresh one and you retry with a new trxId.

Response

200 — Funding initiated

{
  "success": true,
  "statusCode": 200,
  "message": "Wallet funding initiated",
  "data": {
    "transaction": {
      "id": "txn_5b7c9d2e4f6a8b1c3d5e7f9a",
      "wallet_id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "amount": 5000,
      "currency": "XAF",
      "category": "WALLET",
      "type": "FUND",
      "status": "PENDING",
      "phone_number": "237670000000",
      "operator": "mtn",
      "wallet_balance_before": 125000,
      "wallet_balance_after": 125000,
      "created_at": "2026-05-09T10:15:00.000Z"
    },
    "paymentResult": {
      "orderId": "AFB-202605091015-XYZ",
      "providerResponse": { "status": "PENDING", "message": "Awaiting OTP" }
    },
    "feeInfo": {
      "feeAmount": 50,
      "feePercentage": 1.0,
      "totalAmount": 5050
    }
  }
}

Field	Description
`transaction.id`	Cartevo wallet-transaction ID.
`transaction.status`	`PENDING` immediately. Other values: `PROCESSING`, `SUCCESS`, `FAILED`. Wallet balance updates only on `SUCCESS`.
`paymentResult.orderId`	Reference at the upstream payment provider (Afribapay).
`feeInfo`	Breakdown of the fee charged by the operator.

Error responses

Status	`message` example	Trigger
`400`	`"Currency mismatch with target wallet"`	`currency` doesn’t match the wallet’s currency.
`400`	`"Operator not enabled for this wallet"`	The operator hasn’t been enabled for this wallet’s country/currency.
`404`	`"Wallet not found"`	`walletId` is invalid or belongs to another company.

Webhooks fired

A status update fires when the funding settles or fails (same shape as payment.collect).

Code examples

cURL

curl -X POST https://api.cartevo.co/api/v1/wallets/fund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "walletId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "amount": 5000,
    "currency": "XAF",
    "operator": "mtn",
    "phone": "237670000000",
    "trxId": "FUND-2026-001"
  }'

POST /payment/collect — the more general collection endpoint.
GET /wallets/{id} — verify the new balance after settlement.
Payment guidelines — supported operators per country.

Authorizations

Authorization

string

header

required

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

Body

application/json

walletId

string<uuid>

required

ID of the wallet to fund.

amount

number

required

Amount to fund, in the wallet currency.

Required range: x >= 0.01

currency

string

required

Currency of the funding amount.

Example:

"XAF"

phone

string

Mobile-money phone number being charged.

Example:

"237600000000"

operator

string

Mobile-money operator. Defaults to mtn if omitted.

Example:

"mtn"

userId

string<uuid>

Optional ID of the user initiating the funding.

trxId

string

Optional client-supplied transaction reference. Auto-generated (UUID) if omitted.

reason

string

Optional free-text reason, persisted on the transaction.

reason_category

string

Optional categorical reason code.

Response

Funding request initiated successfully. The transaction is pending.

success

boolean

Example:

true

statusCode

integer

Example:

200

message

string

Example:

"Data retrieved successfully"

data

object

Show child attributes

Get USD Wallet Balance Deposit Between Wallets (Currency Conversion)

API documentation

Auth

Cards

Customers

Wallets

Payment Collection

Webhook

Overview

When to use it

Prerequisites

Request

Headers

Query parameters

Body

Orange Money workflow (Burkina Faso & Senegal)

Response

200 — Funding initiated

Error responses

Webhooks fired

Code examples

Authorizations

Body

Response

​Overview

​When to use it

​Prerequisites

​Request

​Headers

​Query parameters

​Body

​Orange Money workflow (Burkina Faso & Senegal)

​Response

​200 — Funding initiated

​Error responses

​Webhooks fired

​Code examples

​Related

Authorizations

Body

Response

Overview

When to use it

Prerequisites

Request

Headers

Query parameters

Body

Orange Money workflow (Burkina Faso & Senegal)

Response

200 — Funding initiated

Error responses

Webhooks fired

Code examples

Related