Create a wallet

curl --request POST \
  --url https://api.paystack.com/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "<string>",
  "customer_id": "<string>",
  "label": "<string>",
  "metadata": {}
}
'

{
  "status": true,
  "message": "Wallet created successfully",
  "code": "ok",
  "data": {
    "id": "wal_01HXYZABC1234567890ABCDEFG",
    "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
    "currency": "USDC",
    "available_balance": "1234.567890",
    "pending_balance": "0.000000",
    "total_balance": "1234.567890",
    "metadata": {},
    "provisioned": false,
    "created_at": "2026-05-20T12:00:00.000Z",
    "updated_at": "2026-05-20T12:00:00.000Z",
    "label": "USDC Operating Wallet"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Wallets

Create a wallet

Create a wallet — a ledger balance in a single currency for a customer.

This does not create a credential. Add funding rails later with POST /v1/wallets/:id/credentials when you need a persistent receive identity. You can still onramp into a wallet with zero credentials.

If customer_id is omitted, the wallet is created for the merchant. The currency must support deposit (can_deposit = true). FIAT currencies are resolved against the customer’s country; crypto currencies resolve for any customer.

Balances start at zero, formatted to the currency’s precision. A customer may hold multiple wallets in the same crypto currency, but only one wallet per fiat currency; each create returns a new wallet with its own wal_… id. Use the optional label to tell them apart.

Body

currency — required. 2-8 uppercase alphanumerics (e.g. USDC, NGN).
customer_id — Owner customer ID. If omitted, defaults to your account’s default customer — created automatically when you signed up.
label — optional. Max 255 chars.
metadata — optional. Free-form Record<string, string>.

Example

POST /v1/wallets
{
  "currency": "USDC"
}

POST

wallets

Create a wallet

curl --request POST \
  --url https://api.paystack.com/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "<string>",
  "customer_id": "<string>",
  "label": "<string>",
  "metadata": {}
}
'

{
  "status": true,
  "message": "Wallet created successfully",
  "code": "ok",
  "data": {
    "id": "wal_01HXYZABC1234567890ABCDEFG",
    "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
    "currency": "USDC",
    "available_balance": "1234.567890",
    "pending_balance": "0.000000",
    "total_balance": "1234.567890",
    "metadata": {},
    "provisioned": false,
    "created_at": "2026-05-20T12:00:00.000Z",
    "updated_at": "2026-05-20T12:00:00.000Z",
    "label": "USDC Operating Wallet"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Headers

Idempotency-Key

string

Optional client-supplied key. Identical key + identical body within 24h replays the original response. Identical key + different body returns 409 idempotency_conflict. The hash is over raw bytes — clients retrying must send the byte-identical body; a re-serialised JSON payload will produce a different hash and a 409. Strongly recommended for retry-safe clients.

Pattern: ^[A-Za-z0-9_\-]{8,255}$

Body

application/json

CreateWalletDto

currency

string

required

Pattern: ^[A-Z0-9]{2,8}$

customer_id

string

label

string

Maximum string length: 255

metadata

object

Response

Wallet created successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Wallet created successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes