Skip to main content
GET
/
wallets
List wallets
curl --request GET \
  --url https://api.cartevo.co/api/v1/wallets \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": "422541f3-80e2-41e0-b7a2-24017586b374",
      "balance": "0.24",
      "payin_balance": "306",
      "payout_balance": "1646",
      "payin_amount": "982.6",
      "payout_amount": "1994",
      "amount_to_recover": "0",
      "is_active": true,
      "currency": "XAF",
      "country": "Cameroon",
      "country_iso_code": "CM",
      "company_id": "eca5e982-00b5-4aa2-b709-7d5cd673e95c",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "country_phone_code": "237",
      "phoneNumbers": [
        {
          "id": "32e525ac-a4a3-47fa-896e-4ef89f64d2d0",
          "wallet_id": "422541f3-80e2-41e0-b7a2-24017586b374",
          "country_iso_code": "CM",
          "country_phone_code": "+237",
          "currency": "XAF",
          "phone_number": "650695112",
          "operator": "MTN",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "operators": [
        {
          "id": "f079c4db-4897-4ae7-9371-87950ad2429c",
          "country_iso_code": "CM",
          "country_phone_code": "237",
          "currency": "XAF",
          "operator_code": "mtn",
          "operator_name": "MTN Money",
          "otp_required": false,
          "ussd_code": "*126#",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ]
    }
  ]
}

​
Overview

GET /wallets returns every wallet provisioned under your company. Each entry includes the current payin_balance and payout_balance, plus configured phone numbers and operators. For a slimmer balances-only view, see GET /payment/balance.

​
When to use it

  • Render a wallets overview in your dashboard.
  • Look up a wallet’s id for use in other endpoints.
  • Inspect configured operators per wallet.

​
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": [
    {
      "id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "company_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "currency": "XAF",
      "country": "Cameroon",
      "country_iso_code": "CM",
      "country_phone_code": "+237",
      "balance": 175000,
      "payin_balance": 125000,
      "payout_balance": 50000,
      "payin_amount": 200000,
      "payout_amount": 75000,
      "amount_to_recover": 0,
      "is_active": true,
      "created_at": "2026-04-01T08:00:00.000Z",
      "updated_at": "2026-05-09T10:15:00.000Z",
      "phoneNumbers": [
        { "id": "...", "phone_number": "237670000000", "operator": "mtn", "is_default": true }
      ],
      "operators": [
        { "operator_code": "mtn", "payin_active": true, "payout_active": true },
        { "operator_code": "orange", "payin_active": true, "payout_active": false }
      ]
    }
  ]
}

​
Field reference

FieldTypeDescription
idstringWallet ID (UUID).
currencystringISO 4217.
country_iso_codestringISO 3166-1 alpha-2.
payin_balancenumberFunds collected from end users, currently in this wallet.
payout_balancenumberFunds available to disburse via POST /payment/payout.
balancenumberTotal balance (typically payin_balance + payout_balance).
payin_amountnumberLifetime pay-in volume.
payout_amountnumberLifetime pay-out volume.
amount_to_recovernumberOutstanding debt against this wallet (see Glossary → Debt).
is_activebooleanfalse when an admin has disabled the wallet.
phoneNumbersarrayMobile-money phone numbers configured against this wallet.
operatorsarrayOperators enabled for pay-in / pay-out on this wallet.

​
Error responses

StatusTrigger
401Missing or expired Bearer token.

​
Code examples

cURL
curl https://api.cartevo.co/api/v1/wallets \
  -H "Authorization: Bearer $TOKEN"
Node.js (axios)
const { data } = await axios.get("https://api.cartevo.co/api/v1/wallets", {
  headers: { Authorization: `Bearer ${token}` },
});
const usdWallet = data.data.find((w) => w.currency === "USD");

Authorizations

​
Authorization
string
header
required

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

Response

200 - application/json

A list of wallets associated with the company.

​
success
boolean
Example:

true

​
statusCode
integer
Example:

200

​
message
string
Example:

"Data retrieved successfully"

​
data
object[]