Skip to main content
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>"
}
'
{
  "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

NameRequiredDescription
AuthorizationYesBearer <access_token>
Content-TypeYesapplication/json

​
Query parameters

NameTypeRequiredDescription
purposestringNoFree-form description that appears in the dashboard.

​
Body

FieldTypeRequiredConstraints / format
walletIdstringYesThe wallet to credit (UUID).
amountnumberYesMinimum 0.01. Major currency unit of the wallet’s currency.
currencystringYesMust match the target wallet’s currency. Sanity check.
operatorstringNoMobile-money operator (mtn, orange, moov, wave, etc.). Defaults to mtn.
phonestringNoPhone number to charge. Country code + local number, no + (e.g. 237670000000).
userIdstringNoInternal user ID for audit trail (filled by the platform if omitted).
trxIdstringNoIdempotency key. Auto-generated UUID if omitted (you lose idempotency).
{
  "walletId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "amount": 5000,
  "currency": "XAF",
  "operator": "mtn",
  "phone": "237670000000",
  "trxId": "FUND-2026-001"
}

​
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
    }
  }
}
FieldDescription
transaction.idCartevo wallet-transaction ID.
transaction.statusPENDING immediately. Other values: PROCESSING, SUCCESS, FAILED. Wallet balance updates only on SUCCESS.
paymentResult.orderIdReference at the upstream payment provider (Afribapay).
feeInfoBreakdown of the fee charged by the operator.

​
Error responses

Statusmessage exampleTrigger
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"
  }'

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