Skip to main content

​
Endpoint

POST /wallets

​
Description

Use this endpoint to provision a wallet for a customer. The wallet is automatically assigned a unique ID and starts with a zero balance. The wallet status is set to active upon creation.

​
Request Body

{
  "currency": "NGN",
  "customer_id": "7da75a46-a1bc-11ee-9a32-560f156a658b"
}

​
Request Fields

FieldTypeRequiredDescription
customer_idstring (UUID)YesThe customer for whom the wallet is being created
currencystringYesThe currency for the wallet (e.g., NGN, USD)

​
Response

​
Success Response (201 Created)

{
  "data": {
    "id": "3d2e3f3e-3b3c-4907-a4fd-e241203440d7",
    "account_id": "f55ca88c-71aa-4dab-a10a-4d818c11e8e6",
    "customer_id": "a08bf5a3-8459-4e65-a5bb-34a1feef94cf",
    "balance": {
      "amount": 0,
      "currency": "NGN"
    },
    "status": "active"
  }
}

​
Response Fields

FieldTypeDescription
idstringUnique wallet ID
account_idstringInternal account identifier
customer_idstringID of the customer linked to the wallet
balance.amountnumberCurrent wallet balance (starts at 0)
balance.currencystringCurrency of the wallet
statusstringWallet status (active)

​
Example cURL Request

curl -X POST https://api.yourdomain.com/wallets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "customer_id": "7da75a46-a1bc-11ee-9a32-560f156a658b"
  }'

​
Common Errors

Status CodeDescription
400Invalid request or unsupported currency
401Unauthorized
404Customer not found
409Wallet already exists for this customer and currency

​
Notes & Best Practices

  • Ensure the customer exists before creating a wallet.
  • Only create one wallet per customer per currency to avoid duplicates.
  • The wallet starts with a zero balance and active status.
  • Use the wallet id for all subsequent transactions, payment methods, or status updates.

​
Common Use Cases

  • Provision wallets when a new customer signs up
  • Enable multi-currency wallet management for existing customers
  • Prepare wallets for payouts, funding, or transaction processing