Skip to main content
POST
/
wallets
Create a wallet
curl --request POST \
  --url https://api.cartevo.co/api/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "XAF",
  "country": "Cameroon",
  "country_iso_code": "CM",
  "country_phone_code": "+237"
}
'

​
Overview

POST /wallets provisions a new wallet for your company. Each wallet is keyed by (currency, country_iso_code) — you cannot have two wallets for the same pair. The wallet is created with balance: 0 and is_active: true. The USD wallet is special: it is the source-of-funds for all card issuance and funding, and the destination for refunds when a card is terminated.

​
When to use it

  • You’re starting collections or payouts in a new country/currency.
  • You’re onboarding a new market.
  • You need a USD wallet before issuing your first card.

​
Prerequisites

  • Your company has completed KYB and is in APPROVED status.

​
Request

​
Headers

NameRequiredDescription
AuthorizationYesBearer <access_token>
Content-TypeYesapplication/json

​
Body

FieldTypeRequiredConstraints / format
currencystringYesISO 4217. Common values: XAF, XOF, CDF, GNF, USD. For country_iso_code=CD, this is forced to CDF.
countrystringYesFull country name (e.g. "Cameroon").
country_iso_codestringYesISO 3166-1 alpha-2 (e.g. CM, CI, CD).
country_phone_codestringYesDial code with + (e.g. +237).
{
  "currency": "XAF",
  "country": "Cameroon",
  "country_iso_code": "CM",
  "country_phone_code": "+237"
}

​
Response

​
201 — Wallet created

{
  "success": true,
  "statusCode": 201,
  "message": "Wallet created 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": 0,
    "payin_balance": 0,
    "payout_balance": 0,
    "is_active": true,
    "created_at": "2026-05-09T10:15:00.000Z",
    "updated_at": "2026-05-09T10:15:00.000Z"
  }
}
FieldTypeDescription
idstringWallet ID (UUID). Use for all wallet operations.
currencystringThe wallet’s currency.
payin_balancenumberPay-in sub-balance (funds collected from end users).
payout_balancenumberPay-out sub-balance (funds available to disburse).
balancenumberTotal balance — usually payin_balance + payout_balance.
is_activebooleantrue for newly created wallets.

​
Error responses

Statusmessage exampleTrigger
400"Wallet for this currency and country already exists"Duplicate (currency, country_iso_code) pair.
400"Invalid country / currency combination"The pair is not supported by Cartevo.
403"KYB not approved"Your company has not completed KYB.

​
Code examples

cURL
curl -X POST https://api.cartevo.co/api/v1/wallets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "XAF",
    "country": "Cameroon",
    "country_iso_code": "CM",
    "country_phone_code": "+237"
  }'
Node.js (axios)
const { data } = await axios.post(
  "https://api.cartevo.co/api/v1/wallets",
  {
    currency: "XAF",
    country: "Cameroon",
    country_iso_code: "CM",
    country_phone_code: "+237",
  },
  { headers: { Authorization: `Bearer ${token}` } }
);
const walletId = data.data.id;

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
currency
string
required
Example:

"XAF"

​
country
string
required
Example:

"Cameroon"

​
country_iso_code
string
required
Example:

"CM"

​
country_phone_code
string
required
Example:

"+237"

Response

Wallet created successfully