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

```shell theme={null}
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

```json theme={null}
{
  "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.