> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Wallet

> Provision a new company wallet for a specific country and currency. The wallet starts at zero balance and is the source/destination for collections, payouts, and (for USD) card operations.

## 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

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

### Body

| Field                | Type   | Required | Constraints / format                                                                                            |
| -------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `currency`           | string | Yes      | ISO 4217. Common values: `XAF`, `XOF`, `CDF`, `GNF`, `USD`. For `country_iso_code=CD`, this is forced to `CDF`. |
| `country`            | string | Yes      | Full country name (e.g. `"Cameroon"`).                                                                          |
| `country_iso_code`   | string | Yes      | ISO 3166-1 alpha-2 (e.g. `CM`, `CI`, `CD`).                                                                     |
| `country_phone_code` | string | Yes      | Dial code with `+` (e.g. `+237`).                                                                               |

```json theme={null}
{
  "currency": "XAF",
  "country": "Cameroon",
  "country_iso_code": "CM",
  "country_phone_code": "+237"
}
```

## Response

### 201 — Wallet created

```json theme={null}
{
  "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"
  }
}
```

| Field            | Type    | Description                                               |
| ---------------- | ------- | --------------------------------------------------------- |
| `id`             | string  | Wallet ID (UUID). Use for all wallet operations.          |
| `currency`       | string  | The wallet's currency.                                    |
| `payin_balance`  | number  | Pay-in sub-balance (funds collected from end users).      |
| `payout_balance` | number  | Pay-out sub-balance (funds available to disburse).        |
| `balance`        | number  | Total balance — usually `payin_balance + payout_balance`. |
| `is_active`      | boolean | `true` for newly created wallets.                         |

### Error responses

| Status | `message` example                                       | Trigger                                        |
| ------ | ------------------------------------------------------- | ---------------------------------------------- |
| `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

```bash cURL theme={null}
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"
  }'
```

```js Node.js (axios) theme={null}
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;
```

## Related

* [`GET /wallets`](/api-reference/endpoint/get-wallets) — list all wallets.
* [`POST /wallets/fund`](/api-reference/endpoint/post-wallets-fund) — top up via mobile money.
* [Glossary → Wallet](/getting-started/glossary#wallet) — pay-in vs pay-out semantics.


## OpenAPI

````yaml POST /wallets
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /wallets:
    post:
      summary: Create a wallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                currency:
                  type: string
                  example: XAF
                country:
                  type: string
                  example: Cameroon
                country_iso_code:
                  type: string
                  example: CM
                country_phone_code:
                  type: string
                  example: '+237'
              required:
                - currency
                - country
                - country_iso_code
                - country_phone_code
      responses:
        '201':
          description: Wallet created successfully
        '400':
          description: Bad request - invalid currency or country
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````