Create Wallet

​

Endpoint

POST /wallets

​

Description

​

Request Body

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

​

Request Fields

​

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

​

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

​

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