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

# Create Deposit Session

> Start a customer deposit session through a widget.

`POST /api/v1/widgets/:widgetId/create-session`

Creates a deposit session for a customer paying through the widget. The session has a 30-minute expiry and is tracked through `CREATED` → `PENDING` → `CONFIRMED` statuses.

This endpoint accepts either a JWT bearer token or the widget's client secret via `X-Client-Secret` header.

## Parameters

### Path

| Name       | Type     | Required | Description   |
| ---------- | -------- | -------- | ------------- |
| `widgetId` | `string` | Yes      | The widget ID |

### Body

| Name                | Type     | Required | Description                                                      |
| ------------------- | -------- | -------- | ---------------------------------------------------------------- |
| `amount`            | `string` | Yes      | Payment amount as a decimal string, 1–32 characters              |
| `currency`          | `string` | Yes      | Currency symbol, 2–8 uppercase alphanumeric (e.g. `USDC`)        |
| `network`           | `string` | Yes      | Blockchain network, 4–66 characters                              |
| `currencyAddress`   | `string` | Yes      | Contract address of the currency on the network, 0–66 characters |
| `depositAddress`    | `string` | Yes      | Destination address for the deposit, 1–128 characters            |
| `customerEmail`     | `string` | No       | Customer's email, 1–128 characters                               |
| `customerReference` | `string` | No       | Your internal reference ID, 1–128 characters                     |
| `metadata`          | `object` | No       | Custom metadata matching the widget's schema, 1–2,048 bytes      |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/wdgt_abc/create-session' \
  --header 'X-Client-Secret: wdgt_secret_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": "100",
    "currency": "USDC",
    "network": "polygon",
    "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "depositAddress": "0xMerchantWalletAddress",
    "customerEmail": "customer@example.com",
    "customerReference": "order_12345"
  }'
```

## Response

### Response schema

| Field             | Type     | Description                                      |
| ----------------- | -------- | ------------------------------------------------ |
| `id`              | `string` | Unique session identifier                        |
| `paymentStatus`   | `string` | Initial status — `CREATED`                       |
| `amount`          | `string` | Payment amount                                   |
| `currency`        | `string` | Currency symbol                                  |
| `network`         | `string` | Blockchain network                               |
| `currencyAddress` | `string` | Currency contract address                        |
| `depositAddress`  | `string` | Destination deposit address                      |
| `expiresAt`       | `string` | ISO 8601 expiry (30 minutes from creation)       |
| `clientSecret`    | `string` | One-time client secret for tracking this session |

### Example response

```json theme={null}
{
  "id": "dep_a1b2c3d4e5f6",
  "paymentStatus": "CREATED",
  "amount": "100",
  "currency": "USDC",
  "network": "polygon",
  "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "depositAddress": "0xMerchantWalletAddress",
  "expiresAt": "2026-06-09T12:30:00.000Z",
  "clientSecret": "dep_secret_xyz..."
}
```

### Error responses

| Status | Code                | Description                                                                                  |
| ------ | ------------------- | -------------------------------------------------------------------------------------------- |
| `400`  | `validation_failed` | Parameters outside allowed ranges (amount not in min/max, disallowed network/currency, etc.) |
| `401`  | `unauthorized`      | Missing or invalid authentication                                                            |
| `404`  | `not_found`         | Widget not found                                                                             |