Wallets API

POST /wallets

Create a wallet for a customer.

Field	Type	Required	Description
`customer_id`	string	yes	Customer to issue the wallet to
`currency`	string	yes	ISO 4217 currency code
`metadata`	object	no

curl https://api.xtopay.co/v1/wallets \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_abc123", "currency": "GHS" }'

Response 201

{
  "id": "wal_a1b2c3",
  "customer_id": "cus_abc123",
  "currency": "GHS",
  "balance": 0,
  "balance_formatted": "GH₵0.00",
  "status": "active",
  "created_at": "2026-05-24T10:00:00Z"
}

GET /wallets/:id

Retrieve a wallet by ID.

GET /wallets

List wallets. Filter with ?customer_id=, ?currency=, ?status=.

POST /wallets/:id/freeze

Freeze a wallet. Blocks debits but allows top-ups.

POST /wallets/:id/unfreeze

Unfreeze a wallet.

POST /wallets/:id/close

Close a wallet permanently.

POST /wallets/:id/debit

Deduct funds from a wallet.

Field	Type	Required	Description
`amount`	integer	yes	Amount to deduct in smallest unit
`description`	string	yes	Human-readable reason for the debit
`reference`	string	yes	Your unique reference — used for idempotency
`metadata`	object	no

curl https://api.xtopay.co/v1/wallets/wal_a1b2c3/debit \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "description": "10 SMS messages sent",
    "reference": "sms_batch_8821"
  }'

Response 200

{
  "id": "txn_a1b2c3",
  "type": "debit",
  "amount": 500,
  "balance_before": 15000,
  "balance_after": 14500,
  "reference": "sms_batch_8821"
}

POST /wallets/:id/credit

Apply an admin credit (no payment required).

Field	Type	Required	Description
`amount`	integer	yes	Amount to credit
`description`	string	yes	Reason for the credit
`reference`	string	yes	Unique reference
`expires_at`	ISO 8601	no	When this credit expires

POST /wallets/:id/topups

Create a top-up checkout for the customer.

Field	Type	Required	Description
`amount`	integer	yes	Amount the customer will pay
`redirect_url`	string	yes	Redirect after successful payment
`cancel_url`	string	no	Redirect on cancellation

Response includes checkout_url to redirect the customer.

GET /wallets/:id/topups

List top-ups for a wallet.

GET /wallets/:id/transactions

List all transactions (debits, credits, top-ups, expiries) for a wallet.

Parameter	Description
`type`	Filter: `topup` \| `debit` \| `credit` \| `expiry`
`limit`	1–100, default 20
`after`	Cursor

On this page