Create Deposit Session

Start a customer deposit session through a widget.

POST /api/v1/widgets/deposit-sessions/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

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
payers	array	Yes	Array of 1–10 payer objects, each with an address field
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' \
  --header 'X-Client-Secret: wdgt_secret_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "widgetId": "wdgt_abc",
    "amount": "100",
    "currency": "USDC",
    "network": "polygon",
    "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "payers": [
      { "address": "0xPayerWalletAddress" }
    ],
    "customerEmail": "[e-mail]",
    "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
dstAddress	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

{
  "id": "dep_a1b2c3d4e5f6",
  "paymentStatus": "CREATED",
  "amount": "100",
  "currency": "USDC",
  "network": "polygon",
  "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "dstAddress": "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