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

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": "[e-mail]",
    "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

{
  "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