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

# Create Wallet

> This endpoint allows you to create a new wallet for a specific customer in a chosen currency. Each wallet is linked to a customer and can be used to manage balances, transactions, and payment methods.

## Endpoint

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

```json theme={null}
{
  "currency": "NGN",
  "customer_id": "7da75a46-a1bc-11ee-9a32-560f156a658b"
}
```

***

## Request Fields

| Field         | Type          | Required | Description                                       |
| :------------ | :------------ | :------- | :------------------------------------------------ |
| `customer_id` | string (UUID) | Yes      | The customer for whom the wallet is being created |
| `currency`    | string        | Yes      | The currency for the wallet (e.g., `NGN`, `USD`)  |

***

## Response

### Success Response (201 Created)

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

| Field              | Type   | Description                             |
| :----------------- | :----- | :-------------------------------------- |
| `id`               | string | Unique wallet ID                        |
| `account_id`       | string | Internal account identifier             |
| `customer_id`      | string | ID of the customer linked to the wallet |
| `balance.amount`   | number | Current wallet balance (starts at 0)    |
| `balance.currency` | string | Currency of the wallet                  |
| `status`           | string | Wallet status (`active`)                |

***

## Example cURL Request

```bash theme={null}
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 Code | Description                                          |
| :---------- | :--------------------------------------------------- |
| `400`       | Invalid request or unsupported currency              |
| `401`       | Unauthorized                                         |
| `404`       | Customer not found                                   |
| `409`       | Wallet 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