Create Widget

Create and configure a new payment widget for a business.

POST /api/v1/businesses/:businessId/widgets/create-widget

A widget is an embeddable crypto payment gateway. Each business can have up to 10 widgets, each independently configured.

Parameters

Path

Name	Type	Required	Description
businessId	string	Yes	The business ID

Body

Name	Type	Required	Description
name	string	Yes	Widget display name, 1–128 characters
mode	enum	Yes	FIXED_AMOUNT or CUSTOMER_AMOUNT
minAmount	string or null	No	Minimum deposit amount as a decimal string
maxAmount	string or null	No	Maximum deposit amount as a decimal string
allowedNetworks	array	No	Accepted blockchain networks
allowedCurrencies	array	No	Accepted currency symbols
allowedDepositAddresses	array	No	Allowed destination addresses
allowedDomains	array	No	Domain restriction list
allowedMethods	array	No	Accepted payment methods (max 3)
successUrl	string or null	No	Redirect URL on success, 1–2,048 characters
cancelUrl	string or null	No	Redirect URL on cancel
defaultCurrency	string or null	No	Default currency, 2–8 uppercase
defaultCurrencyAddress	string or null	No	Default currency contract address
defaultNetwork	string or null	No	Default blockchain network, 4–32 characters
defaultDepositAddress	string or null	No	Default deposit destination
metadataSchema	object or null	No	JSON schema for custom metadata, 1–2,048 bytes
renderMode	enum	No	Widget render mode: IFRAME or POPUP
iconUrl	string or null	No	Widget icon URL, 1–2,048 characters
color	string or null	No	Accent color with alpha (e.g. "#FF5733CC"), 8 characters
emoji	string or null	No	Widget emoji, 1–8 characters

Request example

curl --request POST 'https://payments.bleepay.com/api/v1/businesses/biz_abc123/widgets/create-widget' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Checkout Widget",
    "mode": "CUSTOMER_AMOUNT",
    "minAmount": "1",
    "maxAmount": "1000",
    "allowedNetworks": ["polygon", "ethereum"],
    "allowedCurrencies": ["USDC", "EURC"],
    "allowedDepositAddresses": ["0xMerchantWalletAddress"],
    "allowedDomains": ["shop.example.com"],
    "successUrl": "https://shop.example.com/order/success",
    "cancelUrl": "https://shop.example.com/order/cancel",
    "defaultCurrency": "USDC",
    "defaultNetwork": "polygon",
    "renderMode": "IFRAME"
  }'

Response

Response schema

Field	Type	Description
widget	object	The created widget object
clientSecret	string	Client secret for embedding the widget — shown only once

Widget object:

Field	Type	Description
id	string	Widget identifier
name	string	Widget name
mode	string	FIXED_AMOUNT or CUSTOMER_AMOUNT
enabled	boolean	Whether the widget is active
createdAt	string	ISO 8601 timestamp

Example response

{
  "widget": {
    "id": "wdgt_abc",
    "name": "Checkout Widget",
    "mode": "CUSTOMER_AMOUNT",
    "enabled": true,
    "createdAt": "2026-06-09T12:00:00.000Z"
  },
  "clientSecret": "wdgt_secret_abc123..."
}

Warning: The clientSecret is shown only once at creation time. Store it securely — you’ll need it to authenticate public widget endpoints.