Skip to main content
GET
/
payment
/
balance
Get Payment Balance
curl --request GET \
  --url https://api.cartevo.co/api/v1/payment/balance \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "message": "Balance retrieved successfully",
  "data": {
    "balances": [
      {
        "currency": "XAF",
        "country": "CM",
        "payin_balance": 50000,
        "payout_balance": 30000
      }
    ],
    "updated_at": "2025-01-08T12:00:00.000Z"
  }
}

​
Overview

GET /payment/balance returns the current pay-in and pay-out sub-balances for every wallet your company holds, with one entry per (currency, country) pair. Use this before initiating a payout to verify funds are available, or to render a balances widget in your dashboard.

​
When to use it

  • Pre-flight check before POST /payment/payout to avoid 400 Insufficient balance.
  • Render a wallet/balance summary on a dashboard.
  • Reconcile your local accounting balance against Cartevo.

​
Prerequisites

  • Authenticated as a company user.

​
Request

​
Headers

NameRequiredDescription
AuthorizationYesBearer <access_token>
No query parameters or body.

​
Response

​
200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "balances": [
      {
        "currency": "XAF",
        "country": "CM",
        "payin_balance": 125000,
        "payout_balance": 50000
      },
      {
        "currency": "XOF",
        "country": "CI",
        "payin_balance": 0,
        "payout_balance": 30000
      },
      {
        "currency": "USD",
        "country": "US",
        "payin_balance": 0,
        "payout_balance": 4250.5
      }
    ],
    "updated_at": "2026-05-09T10:15:00.000Z"
  }
}
FieldTypeDescription
data.balances[]arrayOne entry per wallet you own. Empty array if you have no wallets yet.
data.balances[].currencystringISO 4217 (e.g. XAF, XOF, USD).
data.balances[].countrystringISO 3166-1 alpha-2 (e.g. CM, CI, US).
data.balances[].payin_balancenumberPay-in sub-balance — funds collected from end users, not yet moved.
data.balances[].payout_balancenumberPay-out sub-balance — funds available to disburse via POST /payment/payout.
data.updated_atstringISO 8601. The instant Cartevo computed this snapshot. Real-time within ~1 second of any wallet-affecting transaction.
About the two sub-balances: Each wallet maintains a separate pay-in and pay-out sub-balance. Use POST /wallets/{id}/transfer-internal (currently undocumented; reach out to support) to move funds between them when needed. The USD wallet is also the source-of-funds for card issuance and funding.

​
Error responses

StatusTrigger
401Missing or expired Bearer token.

​
Code examples

cURL
curl https://api.cartevo.co/api/v1/payment/balance \
  -H "Authorization: Bearer $TOKEN"
Node.js (axios)
const { data } = await axios.get(
  "https://api.cartevo.co/api/v1/payment/balance",
  { headers: { Authorization: `Bearer ${token}` } }
);

const xafCM = data.data.balances.find(
  (b) => b.currency === "XAF" && b.country === "CM"
);
if (xafCM && xafCM.payout_balance < 50000) {
  throw new Error("Top up XAF/CM payout wallet before disbursing");
}

Authorizations

​
Authorization
string
header
required

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

Response

200 - application/json

Balance retrieved successfully

​
success
boolean
Example:

true

​
message
string
Example:

"Balance retrieved successfully"

​
data
object