> ## 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 Session Voucher

> Create a deposit session with a reserved voucher through a widget.

`POST /api/v1/widgets/deposit-sessions/create-session-voucher`

Creates a deposit session and reserves a voucher in a single request. The session has a 30-minute expiry and is tracked through `CREATED` → `PENDING` → `CONFIRMED` statuses. The voucher is reserved and linked to the session.

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

## Parameters

### Body

| Name                | Type     | Required | Description                                                      |
| ------------------- | -------- | -------- | ---------------------------------------------------------------- |
| `widgetId`          | `string` | Yes      | The widget ID                                                    |
| `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 |
| `code`              | `string` | Yes      | Voucher redemption code, exactly 6 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/deposit-sessions/create-session-voucher' \
  --header 'X-Client-Secret: wdgt_secret_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "widgetId": "wdgt_abc",
    "amount": "100",
    "currency": "USDC",
    "network": "polygon",
    "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "code": "ABC123",
    "customerEmail": "customer@example.com",
    "customerReference": "order_12345"
  }'
```

## Response

### Response schema

**Session fields:**

| Field                   | Type               | Description                                      |
| ----------------------- | ------------------ | ------------------------------------------------ |
| `id`                    | `string`           | Unique session identifier                        |
| `paymentStatus`         | `string`           | Initial status — `CREATED`                       |
| `amount`                | `string`           | Payment amount                                   |
| `amountRaw`             | `string`           | Raw amount in lowest denominator                 |
| `currency`              | `string`           | Currency symbol                                  |
| `network`               | `string`           | Blockchain network                               |
| `currencyAddress`       | `string`           | Currency contract address                        |
| `dstAddress`            | `string`           | Destination deposit address                      |
| `value`                 | `string`           | Estimated USD value                              |
| `valueRaw`              | `string`           | Raw USD value in lowest denominator              |
| `confirmedTxid`         | `string` or `null` | Confirmed blockchain transaction hash            |
| `confirmedPayerAddress` | `string` or `null` | Confirmed payer wallet address                   |
| `expiresAt`             | `string`           | ISO 8601 expiry (30 minutes from creation)       |
| `clientSecret`          | `string`           | One-time client secret for tracking this session |

**Voucher fields:**

| Field            | Type     | Description                 |
| ---------------- | -------- | --------------------------- |
| `voucher.id`     | `string` | Unique voucher identifier   |
| `voucher.code`   | `string` | Voucher redemption code     |
| `voucher.status` | `string` | Voucher status — `RESERVED` |

### Example response

```json theme={null}
{
  "id": "dep_a1b2c3d4e5f6",
  "paymentStatus": "CREATED",
  "amount": "100",
  "amountRaw": "100000000",
  "currency": "USDC",
  "network": "polygon",
  "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "dstAddress": "0xMerchantWalletAddress",
  "value": "100.00",
  "valueRaw": "10000",
  "confirmedTxid": null,
  "confirmedPayerAddress": null,
  "expiresAt": "2026-06-09T12:30:00.000Z",
  "clientSecret": "dep_secret_xyz...",
  "voucher": {
    "id": "vchr_a1b2c3d4e5f6",
    "code": "BLEEP-ABCD-1234",
    "status": "RESERVED"
  }
}
```

### 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                                                                             |