# Get Challenge
Source: https://docs.bleepay.com/api-reference/auth/get-challenge



> Get a verification challenge for device registration.

`GET /api/v1/auth/get-challenge`

Returns a challenge string that must be included when signing up with a mobile device. The challenge is used in the device attestation flow to verify the authenticity of the device.

## Parameters

None.

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/auth/get-challenge'
```

## Response

### Response schema

| Field       | Type     | Description                   |
| ----------- | -------- | ----------------------------- |
| `challenge` | `string` | Verification challenge string |

### Example response

```json theme={null}
{
  "challenge": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghij"
}
```

### Error responses

| Status | Code         | Description       |
| ------ | ------------ | ----------------- |
| `429`  | `rate_limit` | Too many requests |


# Sign In
Source: https://docs.bleepay.com/api-reference/auth/sign-in



> Authenticate as a user to obtain a JWT bearer token.

`POST /api/v1/auth/sign-in`

Authenticate using mobile device credentials or email and password.

## Parameters

### Body

| Name   | Type     | Required | Description                               |
| ------ | -------- | -------- | ----------------------------------------- |
| `type` | `enum`   | Yes      | `mobile-device` or `email-password`       |
| `data` | `object` | Yes      | Credential data — shape depends on `type` |

**When `type` is `mobile-device`:**

| Name                  | Type     | Required | Description                               |
| --------------------- | -------- | -------- | ----------------------------------------- |
| `data.installationId` | `string` | Yes      | Device installation ID, 32–128 characters |
| `data.password`       | `string` | Yes      | Device password, 32–256 characters        |

**When `type` is `email-password`:**

| Name            | Type     | Required | Description                        |
| --------------- | -------- | -------- | ---------------------------------- |
| `data.email`    | `string` | Yes      | Email address, 3–128 characters    |
| `data.password` | `string` | Yes      | Account password, 8–256 characters |

## Request examples

### Payer sign-in (mobile device)

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/auth/sign-in' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "mobile-device",
    "data": {
      "installationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6",
      "password": "your-device-password-minimum-32-chars"
    }
  }'
```

### Email sign-in

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/auth/sign-in' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "email-password",
    "data": {
      "email": "user@example.com",
      "password": "your-password"
    }
  }'
```

## Response

### Response schema

| Field                 | Type     | Description                              |
| --------------------- | -------- | ---------------------------------------- |
| `authorization`       | `object` | Authorization payload                    |
| `authorization.token` | `string` | JWT bearer token for subsequent requests |

### Example response

```json theme={null}
{
  "authorization": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

### Error responses

| Status | Code                  | Description                                |
| ------ | --------------------- | ------------------------------------------ |
| `400`  | `invalid_credentials` | The provided credentials are invalid       |
| `400`  | `invalid_type`        | The `type` field is missing or unsupported |
| `429`  | `rate_limit`          | Too many sign-in attempts — wait and retry |


# Sign Up
Source: https://docs.bleepay.com/api-reference/auth/sign-up



> Create a new user account with a device or email and password.

`POST /api/v1/auth/sign-up`

Register a new user. Supports two methods: mobile device registration (for wallet users) and email/password registration.

## Parameters

### Body

| Name   | Type     | Required | Description                                 |
| ------ | -------- | -------- | ------------------------------------------- |
| `type` | `enum`   | Yes      | `mobile-device` or `email-password`         |
| `data` | `object` | Yes      | Registration data — shape depends on `type` |

**When `type` is `mobile-device`:**

| Name                  | Type     | Required | Description                               |
| --------------------- | -------- | -------- | ----------------------------------------- |
| `data.installationId` | `string` | Yes      | Device installation ID, 32–128 characters |
| `data.password`       | `string` | Yes      | Device password, 32–256 characters        |
| `data.platform`       | `enum`   | Yes      | `ios` or `android`                        |
| `data.challenge`      | `string` | Yes      | Verification challenge, 48 characters     |
| `data.assertionToken` | `string` | Yes      | Assertion token, 1–10,240 characters      |
| `data.assertionKeyId` | `string` | No       | Optional key identifier, 32–64 characters |

**When `type` is `email-password`:**

| Name            | Type     | Required | Description                        |
| --------------- | -------- | -------- | ---------------------------------- |
| `data.email`    | `string` | Yes      | Email address, 3–128 characters    |
| `data.password` | `string` | Yes      | Account password, 8–256 characters |

## Request examples

### Mobile device sign-up

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/auth/sign-up' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "mobile-device",
    "data": {
      "installationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6",
      "password": "your-device-password-minimum-32-chars",
      "platform": "ios",
      "challenge": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghij",
      "assertionToken": "eyJhbGciOiJSUzI1NiIs..."
    }
  }'
```

### Email sign-up

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/auth/sign-up' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "email-password",
    "data": {
      "email": "user@example.com",
      "password": "your-password"
    }
  }'
```

## Response

### Response schema

| Field       | Type     | Description                    |
| ----------- | -------- | ------------------------------ |
| `id`        | `string` | Unique user identifier         |
| `role`      | `string` | User role (`USER`, etc.)       |
| `createdAt` | `string` | ISO 8601 creation timestamp    |
| `updatedAt` | `string` | ISO 8601 last update timestamp |

### Example response

```json theme={null}
{
  "id": "usr_a1b2c3d4e5f6",
  "role": "USER",
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:00:00.000Z"
}
```

### Error responses

| Status | Code                | Description                                              |
| ------ | ------------------- | -------------------------------------------------------- |
| `400`  | `invalid_type`      | The `type` field is missing or unsupported               |
| `400`  | `validation_failed` | Required fields are missing or invalid                   |
| `409`  | `already_exists`    | A user with this installation ID or email already exists |
| `429`  | `rate_limit`        | Too many sign-up attempts                                |


# Get Account
Source: https://docs.bleepay.com/api-reference/businesses/accounts/get-account



> Retrieve a single account by ID.

`GET /api/v1/businesses/accounts/:accountId`

Returns full details for a specific blockchain account. The owning business is resolved from the account ID. Accepts both Bearer token (registered user) and API key authentication.

## Parameters

### Path

| Name        | Type     | Required | Description    |
| ----------- | -------- | -------- | -------------- |
| `accountId` | `string` | Yes      | The account ID |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/businesses/accounts/acc_abc123' \
  --header 'Authorization: Bearer <business_token>'

curl --request GET 'https://payments.bleepay.com/api/v1/businesses/accounts/acc_abc123' \
  --header 'x-api-key: <api_key>'
```

## Response

### Response schema

| Field        | Type               | Description                                              |
| ------------ | ------------------ | -------------------------------------------------------- |
| `id`         | `string`           | Account identifier                                       |
| `businessId` | `string`           | Parent business identifier                               |
| `type`       | `string`           | Account type (`WEB3`)                                    |
| `network`    | `string`           | Blockchain network                                       |
| `address`    | `string`           | Blockchain address                                       |
| `currencies` | `array`            | Accepted currencies as `[{ currency, currencyAddress }]` |
| `label`      | `string` or `null` | Human-readable label                                     |
| `status`     | `string`           | `PENDING`, `ENABLED`, or `DISABLED`                      |
| `version`    | `number`           | Optimistic lock version                                  |
| `createdAt`  | `string`           | ISO 8601 creation timestamp                              |
| `updatedAt`  | `string`           | ISO 8601 last update timestamp                           |

### Example response

```json theme={null}
{
  "id": "acc_abc123",
  "businessId": "biz_abc123",
  "type": "WEB3",
  "network": "ethereum",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "currencies": [
    { "currency": "USDC", "currencyAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
  ],
  "label": "Primary wallet",
  "status": "ENABLED",
  "version": 1,
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:30:00.000Z"
}
```


# Query Accounts
Source: https://docs.bleepay.com/api-reference/businesses/accounts/query-accounts



> List all accounts linked to a business.

`GET /api/v1/businesses/accounts`

Returns all blockchain accounts linked to the business specified by the `businessId` query parameter. Accepts optional filters for type, network, and address. Accepts both Bearer token (registered user) and API key authentication.

## Parameters

### Query

| Name         | Type     | Required | Description                     |
| ------------ | -------- | -------- | ------------------------------- |
| `businessId` | `string` | Yes      | The business ID                 |
| `type`       | `string` | No       | Filter by account type (`WEB3`) |
| `network`    | `string` | No       | Filter by blockchain network    |
| `address`    | `string` | No       | Filter by blockchain address    |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/businesses/accounts?businessId=biz_abc123&network=ethereum' \
  --header 'Authorization: Bearer <business_token>'

curl --request GET 'https://payments.bleepay.com/api/v1/businesses/accounts?businessId=biz_abc123&network=ethereum' \
  --header 'x-api-key: <api_key>'
```

## Response

### Response schema

Returns an array of account objects.

| Field        | Type               | Description                                              |
| ------------ | ------------------ | -------------------------------------------------------- |
| `id`         | `string`           | Account identifier                                       |
| `businessId` | `string`           | Parent business identifier                               |
| `type`       | `string`           | Account type (`WEB3`)                                    |
| `network`    | `string`           | Blockchain network                                       |
| `address`    | `string`           | Blockchain address                                       |
| `currencies` | `array`            | Accepted currencies as `[{ currency, currencyAddress }]` |
| `label`      | `string` or `null` | Human-readable label                                     |
| `status`     | `string`           | `PENDING`, `ENABLED`, or `DISABLED`                      |
| `version`    | `number`           | Optimistic lock version                                  |
| `createdAt`  | `string`           | ISO 8601 creation timestamp                              |
| `updatedAt`  | `string`           | ISO 8601 last update timestamp                           |

### Example response

```json theme={null}
[
  {
    "id": "acc_abc123",
    "businessId": "biz_abc123",
    "type": "WEB3",
    "network": "ethereum",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
    "currencies": [
      { "currency": "USDC", "currencyAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
    ],
    "label": "Primary wallet",
    "status": "ENABLED",
    "version": 0,
    "createdAt": "2026-06-09T12:00:00.000Z",
    "updatedAt": "2026-06-09T12:00:00.000Z"
  }
]
```


# Convert Amount
Source: https://docs.bleepay.com/api-reference/finance/convert-amount



> Convert an amount between two currencies — get the current exchange rate.

`POST /api/v1/finance/currencies/convert`

Returns the converted amount based on current market rates. Used for FX calculations when a payer wants to pay in a different currency than the payee requested.

## Parameters

### Body

| Name                    | Type     | Required | Description                                              |
| ----------------------- | -------- | -------- | -------------------------------------------------------- |
| `sourceNetwork`         | `string` | Yes      | Source blockchain network, 4–32 characters               |
| `sourceCurrency`        | `string` | Yes      | Source currency symbol, 2–8 uppercase alphanumeric       |
| `sourceCurrencyAddress` | `string` | Yes      | Source token contract address, 0–66 characters           |
| `targetNetwork`         | `string` | Yes      | Target blockchain network, 4–32 characters               |
| `targetCurrency`        | `string` | Yes      | Target currency symbol, 2–8 uppercase alphanumeric       |
| `targetCurrencyAddress` | `string` | Yes      | Target token contract address, 0–66 characters           |
| `amount`                | `string` | Yes      | Amount to convert, numeric decimal string (e.g. `"100"`) |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/finance/currencies/convert' \
  --header 'Content-Type: application/json' \
  --data '{
    "sourceNetwork": "polygon",
    "sourceCurrency": "USDC",
    "sourceCurrencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "targetNetwork": "polygon",
    "targetCurrency": "EURC",
    "targetCurrencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
    "amount": "100"
  }'
```

## Response

### Response schema

Returns a `string` — the converted amount.

### Example response

```json theme={null}
"92.15"
```


# Get Currencies
Source: https://docs.bleepay.com/api-reference/finance/get-currencies



> Get information about supported currencies and tokens.

`GET /api/v1/finance/currencies`

Returns details about supported currencies including symbol, contract address, network, and whether the currency is enabled for swaps (bridgeable).

## Parameters

### Query

| Name         | Type      | Required | Description                                      |
| ------------ | --------- | -------- | ------------------------------------------------ |
| `network`    | `string`  | No       | Filter by network                                |
| `symbol`     | `string`  | No       | Filter by currency symbol (e.g. `EURC`, `USDC`)  |
| `address`    | `string`  | No       | Filter by contract address                       |
| `srcNetwork` | `string`  | No       | Source network for routing queries               |
| `srcSymbol`  | `string`  | No       | Source currency symbol for routing queries       |
| `srcAddress` | `string`  | No       | Source contract address for routing queries      |
| `dstNetwork` | `string`  | No       | Destination network for routing queries          |
| `dstSymbol`  | `string`  | No       | Destination currency symbol for routing queries  |
| `dstAddress` | `string`  | No       | Destination contract address for routing queries |
| `limit`      | `integer` | No       | Number of items (default 1000)                   |
| `offset`     | `integer` | No       | Pagination offset                                |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/finance/currencies?network=polygon&symbol=EURC' \
  --header 'Content-Type: application/json'
```

## Response

Returns an array of currency objects.

**Currency object:**

| Field        | Type      | Description                                 |
| ------------ | --------- | ------------------------------------------- |
| `symbol`     | `string`  | Currency symbol (e.g. `USDC`)               |
| `network`    | `string`  | Blockchain network                          |
| `address`    | `string`  | Contract address on-chain                   |
| `decimals`   | `integer` | Token decimals                              |
| `bridgeable` | `boolean` | Whether the currency can be swapped/bridged |
| `enabled`    | `boolean` | Whether the currency is active              |

### Example response

```json theme={null}
[
  {
    "symbol": "EURC",
    "network": "polygon",
    "address": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
    "decimals": 6,
    "bridgeable": true,
    "enabled": true
  }
]
```


# Get Networks
Source: https://docs.bleepay.com/api-reference/finance/get-networks



> Get information about supported blockchain networks.

`GET /api/v1/finance/networks`

Returns details about supported blockchain networks including name, type, chain ID, and native currency. Can be filtered to a specific network or queried for source/destination routing pairs.

## Parameters

### Query

| Name         | Type      | Required | Description                                                      |
| ------------ | --------- | -------- | ---------------------------------------------------------------- |
| `network`    | `string`  | No       | Filter by network name (e.g. `polygon`, `ethereum`). 4–32 chars. |
| `srcNetwork` | `string`  | No       | Source network for routing queries                               |
| `dstNetwork` | `string`  | No       | Destination network for routing queries                          |
| `limit`      | `integer` | No       | Number of items (default 1000)                                   |
| `offset`     | `integer` | No       | Pagination offset                                                |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/finance/networks?network=polygon' \
  --header 'Content-Type: application/json'
```

## Response

Returns an array of network objects.

**Network object:**

| Field            | Type      | Description                          |
| ---------------- | --------- | ------------------------------------ |
| `network`        | `string`  | Network identifier (e.g. `polygon`)  |
| `type`           | `string`  | Network type (`evm`, `solana`, etc.) |
| `chainId`        | `string`  | Chain ID                             |
| `nativeCurrency` | `string`  | Native gas currency symbol           |
| `enabled`        | `boolean` | Whether the network is active        |

### Example response

```json theme={null}
[
  {
    "network": "polygon",
    "type": "evm",
    "chainId": "137",
    "nativeCurrency": "POL",
    "enabled": true
  }
]
```


# API Reference
Source: https://docs.bleepay.com/api-reference/index



# API Reference

> Programmatic access to the Bleepay payment protocol — vouchers, widgets, on-chain settlement.

Bleepay's REST API lets you create payment vouchers, manage widget integrations, monitor on-chain settlement, and configure business accounts. The API is organized around the core payment primitives: **contexts**, **vouchers**, and **sessions**.

## Base URL

```
https://payments.bleepay.com/api/v1
```

## Environments

| Environment    | Base URL                              | Use case               |
| -------------- | ------------------------------------- | ---------------------- |
| **Sandbox**    | `https://sandbox.bleepay.com/api/v1`  | Testing; no real funds |
| **Production** | `https://payments.bleepay.com/api/v1` | Live payments          |

## API reference

### Introduction

* [Authentication](/api-reference/introduction/authentication) — API keys and bearer tokens

### Auth

* [Sign in](/api-reference/auth/sign-in) — Authenticate as a user to obtain a JWT bearer token
* [Sign up](/api-reference/auth/sign-up) — Create a new user account
* [Get challenge](/api-reference/auth/get-challenge) — Get a verification challenge

### Vouchers

* [Open context](/api-reference/vouchers/contexts/open-context) — Start a payment context
* [Get context](/api-reference/vouchers/contexts/get-context) — Retrieve a context by ID
* [Query contexts](/api-reference/vouchers/contexts/query-contexts) — List all contexts
* [Close context](/api-reference/vouchers/contexts/close-context) — Close a payment context
* [Reserve voucher](/api-reference/vouchers/reserve-voucher) — Reserve a voucher from a context code
* [Redeem voucher](/api-reference/vouchers/redeem-voucher) — Set payment terms (SIMPLE or CUSTOM)
* [Resolve voucher](/api-reference/vouchers/resolve-voucher) — Submit signed transaction receipts
* [Negotiate voucher](/api-reference/vouchers/negotiate-voucher) — Propose an alternative payment
* [Sign voucher](/api-reference/vouchers/sign-voucher) — Sign a voucher with a public key
* [Discard voucher](/api-reference/vouchers/discard-voucher) — Discard an unused voucher
* [Get voucher](/api-reference/vouchers/get-voucher) — Retrieve a voucher by ID
* [Query vouchers](/api-reference/vouchers/query-vouchers) — List all vouchers
* [Submit interop signature](/api-reference/vouchers/submit-interop) — Cross-chain signature submission
* [Get interop status](/api-reference/vouchers/get-interop-status) — Check cross-chain signature status

#### Sessions

* [Open session](/api-reference/vouchers/sessions/open-session) — Start a multi-voucher session
* [Get session](/api-reference/vouchers/sessions/get-session) — Retrieve a session by ID
* [Join session](/api-reference/vouchers/sessions/join-session) — Join a session as payer
* [Close session](/api-reference/vouchers/sessions/close-session) — Close a session
* [Reserve voucher in session](/api-reference/vouchers/sessions/reserve-voucher) — Reserve a voucher within a session

### Finance

* [Get networks](/api-reference/finance/get-networks) — Supported blockchain networks
* [Get currencies](/api-reference/finance/get-currencies) — Supported currencies and tokens
* [Convert amount](/api-reference/finance/convert-amount) — Convert an amount between currencies

### Widgets

#### Management

* [Create widget](/api-reference/widgets/management/create-widget) — Configure a new widget
* [Get widget](/api-reference/widgets/management/get-widget) — Retrieve a widget by ID
* [Query widgets](/api-reference/widgets/management/query-widgets) — List business widgets
* [Update widget](/api-reference/widgets/management/update-widget) — Update widget configuration
* [Enable widget](/api-reference/widgets/management/enable-widget) — Enable a widget
* [Disable widget](/api-reference/widgets/management/disable-widget) — Disable a widget
* [Delete widget](/api-reference/widgets/management/delete-widget) — Delete a widget

#### Public

* [Get public config](/api-reference/widgets/public/get-config) — Get public widget configuration
* [Create deposit session](/api-reference/widgets/public/create-session) — Start a customer deposit
* [Create session voucher](/api-reference/widgets/public/create-session-voucher) — Create deposit session with reserved voucher
* [Get deposit session](/api-reference/widgets/public/get-session) — Check deposit session status
* [Cancel deposit session](/api-reference/widgets/public/cancel-session) — Cancel a deposit session

#### Deposits

* [Query deposit sessions](/api-reference/widgets/deposits/query-deposit-sessions) — List deposit sessions
* [Search deposit sessions](/api-reference/widgets/deposits/search-deposit-sessions) — Search deposit sessions
* [Query deposits](/api-reference/widgets/deposits/query-deposits) — List on-chain payments
* [Get deposit](/api-reference/widgets/deposits/get-deposit) — Retrieve a payment by ID
* [Query widget events](/api-reference/widgets/deposits/query-widget-events) — List widget events
* [Get widget event](/api-reference/widgets/deposits/get-widget-event) — Retrieve a widget event by ID

#### Charts

* [Get charts](/api-reference/widgets/charts/get-charts) — Retrieve aggregated payment chart data

#### Refunds

* [Create refund session](/api-reference/widgets/refunds/create-session) — Create a refund session
* [Create refund session voucher](/api-reference/widgets/refunds/create-session-voucher) — Create refund session with reserved voucher
* [Query refund sessions](/api-reference/widgets/refunds/query-sessions) — List refund sessions
* [Get refund session](/api-reference/widgets/refunds/get-session) — Retrieve a refund session by ID
* [Cancel refund session](/api-reference/widgets/refunds/cancel-session) — Cancel a refund session

### Webhooks

* [Create endpoint](/api-reference/webhooks/create-endpoint) — Register a webhook endpoint
* [Get endpoint](/api-reference/webhooks/get-endpoint) — Retrieve an endpoint by ID
* [Query endpoints](/api-reference/webhooks/query-endpoints) — List webhook endpoints
* [Update endpoint](/api-reference/webhooks/update-endpoint) — Update endpoint configuration
* [Rotate secret](/api-reference/webhooks/rotate-secret) — Rotate the signing secret
* [Enable endpoint](/api-reference/webhooks/enable-endpoint) — Enable an endpoint
* [Disable endpoint](/api-reference/webhooks/disable-endpoint) — Disable an endpoint
* [Delete endpoint](/api-reference/webhooks/delete-endpoint) — Delete an endpoint
* [Query deliveries](/api-reference/webhooks/query-deliveries) — List webhook deliveries
* [Get delivery](/api-reference/webhooks/get-delivery) — Retrieve a delivery by ID
* [Retry delivery](/api-reference/webhooks/retry-delivery) — Retry a failed delivery

### Accounts

* [Get account](/api-reference/businesses/accounts/get-account) — Retrieve an account by ID
* [Query accounts](/api-reference/businesses/accounts/query-accounts) — List business accounts


# Authentication
Source: https://docs.bleepay.com/api-reference/introduction/authentication



> How to authenticate with the Bleepay API — bearer tokens and API keys.

The Bleepay API uses **Bearer tokens** (JWTs) for most endpoints. The authentication method depends on who you are and what you're doing.

## Authentication methods

| Method                 | Header                          | Used by                                          |
| ---------------------- | ------------------------------- | ------------------------------------------------ |
| **Bearer token (JWT)** | `Authorization: Bearer <token>` | Payers, payees, businesses                       |
| **Client secret**      | `X-Client-Secret: <secret>`     | Widget public endpoints (customer-facing)        |
| **None**               | —                               | Auth endpoints, finance endpoints, health checks |

## Bearer token (JWT)

The most common method. Obtain a token by signing in, then include it in all subsequent requests.

### Obtaining a token

**User sign-in** — for payers using a wallet:

```text theme={null}
POST /api/v1/auth/sign-in

{
    "type": "mobile-device",
    "data": {
        "installationId": "a1b2c3d4e5f6...",
        "password": "your-device-password..."
    }
}
```

**Response:**

```json theme={null}
{
    "authorization": {
        "token": "eyJhbGciOiJIUzI1NiIs..."
    }
}
```

### Using the token

Include it as a Bearer token in the `Authorization` header:

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/reserve-voucher' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \
  --header 'Content-Type: application/json' \
  --data '{ "code": "A1B2C3" }'
```

### Token types

Bleepay JWTs encode the authentication method:

| Guard                         | Token type                              | Access                                           |
| ----------------------------- | --------------------------------------- | ------------------------------------------------ |
| `RegisteredUserGuard`         | JWT with `userId` or `deviceId`         | Full user operations                             |
| `RegisteredUserOrApiKeyGuard` | JWT with `userId`/`deviceId` or API key | Finance, widget, voucher, and session operations |
| `BusinessUserGuard`           | JWT with `userId` + business membership | Widget management, business CRUD                 |

API keys provide scoped access to business resources and widget management endpoints. They cannot access user management endpoints.

## Client secret

Widget public endpoints accept either a JWT or a client secret header:

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/wdgt_123/config' \
  --header 'X-Client-Secret: wdgt_secret_abc123...'
```

Client secrets are issued when a widget is created.

> **Security notice:** Never expose client secrets in client-side code, public repositories, or logs. Client secrets are shown only once at the time of widget creation.

## HTTP status codes

| Status | Meaning                                              |
| ------ | ---------------------------------------------------- |
| `200`  | Success                                              |
| `400`  | Invalid request (bad parameters, validation failure) |
| `401`  | Missing or invalid authentication                    |
| `403`  | Authenticated but not authorized for this resource   |
| `404`  | Resource not found                                   |
| `429`  | Rate limit exceeded                                  |
| `500`  | Unexpected server error                              |

## Rate limits

Each endpoint has its own rate limit. The limits below are per-endpoint (not per scope):

| Endpoint group                                                               | Limit                       |
| ---------------------------------------------------------------------------- | --------------------------- |
| Auth (`sign-in`, `sign-up`, `get-challenge`)                                 | 5 requests per 300 seconds  |
| Businesses read/write                                                        | 5 requests per 300 seconds  |
| Finance read/write                                                           | 5 requests per 300 seconds  |
| Vouchers read (`query`, `get`)                                               | 10 requests per 600 seconds |
| Vouchers write (`reserve`, `redeem`, `resolve`, `sign`, `discard`, sessions) | 5 requests per 300 seconds  |
| Voucher negotiate                                                            | 1 request per 60 seconds    |
| Widgets read/write                                                           | 5 requests per 300 seconds  |
| Widgets public read/write                                                    | 5 requests per 300 seconds  |
| Webhooks read/write                                                          | 5 requests per 300 seconds  |

When a limit is exceeded, the API returns `429 Too Many Requests`.


# Close Context
Source: https://docs.bleepay.com/api-reference/vouchers/contexts/close-context



> Close an open payment context.

`POST /api/v1/vouchers/contexts/:contextId/context-close`

Closes a context, preventing any new vouchers from being reserved against it. Existing vouchers in the context are unaffected.

## Parameters

### Path

| Name        | Type     | Required | Description             |
| ----------- | -------- | -------- | ----------------------- |
| `contextId` | `string` | Yes      | The context ID to close |

### Body

| Name      | Type               | Required | Description                                                              |
| --------- | ------------------ | -------- | ------------------------------------------------------------------------ |
| `payeeId` | `string` or `null` | Yes      | The payee ID (exactly 64 characters), or `null` if no payee was involved |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/contexts/ctx_a1b2c3d4e5f6/context-close' \
  --header 'Authorization: Bearer <payer_token>' \
  --header 'Content-Type: application/json' \
  --data '{ "payeeId": null }'
```

## Response

### Response schema

Returns the updated context object with status `CLOSED`.

### Example response

```json theme={null}
{
  "id": "ctx_a1b2c3d4e5f6",
  "code": "A1B2C3",
  "status": "CLOSED",
  "format": "numeric",
  "payers": [
    {
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    }
  ],
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:05:00.000Z"
}
```

### Error responses

| Status | Code             | Description                     |
| ------ | ---------------- | ------------------------------- |
| `400`  | `already_closed` | The context is already closed   |
| `401`  | `unauthorized`   | Missing or invalid bearer token |
| `404`  | `not_found`      | Context not found               |


# Get Context
Source: https://docs.bleepay.com/api-reference/vouchers/contexts/get-context



> Retrieve a voucher context by its ID.

`GET /api/v1/vouchers/contexts/:contextId`

Returns the full state of a payment context, including its code, status, and associated payers.

## Parameters

### Path

| Name        | Type     | Required | Description                                         |
| ----------- | -------- | -------- | --------------------------------------------------- |
| `contextId` | `string` | Yes      | The context ID returned when the context was opened |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/vouchers/contexts/ctx_a1b2c3d4e5f6' \
  --header 'Authorization: Bearer <payer_token>'
```

## Response

### Response schema

| Field       | Type     | Description                               |
| ----------- | -------- | ----------------------------------------- |
| `id`        | `string` | Unique context identifier                 |
| `code`      | `string` | Context code                              |
| `status`    | `string` | Context status (`OPEN`, `CLOSED`)         |
| `format`    | `string` | Code format (`numeric` or `alphanumeric`) |
| `payers`    | `array`  | Payer objects                             |
| `createdAt` | `string` | ISO 8601 creation timestamp               |
| `updatedAt` | `string` | ISO 8601 last update timestamp            |

### Example response

```json theme={null}
{
  "id": "ctx_a1b2c3d4e5f6",
  "code": "A1B2C3",
  "status": "OPEN",
  "format": "numeric",
  "payers": [
    {
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    }
  ],
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:00:00.000Z"
}
```

### Error responses

| Status | Code           | Description                     |
| ------ | -------------- | ------------------------------- |
| `401`  | `unauthorized` | Missing or invalid bearer token |
| `404`  | `not_found`    | Context not found               |


# Open Context
Source: https://docs.bleepay.com/api-reference/vouchers/contexts/open-context



> Start a new payment context — the first step in a voucher payment flow.

`POST /api/v1/vouchers/contexts/context-open`

A context is a secure link between a payer's wallet and a payment session. The payer opens a context in their wallet, which generates a **context code** they share with the payee. The payee then uses this code to authenticate and reserve vouchers.

This endpoint requires authentication as a registered user (the payer).

## Parameters

### Body

| Name     | Type    | Required | Description                                              |
| -------- | ------- | -------- | -------------------------------------------------------- |
| `format` | `enum`  | Yes      | `numeric` or `alphanum` — the format of the context code |
| `payers` | `array` | Yes      | List of payers, 1–10 entries                             |

**Payer object:**

| Name      | Type     | Required | Description                            |
| --------- | -------- | -------- | -------------------------------------- |
| `address` | `string` | Yes      | Blockchain wallet address of the payer |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/contexts/context-open' \
  --header 'Authorization: Bearer <payer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "format": "numeric",
    "payers": [
      { "address": "0x1234567890abcdef1234567890abcdef12345678" }
    ]
  }'
```

## Response

### Response schema

| Field       | Type     | Description                              |
| ----------- | -------- | ---------------------------------------- |
| `id`        | `string` | Unique context identifier                |
| `code`      | `string` | Context code — share this with the payee |
| `status`    | `string` | Context status (`OPEN`, etc.)            |
| `format`    | `string` | Code format (`numeric` or `alphanum`)    |
| `payers`    | `array`  | Payer objects in the context             |
| `createdAt` | `string` | ISO 8601 creation timestamp              |

### Example response

```json theme={null}
{
  "id": "ctx_a1b2c3d4e5f6",
  "code": "A1B2C3",
  "status": "OPEN",
  "format": "numeric",
  "payers": [
    {
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    }
  ],
  "createdAt": "2026-06-09T12:00:00.000Z"
}
```

### Error responses

| Status | Code                | Description                        |
| ------ | ------------------- | ---------------------------------- |
| `400`  | `validation_failed` | Invalid or missing required fields |
| `401`  | `unauthorized`      | Missing or invalid bearer token    |
| `500`  | `unexpected`        | An unexpected error occurred       |


# Query Contexts
Source: https://docs.bleepay.com/api-reference/vouchers/contexts/query-contexts



> List all voucher contexts for the authenticated user.

`GET /api/v1/vouchers/contexts`

Returns a paginated list of contexts ordered by creation time (newest first).

## Parameters

### Query

| Name     | Type      | Required | Description                                                 |
| -------- | --------- | -------- | ----------------------------------------------------------- |
| `limit`  | `integer` | No       | Number of items to return (default 100)                     |
| `offset` | `integer` | No       | Number of items to skip for pagination                      |
| `since`  | `integer` | No       | Unix timestamp (ms) — return items created after this time  |
| `until`  | `integer` | No       | Unix timestamp (ms) — return items created before this time |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/vouchers/contexts?limit=20' \
  --header 'Authorization: Bearer <payer_token>'
```

## Response

Returns an array of context objects. See [Get Context](/api-reference/vouchers/contexts/get-context) for the object schema.

### Example response

```json theme={null}
[
  {
    "id": "ctx_a1b2c3d4e5f6",
    "code": "A1B2C3",
    "status": "OPEN",
    "format": "numeric",
    "payers": [
      { "address": "0x1234567890abcdef1234567890abcdef12345678" }
    ],
    "createdAt": "2026-06-09T12:00:00.000Z",
    "updatedAt": "2026-06-09T12:00:00.000Z"
  }
]
```


# Discard Voucher
Source: https://docs.bleepay.com/api-reference/vouchers/discard-voucher



> Discard an unused voucher — releases it from the reserved state.

`POST /api/v1/vouchers/:voucherId/discard-voucher`

Discards a voucher that is no longer needed. The voucher must be in `RESERVED` or `REDEEMED` status. Once discarded, the voucher cannot be used.

This endpoint accepts both API key and registered user tokens.

## Parameters

### Path

| Name        | Type     | Required | Description               |
| ----------- | -------- | -------- | ------------------------- |
| `voucherId` | `string` | Yes      | The voucher ID to discard |

### Body

No body parameters required.

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/vch_482916/discard-voucher' \
  --header 'Authorization: Bearer <payee_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

### Response schema

Returns the updated voucher object with a discarded status.

### Error responses

| Status | Code               | Description                            |
| ------ | ------------------ | -------------------------------------- |
| `400`  | `already_resolved` | A resolved voucher cannot be discarded |
| `401`  | `unauthorized`     | Missing or invalid bearer token        |
| `404`  | `not_found`        | Voucher not found                      |


# Get Interop Status
Source: https://docs.bleepay.com/api-reference/vouchers/get-interop-status



> Check the cross-chain signature submission status for a voucher.

`GET /api/v1/vouchers/:voucherId/status/interop-info`

Returns the status of a cross-chain signature submission initiated via `submit/interop-init`.

## Parameters

### Path

| Name        | Type     | Required | Description    |
| ----------- | -------- | -------- | -------------- |
| `voucherId` | `string` | Yes      | The voucher ID |

### Query

| Name           | Type      | Required | Description                                         |
| -------------- | --------- | -------- | --------------------------------------------------- |
| `id`           | `string`  | Yes      | Signature submission identifier, 1–128 characters   |
| `paymentIndex` | `integer` | No       | Index of the payment being signed (0–10, default 0) |
| `vid`          | `string`  | No       | Voucher ID override, 1–32 characters                |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/vouchers/vch_482916/status/interop-info?id=sig_abc&paymentIndex=0' \
  --header 'Authorization: Bearer <payer_token>'
```

## Response

### Response schema

| Field    | Type     | Description                                                    |
| -------- | -------- | -------------------------------------------------------------- |
| `status` | `string` | Interop status: `PENDING`, `SUCCEEDED`, `FAILED`, or `UNKNOWN` |

### Example response

```json theme={null}
{
  "status": "SUCCEEDED"
}
```

### Error responses

| Status | Code           | Description                     |
| ------ | -------------- | ------------------------------- |
| `401`  | `unauthorized` | Missing or invalid bearer token |
| `404`  | `not_found`    | Voucher not found               |


# Get Voucher
Source: https://docs.bleepay.com/api-reference/vouchers/get-voucher



> Retrieve a voucher by its ID.

`GET /api/v1/vouchers/:voucherId`

Returns the full state of a voucher, including its type, status, payment details, and any FX negotiation state.

This is the endpoint to poll when waiting for the payer to resolve the voucher.

## Parameters

### Path

| Name        | Type     | Required | Description    |
| ----------- | -------- | -------- | -------------- |
| `voucherId` | `string` | Yes      | The voucher ID |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/vouchers/vch_482916' \
  --header 'Authorization: Bearer <payee_token>'
```

## Response

### Response schema

| Field             | Type     | Description                                                      |
| ----------------- | -------- | ---------------------------------------------------------------- |
| `id`              | `string` | Voucher identifier                                               |
| `code`            | `string` | 6-digit voucher code                                             |
| `status`          | `string` | Voucher status (`RESERVED`, `REDEEMED`, `RESOLVED`, `DISCARDED`) |
| `type`            | `string` | `SIMPLE` or `CUSTOM`                                             |
| `expectedPayment` | `object` | Payment the payee expects (SIMPLE vouchers)                      |
| `suppliedPayment` | `object` | Payer's FX negotiation offer (if negotiated)                     |
| `payments`        | `array`  | Custom payment instructions (CUSTOM vouchers)                    |
| `networks`        | `array`  | Network specifications (CUSTOM vouchers)                         |
| `extras`          | `array`  | Extra instructions (CUSTOM vouchers)                             |
| `expiresAt`       | `string` | ISO 8601 expiry timestamp                                        |
| `createdAt`       | `string` | ISO 8601 creation timestamp                                      |
| `updatedAt`       | `string` | ISO 8601 last update timestamp                                   |

### Example response

```json theme={null}
{
  "id": "vch_482916",
  "code": "482916",
  "status": "RESOLVED",
  "type": "SIMPLE",
  "expectedPayment": {
    "network": "polygon",
    "currency": "EURC",
    "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
    "amount": "100",
    "wallet": {
      "address": "0xYourWalletAddress"
    }
  },
  "expiresAt": "2026-06-09T12:02:00.000Z",
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:01:00.000Z"
}
```

### Error responses

| Status | Code           | Description                     |
| ------ | -------------- | ------------------------------- |
| `401`  | `unauthorized` | Missing or invalid bearer token |
| `404`  | `not_found`    | Voucher not found               |


# Negotiate Voucher
Source: https://docs.bleepay.com/api-reference/vouchers/negotiate-voucher



> Propose an alternative payment currency — used for FX negotiation.

`POST /api/v1/vouchers/:voucherId/negotiate-voucher`

If the payer doesn't hold the currency the payee requested, their wallet can negotiate by proposing an alternative currency they do hold. The system calculates the exchange rate and fills in the required amount.

This only applies to SIMPLE vouchers. The negotiation happens on the payer's side — the payee's `expectedPayment` remains unchanged, and a `suppliedPayment` is added to the voucher.

## Parameters

### Path

| Name        | Type     | Required | Description                 |
| ----------- | -------- | -------- | --------------------------- |
| `voucherId` | `string` | Yes      | The voucher ID to negotiate |

### Body

| Name                              | Type     | Required | Description                           |
| --------------------------------- | -------- | -------- | ------------------------------------- |
| `suppliedPayment`                 | `object` | Yes      | The payment the payer is offering     |
| `suppliedPayment.network`         | `string` | Yes      | Blockchain network                    |
| `suppliedPayment.currency`        | `string` | Yes      | Currency symbol (e.g. `USDC`)         |
| `suppliedPayment.currencyAddress` | `string` | Yes      | Contract address of the offered token |
| `suppliedPayment.amount`          | `string` | Yes      | Amount the payer is offering          |
| `suppliedPayment.wallet`          | `object` | Yes      | Payer's wallet                        |
| `suppliedPayment.wallet.address`  | `string` | Yes      | Payer's wallet address                |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/vch_482916/negotiate-voucher' \
  --header 'Authorization: Bearer <payer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "suppliedPayment": {
      "network": "polygon",
      "currency": "USDC",
      "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
      "amount": "105",
      "wallet": {
        "address": "0xPayerWalletAddress"
      }
    }
  }'
```

## Response

### Response schema

| Field             | Type     | Description                                               |
| ----------------- | -------- | --------------------------------------------------------- |
| `id`              | `string` | Voucher identifier                                        |
| `status`          | `string` | Voucher status                                            |
| `expectedPayment` | `object` | The payee's original request (unchanged)                  |
| `suppliedPayment` | `object` | The payer's proposed alternative, with FX-adjusted amount |

### Example response

```json theme={null}
{
  "id": "vch_482916",
  "status": "REDEEMED",
  "expectedPayment": {
    "network": "polygon",
    "currency": "EURC",
    "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
    "amount": "100",
    "wallet": { "address": "0xYourWalletAddress" }
  },
  "suppliedPayment": {
    "network": "polygon",
    "currency": "USDC",
    "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "amount": "105.23",
    "wallet": { "address": "0xPayerWalletAddress" }
  }
}
```

### Error responses

| Status | Code                | Description                                                                |
| ------ | ------------------- | -------------------------------------------------------------------------- |
| `400`  | `not_simple`        | Negotiation is only available for SIMPLE vouchers                          |
| `400`  | `different_network` | The supplied currency must be on the same network as the expected currency |
| `401`  | `unauthorized`      | Missing or invalid bearer token                                            |
| `404`  | `not_found`         | Voucher not found                                                          |


# Query Vouchers
Source: https://docs.bleepay.com/api-reference/vouchers/query-vouchers



> List all vouchers for the authenticated user.

`GET /api/v1/vouchers/`

Returns a paginated list of vouchers ordered by creation time. Useful for checking the status of multiple vouchers at once.

## Parameters

### Query

| Name     | Type      | Required | Description                                                                |
| -------- | --------- | -------- | -------------------------------------------------------------------------- |
| `limit`  | `integer` | No       | Number of items to return (default 100)                                    |
| `offset` | `integer` | No       | Number of items to skip for pagination                                     |
| `since`  | `integer` | No       | Unix timestamp (ms) — return items created after this time                 |
| `until`  | `integer` | No       | Unix timestamp (ms) — return items created before this time                |
| `status` | `string`  | No       | Filter by voucher status (`RESERVED`, `REDEEMED`, `RESOLVED`, `DISCARDED`) |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/vouchers/?status=RESOLVED&limit=20' \
  --header 'Authorization: Bearer <payer_token>'
```

## Response

Returns an array of voucher objects. See [Get Voucher](/api-reference/vouchers/get-voucher) for the object schema.

### Example response

```json theme={null}
[
  {
    "id": "vch_482916",
    "code": "482916",
    "status": "RESOLVED",
    "type": "SIMPLE",
    "expectedPayment": {
      "network": "polygon",
      "currency": "EURC",
      "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
      "amount": "100",
      "wallet": { "address": "0xYourWalletAddress" }
    },
    "createdAt": "2026-06-09T12:00:00.000Z",
    "updatedAt": "2026-06-09T12:01:00.000Z"
  }
]
```


# Redeem Voucher
Source: https://docs.bleepay.com/api-reference/vouchers/redeem-voucher



> Set the payment terms for a reserved voucher — creates a SIMPLE or CUSTOM voucher.

`POST /api/v1/vouchers/:voucherId/redeem-voucher`

Redeeming defines what the payee expects to receive. The voucher type is automatically determined:

* Provide `expectedPayment` → **SIMPLE** voucher (automatic network selection, supports FX)
* Provide `networks`, `payments`, or `extras` → **CUSTOM** voucher (full control, no FX)

You cannot provide both `expectedPayment` and `networks`/`payments`/`extras` — the system picks one based on what you supply.

## Parameters

### Path

| Name        | Type     | Required | Description                              |
| ----------- | -------- | -------- | ---------------------------------------- |
| `voucherId` | `string` | Yes      | The voucher ID from the reserve response |

### Body — SIMPLE voucher

Use `expectedPayment` for straightforward token transfers:

| Name                              | Type     | Required | Description                                           |
| --------------------------------- | -------- | -------- | ----------------------------------------------------- |
| `expectedPayment`                 | `object` | See note | The payment the payee expects to receive              |
| `expectedPayment.network`         | `string` | Yes      | Blockchain network (e.g. `polygon`, `ethereum`)       |
| `expectedPayment.currency`        | `string` | Yes      | Settlement currency symbol (e.g. `EURC`, `USDC`)      |
| `expectedPayment.currencyAddress` | `string` | Yes      | Contract address of the settlement token on-chain     |
| `expectedPayment.amount`          | `string` | Yes      | Amount to receive, as a decimal string (e.g. `"100"`) |
| `expectedPayment.wallet`          | `object` | Yes      | Destination wallet                                    |
| `expectedPayment.wallet.address`  | `string` | Yes      | Payee's wallet address where funds are sent           |

### Body — CUSTOM voucher

Use `networks`, `payments`, and `extras` for smart contract interactions:

| Name                     | Type     | Required | Description                                                     |
| ------------------------ | -------- | -------- | --------------------------------------------------------------- |
| `networks`               | `array`  | Yes      | 1–3 blockchain network specifications                           |
| `networks[].network`     | `string` | Yes      | Network name (e.g. `ethereum`)                                  |
| `networks[].type`        | `string` | Yes      | Network type (`evm`, `solana`)                                  |
| `networks[].chainId`     | `string` | Yes      | Chain ID (e.g. `"1"`)                                           |
| `payments`               | `array`  | Yes      | 1 payment instruction                                           |
| `payments[].type`        | `string` | Yes      | `send_transaction`                                              |
| `payments[].input.from`  | `string` | Yes      | `{payer}` — substituted by the wallet at resolution             |
| `payments[].input.to`    | `string` | Yes      | Contract address to call                                        |
| `payments[].input.value` | `string` | Yes      | Native currency value to send (`"0"` for contract calls)        |
| `payments[].input.data`  | `string` | Yes      | ABI-encoded calldata                                            |
| `extras`                 | `array`  | No       | 0–5 additional instructions (e.g. `call_transaction` for reads) |
| `payeeInfo`              | `object` | No       | Additional payee information                                    |

## Request examples

### SIMPLE voucher (EURC payment)

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/vch_482916/redeem-voucher' \
  --header 'Authorization: Bearer <payee_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "expectedPayment": {
      "network": "polygon",
      "currency": "EURC",
      "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
      "amount": "100",
      "wallet": {
        "address": "0xYourWalletAddress"
      }
    }
  }'
```

### CUSTOM voucher (staking contract call)

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/vch_591234/redeem-voucher' \
  --header 'Authorization: Bearer <payee_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "networks": [
      {
        "network": "ethereum",
        "type": "evm",
        "chainId": "1"
      }
    ],
    "payments": [
      {
        "type": "send_transaction",
        "input": {
          "from": "{payer}",
          "to": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
          "value": "0",
          "data": "0xa694fc3a0000000000000000000000000000000000000000000000000de0b6b3a7640000"
        }
      }
    ],
    "extras": []
  }'
```

## Response

### Response schema

| Field             | Type     | Description                                       |
| ----------------- | -------- | ------------------------------------------------- |
| `id`              | `string` | Voucher identifier                                |
| `status`          | `string` | Voucher status — `REDEEMED`                       |
| `type`            | `string` | `SIMPLE` or `CUSTOM`                              |
| `expectedPayment` | `object` | Present for SIMPLE vouchers (see body parameters) |
| `networks`        | `array`  | Present for CUSTOM vouchers                       |
| `payments`        | `array`  | Present for CUSTOM vouchers                       |
| `extras`          | `array`  | Present for CUSTOM vouchers                       |

### Example response (SIMPLE)

```json theme={null}
{
  "id": "vch_482916",
  "status": "REDEEMED",
  "type": "SIMPLE",
  "expectedPayment": {
    "network": "polygon",
    "currency": "EURC",
    "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
    "amount": "100",
    "wallet": {
      "address": "0xYourWalletAddress"
    }
  }
}
```

### Error responses

| Status | Code                | Description                                                                                       |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------- |
| `400`  | `already_redeemed`  | The voucher has already been redeemed                                                             |
| `400`  | `validation_failed` | Invalid parameters — check that `expectedPayment` and `networks`/`payments` are not both provided |
| `401`  | `unauthorized`      | Missing or invalid bearer token                                                                   |
| `404`  | `not_found`         | Voucher not found                                                                                 |


# Reserve Voucher
Source: https://docs.bleepay.com/api-reference/vouchers/reserve-voucher



> Reserve a voucher within a payment context — returns a 6-digit voucher code.

`POST /api/v1/vouchers/reserve-voucher`

The payee reserves a voucher using the context code the payer shared with them. The response includes a 6-digit voucher code and a voucher ID. The voucher starts in `RESERVED` status.

This endpoint accepts both API key authentication and registered user tokens.

## Parameters

### Body

| Name   | Type     | Required | Description                                         |
| ------ | -------- | -------- | --------------------------------------------------- |
| `code` | `string` | Yes      | The context code shared by the payer. 6 characters. |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/reserve-voucher' \
  --header 'Authorization: Bearer <payee_token>' \
  --header 'Content-Type: application/json' \
  --data '{ "code": "A1B2C3" }'
```

## Response

### Response schema

| Field       | Type     | Description                 |
| ----------- | -------- | --------------------------- |
| `id`        | `string` | Unique voucher identifier   |
| `code`      | `string` | 6-digit voucher code        |
| `status`    | `string` | Voucher status — `RESERVED` |
| `expiresAt` | `string` | ISO 8601 expiry timestamp   |

### Example response

```json theme={null}
{
  "id": "vch_482916",
  "code": "482916",
  "status": "RESERVED",
  "expiresAt": "2026-06-09T12:02:00.000Z"
}
```

### Error responses

| Status | Code           | Description                            |
| ------ | -------------- | -------------------------------------- |
| `400`  | `invalid_code` | The context code is invalid or expired |
| `401`  | `unauthorized` | Missing or invalid bearer token        |
| `404`  | `not_found`    | Context not found                      |


# Resolve Voucher
Source: https://docs.bleepay.com/api-reference/vouchers/resolve-voucher



> Finalize a voucher by submitting signed transaction receipts.

`POST /api/v1/vouchers/:voucherId/resolve-voucher`

After the payer reviews and signs the transaction in their wallet, the wallet submits the signed receipts via this endpoint. This completes the voucher lifecycle — the status moves to `RESOLVED`.

This endpoint requires authentication as a registered user (the payer).

## Parameters

### Path

| Name        | Type     | Required | Description               |
| ----------- | -------- | -------- | ------------------------- |
| `voucherId` | `string` | Yes      | The voucher ID to resolve |

### Body

| Name       | Type    | Required | Description                     |
| ---------- | ------- | -------- | ------------------------------- |
| `receipts` | `array` | Yes      | 1–5 signed transaction receipts |

**Receipt object:**

| Name        | Type     | Required | Description                                       |
| ----------- | -------- | -------- | ------------------------------------------------- |
| `paymentId` | `string` | Yes      | The ID of the payment this receipt corresponds to |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/vch_482916/resolve-voucher' \
  --header 'Authorization: Bearer <payer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "receipts": [
      { "paymentId": "pay_a1b2c3d4e5f6" }
    ]
  }'
```

## Response

### Response schema

| Field    | Type     | Description                 |
| -------- | -------- | --------------------------- |
| `id`     | `string` | Voucher identifier          |
| `status` | `string` | Voucher status — `RESOLVED` |

### Example response

```json theme={null}
{
  "id": "vch_482916",
  "status": "RESOLVED"
}
```

### Error responses

| Status | Code                | Description                                   |
| ------ | ------------------- | --------------------------------------------- |
| `400`  | `not_redeemed`      | The voucher must be redeemed before resolving |
| `400`  | `already_resolved`  | The voucher has already been resolved         |
| `400`  | `validation_failed` | Invalid or missing receipt data               |
| `401`  | `unauthorized`      | Missing or invalid bearer token               |
| `404`  | `not_found`         | Voucher not found                             |


# Close Session
Source: https://docs.bleepay.com/api-reference/vouchers/sessions/close-session



> Close a voucher session — prevents new vouchers from being reserved.

`POST /api/v1/vouchers/sessions/:sessionId/session-close`

Close the session once all vouchers within it have been resolved. This finalizes the session; no new vouchers can be reserved in a closed session.

## Parameters

### Path

| Name        | Type     | Required | Description             |
| ----------- | -------- | -------- | ----------------------- |
| `sessionId` | `string` | Yes      | The session ID to close |

### Body

No body parameters required.

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/sessions/ses_xyz/session-close' \
  --header 'Authorization: Bearer <payee_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

### Response schema

Returns the updated session object with status `CLOSED`.

### Example response

```json theme={null}
{
  "id": "ses_xyz",
  "code": "D4E5F6",
  "status": "CLOSED",
  "type": "payment",
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:10:00.000Z"
}
```

### Error responses

| Status | Code             | Description                     |
| ------ | ---------------- | ------------------------------- |
| `400`  | `already_closed` | The session is already closed   |
| `401`  | `unauthorized`   | Missing or invalid bearer token |
| `404`  | `not_found`      | Session not found               |


# Get Session
Source: https://docs.bleepay.com/api-reference/vouchers/sessions/get-session



> Retrieve a voucher session by its ID.

`GET /api/v1/vouchers/sessions/:sessionId`

Returns the state of a session, including its status and any vouchers reserved within it.

## Parameters

### Path

| Name        | Type     | Required | Description    |
| ----------- | -------- | -------- | -------------- |
| `sessionId` | `string` | Yes      | The session ID |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/vouchers/sessions/ses_xyz' \
  --header 'Authorization: Bearer <payee_token>'
```

## Response

### Response schema

| Field       | Type     | Description                           |
| ----------- | -------- | ------------------------------------- |
| `id`        | `string` | Session identifier                    |
| `code`      | `string` | Session code                          |
| `status`    | `string` | Session status (`OPEN`, `CLOSED`)     |
| `type`      | `string` | Session type                          |
| `vouchers`  | `array`  | Vouchers reserved within this session |
| `createdAt` | `string` | ISO 8601 creation timestamp           |
| `updatedAt` | `string` | ISO 8601 last update timestamp        |

### Example response

```json theme={null}
{
  "id": "ses_xyz",
  "code": "D4E5F6",
  "status": "OPEN",
  "type": "payment",
  "vouchers": [],
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:00:00.000Z"
}
```

### Error responses

| Status | Code           | Description                     |
| ------ | -------------- | ------------------------------- |
| `401`  | `unauthorized` | Missing or invalid bearer token |
| `404`  | `not_found`    | Session not found               |


# Join Session
Source: https://docs.bleepay.com/api-reference/vouchers/sessions/join-session



> Join a voucher session as the payer.

`POST /api/v1/vouchers/sessions/:sessionId/session-join`

After the payee opens a session, the payer joins it from their wallet. This links the payer's identity to the session so vouchers can be reserved and resolved within it.

## Parameters

### Path

| Name        | Type     | Required | Description            |
| ----------- | -------- | -------- | ---------------------- |
| `sessionId` | `string` | Yes      | The session ID to join |

### Body

No body parameters required.

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/sessions/ses_xyz/session-join' \
  --header 'Authorization: Bearer <payer_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

### Response schema

Returns the updated session object with the payer joined.

### Error responses

| Status | Code             | Description                           |
| ------ | ---------------- | ------------------------------------- |
| `400`  | `already_joined` | Payer has already joined this session |
| `400`  | `session_closed` | Cannot join a closed session          |
| `401`  | `unauthorized`   | Missing or invalid bearer token       |
| `404`  | `not_found`      | Session not found                     |


# Open Session
Source: https://docs.bleepay.com/api-reference/vouchers/sessions/open-session



> Start a new voucher session — groups multiple vouchers under a single context.

`POST /api/v1/vouchers/sessions/session-open`

A session groups multiple vouchers together for multi-payment flows like split payments or multi-currency checkouts. Each voucher in the session is independent (own code, lifecycle, settlement), but they share the session for tracking and coordination.

## Parameters

### Body

| Name        | Type     | Required | Description                                         |
| ----------- | -------- | -------- | --------------------------------------------------- |
| `code`      | `string` | Yes      | The context code shared by the payer. 6 characters. |
| `type`      | `enum`   | Yes      | Session type — always `SESSION_DEFAULT`             |
| `payeeInfo` | `object` | No       | Additional payee information                        |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/sessions/session-open' \
  --header 'Authorization: Bearer <payee_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "A1B2C3",
    "type": "SESSION_DEFAULT"
  }'
```

## Response

### Response schema

| Field       | Type     | Description                                |
| ----------- | -------- | ------------------------------------------ |
| `id`        | `string` | Unique session identifier (e.g. `ses_xyz`) |
| `code`      | `string` | Session code                               |
| `status`    | `string` | Session status — `OPEN`                    |
| `type`      | `string` | Session type                               |
| `createdAt` | `string` | ISO 8601 creation timestamp                |

### Example response

```json theme={null}
{
  "id": "ses_xyz",
  "code": "D4E5F6",
  "status": "OPEN",
  "type": "SESSION_DEFAULT",
  "createdAt": "2026-06-09T12:00:00.000Z"
}
```

### Error responses

| Status | Code           | Description                            |
| ------ | -------------- | -------------------------------------- |
| `400`  | `invalid_code` | The context code is invalid or expired |
| `401`  | `unauthorized` | Missing or invalid bearer token        |


# Reserve Voucher in Session
Source: https://docs.bleepay.com/api-reference/vouchers/sessions/reserve-voucher



> Reserve a voucher within an open session.

`POST /api/v1/vouchers/sessions/:sessionId/reserve-voucher`

Works the same as the standalone `reserve-voucher` endpoint, but scoped to a session. Each voucher reserved in a session is independent — with its own code, lifecycle, and settlement — but tracked together under the session.

## Parameters

### Path

| Name        | Type     | Required | Description    |
| ----------- | -------- | -------- | -------------- |
| `sessionId` | `string` | Yes      | The session ID |

### Body

No body parameters required. The context is derived from the session.

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/sessions/ses_xyz/reserve-voucher' \
  --header 'Authorization: Bearer <payee_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

### Response schema

| Field       | Type     | Description                 |
| ----------- | -------- | --------------------------- |
| `id`        | `string` | Unique voucher identifier   |
| `code`      | `string` | 6-digit voucher code        |
| `status`    | `string` | Voucher status — `RESERVED` |
| `expiresAt` | `string` | ISO 8601 expiry timestamp   |

### Example response

```json theme={null}
{
  "id": "vch_482916",
  "code": "482916",
  "status": "RESERVED",
  "expiresAt": "2026-06-09T12:02:00.000Z"
}
```

### Error responses

| Status | Code             | Description                        |
| ------ | ---------------- | ---------------------------------- |
| `400`  | `session_closed` | Cannot reserve in a closed session |
| `401`  | `unauthorized`   | Missing or invalid bearer token    |
| `404`  | `not_found`      | Session not found                  |

## Next steps

After reserving, [redeem the voucher](/api-reference/vouchers/redeem-voucher) to set the payment terms.


# Sign Voucher
Source: https://docs.bleepay.com/api-reference/vouchers/sign-voucher



> Sign a voucher with a public key.

`POST /api/v1/vouchers/:voucherId/sign-voucher`

Attaches a cryptographic signature to a voucher. This is used for protocols that require an explicit signing step separate from resolution.

## Parameters

### Path

| Name        | Type     | Required | Description            |
| ----------- | -------- | -------- | ---------------------- |
| `voucherId` | `string` | Yes      | The voucher ID to sign |

### Body

| Name        | Type     | Required | Description                                   |
| ----------- | -------- | -------- | --------------------------------------------- |
| `publicKey` | `string` | Yes      | Public key used for signing, 1–256 characters |
| `signature` | `string` | Yes      | Cryptographic signature, 1–256 characters     |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/vch_482916/sign-voucher' \
  --header 'Authorization: Bearer <payer_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "publicKey": "0xPublicKey...",
    "signature": "0xSignature..."
  }'
```

## Response

### Response schema

Returns the updated voucher object with the signature attached.

### Error responses

| Status | Code                | Description                     |
| ------ | ------------------- | ------------------------------- |
| `400`  | `validation_failed` | Invalid or missing fields       |
| `401`  | `unauthorized`      | Missing or invalid bearer token |
| `404`  | `not_found`         | Voucher not found               |


# Submit Interop Signature
Source: https://docs.bleepay.com/api-reference/vouchers/submit-interop



> Initiate cross-chain signature submission for a voucher.

`POST /api/v1/vouchers/:voucherId/submit/interop-init`

Initiates a cross-chain signature submission flow. Used when the voucher requires signatures across multiple blockchain networks.

## Parameters

### Path

| Name        | Type     | Required | Description    |
| ----------- | -------- | -------- | -------------- |
| `voucherId` | `string` | Yes      | The voucher ID |

### Query

| Name           | Type      | Required | Description                              |
| -------------- | --------- | -------- | ---------------------------------------- |
| `id`           | `string`  | Yes      | Signature submission identifier          |
| `paymentIndex` | `integer` | No       | Index of the payment being signed (0–10) |
| `vid`          | `string`  | No       | Voucher ID override for the signature    |

### Body

| Name        | Type     | Required | Description                                   |
| ----------- | -------- | -------- | --------------------------------------------- |
| `signature` | `string` | No       | The cryptographic signature, 1–256 characters |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/vouchers/vch_482916/submit/interop-init?id=sig_abc&paymentIndex=0' \
  --header 'Authorization: Bearer <payer_token>' \
  --header 'Content-Type: application/json' \
  --data '{ "signature": "0xSignature..." }'
```

## Response

Returns `{ "id": "<submission_id>" }` on success.

### Error responses

| Status | Code           | Description                     |
| ------ | -------------- | ------------------------------- |
| `401`  | `unauthorized` | Missing or invalid bearer token |
| `404`  | `not_found`    | Voucher not found               |


# Create Webhook Endpoint
Source: https://docs.bleepay.com/api-reference/webhooks/create-endpoint



> Register a webhook endpoint to receive payment event notifications.

`POST /api/v1/widgets/webhook-endpoints/create-endpoint`

Webhooks are dispatched as signed HTTP POST requests with HMAC-SHA256 signatures. You can subscribe to specific event types and register multiple endpoints per widget.

## Parameters

### Body

| Name          | Type     | Required | Description                                 |
| ------------- | -------- | -------- | ------------------------------------------- |
| `widgetId`    | `string` | Yes      | The widget ID                               |
| `url`         | `string` | Yes      | HTTPS URL to deliver events to              |
| `description` | `string` | No       | Human-readable description of this endpoint |
| `events`      | `array`  | Yes      | List of event types to subscribe to         |

**Supported event types:**

| Event Type          | Description                                    |
| ------------------- | ---------------------------------------------- |
| `deposit.created`   | Deposit session created                        |
| `deposit.pending`   | On-chain payment detected                      |
| `deposit.confirmed` | Payment confirmed after block confirmations    |
| `deposit.expired`   | Session expired without payment                |
| `deposit.failed`    | Deposit failed                                 |
| `deposit.underpaid` | Payment received below the expected amount     |
| `deposit.overpaid`  | Payment received above the expected amount     |
| `deposit.unmatched` | Payment received but no matching session found |
| `refund.confirmed`  | Refund confirmed on-chain                      |
| `refund.expired`    | Refund received after session expired          |
| `refund.failed`     | Refund failed                                  |
| `refund.unmatched`  | Refund received but no matching session found  |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/webhook-endpoints/create-endpoint' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "widgetId": "wdgt_abc",
    "url": "https://example.com/webhooks/bleepay",
    "description": "Production webhook endpoint",
    "events": ["deposit.pending", "deposit.confirmed", "deposit.expired", "refund.confirmed"]
  }'
```

## Response

### Response schema

| Field           | Type      | Description                                                   |
| --------------- | --------- | ------------------------------------------------------------- |
| `id`            | `string`  | Endpoint identifier                                           |
| `url`           | `string`  | Delivery URL                                                  |
| `events`        | `array`   | Subscribed event types                                        |
| `enabled`       | `boolean` | Whether the endpoint is active                                |
| `signingSecret` | `string`  | Secret for verifying webhook signatures — **shown only once** |

### Example response

```json theme={null}
{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/bleepay",
  "description": "Production webhook endpoint",
  "events": ["deposit.pending", "deposit.confirmed", "deposit.expired", "refund.confirmed"],
  "enabled": true,
  "signingSecret": "whsec_abc123def456..."
}
```

> **Warning:** The `signingSecret` is shown only once at creation time. Store it securely — you'll need it to verify webhook payload signatures.


# Delete Webhook Endpoint
Source: https://docs.bleepay.com/api-reference/webhooks/delete-endpoint



> Permanently delete a webhook endpoint.

`POST /api/v1/widgets/webhook-endpoints/:endpointId/delete-endpoint`

Deleted endpoints cannot be recovered. Any pending deliveries for this endpoint are cancelled.

## Parameters

### Path

| Name         | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `endpointId` | `string` | Yes      | The endpoint ID |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/webhook-endpoints/wh_abc123/delete-endpoint' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

Returns HTTP 200 with an empty body.


# Disable Webhook Endpoint
Source: https://docs.bleepay.com/api-reference/webhooks/disable-endpoint



> Disable a webhook endpoint — pauses event delivery.

`POST /api/v1/widgets/webhook-endpoints/:endpointId/disable-endpoint`

Disabled endpoints do not receive webhook deliveries. Events for this endpoint are not queued while disabled.

## Parameters

### Path

| Name         | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `endpointId` | `string` | Yes      | The endpoint ID |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/webhook-endpoints/wh_abc123/disable-endpoint' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

Returns HTTP 200 with an empty body.


# Enable Webhook Endpoint
Source: https://docs.bleepay.com/api-reference/webhooks/enable-endpoint



> Enable a disabled webhook endpoint.

`POST /api/v1/widgets/webhook-endpoints/:endpointId/enable-endpoint`

## Parameters

### Path

| Name         | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `endpointId` | `string` | Yes      | The endpoint ID |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/webhook-endpoints/wh_abc123/enable-endpoint' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

Returns HTTP 200 with an empty body.


# Get Webhook Delivery
Source: https://docs.bleepay.com/api-reference/webhooks/get-delivery



> Retrieve a single webhook delivery by its ID.

`GET /api/v1/widgets/webhook-deliveries/:deliveryId`

Returns the full details of a webhook delivery attempt, including request/response information.

## Parameters

### Path

| Name         | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `deliveryId` | `string` | Yes      | The delivery ID |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/webhook-deliveries/dly_abc123' \
  --header 'Authorization: Bearer <business_token>'
```

## Response

### Response schema

| Field           | Type                | Description                                     |
| --------------- | ------------------- | ----------------------------------------------- |
| `id`            | `string`            | Delivery identifier                             |
| `eventType`     | `string`            | Event type                                      |
| `endpointId`    | `string`            | The endpoint this delivery was sent to          |
| `status`        | `string`            | `PENDING`, `DELIVERED`, `FAILED`, or `RETRYING` |
| `attempts`      | `integer`           | Number of attempts                              |
| `requestUrl`    | `string`            | URL the request was sent to                     |
| `requestBody`   | `string`            | JSON payload that was sent                      |
| `responseCode`  | `integer` or `null` | HTTP response code from the endpoint            |
| `responseBody`  | `string` or `null`  | Response body from the endpoint                 |
| `lastAttemptAt` | `string` or `null`  | ISO 8601 last attempt timestamp                 |
| `createdAt`     | `string`            | ISO 8601 creation timestamp                     |


# Get Webhook Endpoint
Source: https://docs.bleepay.com/api-reference/webhooks/get-endpoint



> Retrieve a webhook endpoint by its ID.

`GET /api/v1/widgets/webhook-endpoints/:endpointId`

Returns the configuration of a single webhook endpoint. The signing secret is **not** returned.

## Parameters

### Path

| Name         | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `endpointId` | `string` | Yes      | The endpoint ID |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/webhook-endpoints/wh_abc123' \
  --header 'Authorization: Bearer <business_token>'
```

## Response

### Response schema

| Field         | Type      | Description                    |
| ------------- | --------- | ------------------------------ |
| `id`          | `string`  | Endpoint identifier            |
| `url`         | `string`  | Delivery URL                   |
| `description` | `string`  | Human-readable description     |
| `events`      | `array`   | Subscribed event types         |
| `enabled`     | `boolean` | Whether the endpoint is active |
| `createdAt`   | `string`  | ISO 8601 creation timestamp    |
| `updatedAt`   | `string`  | ISO 8601 last update timestamp |

### Example response

```json theme={null}
{
  "id": "wh_abc123",
  "url": "https://example.com/webhooks/bleepay",
  "description": "Production webhook endpoint",
  "events": ["deposit.pending", "deposit.confirmed", "deposit.expired"],
  "enabled": true,
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:00:00.000Z"
}
```


# Query Webhook Deliveries
Source: https://docs.bleepay.com/api-reference/webhooks/query-deliveries



> List webhook delivery attempts for a business.

`GET /api/v1/widgets/webhook-deliveries`

Returns a list of webhook delivery attempts with their status. Failed deliveries are automatically retried up to 3 times at 30-second intervals.

## Parameters

### Query

| Name     | Type      | Required | Description                                                 |
| -------- | --------- | -------- | ----------------------------------------------------------- |
| `limit`  | `integer` | No       | Number of items (default 100)                               |
| `offset` | `integer` | No       | Pagination offset                                           |
| `since`  | `integer` | No       | Unix timestamp (ms) — return items created after this time  |
| `until`  | `integer` | No       | Unix timestamp (ms) — return items created before this time |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/webhook-deliveries?limit=20' \
  --header 'Authorization: Bearer <business_token>'
```

## Response

**Delivery object:**

| Field           | Type               | Description                                                   |
| --------------- | ------------------ | ------------------------------------------------------------- |
| `id`            | `string`           | Delivery identifier                                           |
| `eventType`     | `string`           | Event type (e.g. `deposit.confirmed`)                         |
| `status`        | `string`           | Delivery status: `PENDING`, `DELIVERED`, `FAILED`, `RETRYING` |
| `attempts`      | `integer`          | Number of delivery attempts made                              |
| `lastAttemptAt` | `string` or `null` | ISO 8601 timestamp of last attempt                            |
| `createdAt`     | `string`           | ISO 8601 creation timestamp                                   |

### Example response

```json theme={null}
[
  {
    "id": "dly_abc123",
    "eventType": "deposit.confirmed",
    "status": "DELIVERED",
    "attempts": 1,
    "lastAttemptAt": "2026-06-09T12:05:00.000Z",
    "createdAt": "2026-06-09T12:05:00.000Z"
  }
]
```


# Query Webhook Endpoints
Source: https://docs.bleepay.com/api-reference/webhooks/query-endpoints



> List all webhook endpoints for a business.

`GET /api/v1/widgets/webhook-endpoints`

Returns a list of all webhook endpoints registered for the business.

## Parameters

### Query

| Name     | Type      | Required | Description                                                 |
| -------- | --------- | -------- | ----------------------------------------------------------- |
| `limit`  | `integer` | No       | Number of items (default 100)                               |
| `offset` | `integer` | No       | Pagination offset                                           |
| `since`  | `integer` | No       | Unix timestamp (ms) — return items created after this time  |
| `until`  | `integer` | No       | Unix timestamp (ms) — return items created before this time |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/webhook-endpoints' \
  --header 'Authorization: Bearer <business_token>'
```

## Response

Returns an array of endpoint objects. See [Get Endpoint](/api-reference/webhooks/get-endpoint) for the object schema.

### Example response

```json theme={null}
[
  {
    "id": "wh_abc123",
    "url": "https://example.com/webhooks/bleepay",
    "description": "Production webhook endpoint",
    "events": ["deposit.pending", "deposit.confirmed"],
    "enabled": true,
    "createdAt": "2026-06-09T12:00:00.000Z"
  }
]
```


# Retry Webhook Delivery
Source: https://docs.bleepay.com/api-reference/webhooks/retry-delivery



> Manually retry a failed webhook delivery.

`POST /api/v1/widgets/webhook-deliveries/:deliveryId/retry-delivery`

Triggers an immediate retry of a previously failed delivery. This is in addition to the automatic retry schedule (up to 3 retries at 30-second intervals).

## Parameters

### Path

| Name         | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `deliveryId` | `string` | Yes      | The delivery ID |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/webhook-deliveries/dly_abc123/retry-delivery' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

Returns HTTP 200 with an empty body.


# Rotate Webhook Signing Secret
Source: https://docs.bleepay.com/api-reference/webhooks/rotate-secret



> Rotate the HMAC-SHA256 signing secret for a webhook endpoint.

`POST /api/v1/widgets/webhook-endpoints/:endpointId/rotate-endpoint-secret`

Generates a new signing secret for the endpoint. The old secret is immediately invalidated. Use this for key rotation or if a secret has been compromised.

> **Warning:** The new signing secret is shown only once. Store it securely before confirming the rotation.

## Parameters

### Path

| Name         | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `endpointId` | `string` | Yes      | The endpoint ID |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/webhook-endpoints/wh_abc123/rotate-endpoint-secret' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

### Response schema

| Field           | Type     | Description                              |
| --------------- | -------- | ---------------------------------------- |
| `id`            | `string` | Endpoint identifier                      |
| `signingSecret` | `string` | New signing secret — **shown only once** |

### Example response

```json theme={null}
{
  "id": "wh_abc123",
  "signingSecret": "whsec_newsecret123..."
}
```


# Update Webhook Endpoint
Source: https://docs.bleepay.com/api-reference/webhooks/update-endpoint



> Update a webhook endpoint's configuration.

`POST /api/v1/widgets/webhook-endpoints/:endpointId/update-endpoint`

## Parameters

### Path

| Name         | Type     | Required | Description     |
| ------------ | -------- | -------- | --------------- |
| `endpointId` | `string` | Yes      | The endpoint ID |

### Body

| Name          | Type     | Required | Description                 |
| ------------- | -------- | -------- | --------------------------- |
| `url`         | `string` | No       | New HTTPS URL for delivery  |
| `description` | `string` | No       | Updated description         |
| `events`      | `array`  | No       | Updated list of event types |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/webhook-endpoints/wh_abc123/update-endpoint' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/webhooks/v2",
    "events": ["deposit.pending", "deposit.confirmed", "deposit.expired", "deposit.underpaid"]
  }'
```

## Response

Returns HTTP 200 with an empty body.


# Create Widget
Source: https://docs.bleepay.com/api-reference/widgets/management/create-widget



> Create and configure a new payment widget for a business.

`POST /api/v1/widgets/create-widget`

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

## Parameters

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


# Delete Widget
Source: https://docs.bleepay.com/api-reference/widgets/management/delete-widget



> Permanently delete a widget.

`POST /api/v1/widgets/:widgetId/delete-widget`

Deleted widgets cannot be recovered. Active deposit sessions for this widget are not affected.

## Parameters

### Path

| Name       | Type     | Required | Description   |
| ---------- | -------- | -------- | ------------- |
| `widgetId` | `string` | Yes      | The widget ID |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/wdgt_abc/delete-widget' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

Returns HTTP 200 with an empty body.


# Disable Widget
Source: https://docs.bleepay.com/api-reference/widgets/management/disable-widget



> Deactivate a widget — stops accepting new deposit sessions.

`POST /api/v1/widgets/:widgetId/disable-widget`

Existing deposit sessions are unaffected. New sessions cannot be created while the widget is disabled.

## Parameters

### Path

| Name       | Type     | Required | Description   |
| ---------- | -------- | -------- | ------------- |
| `widgetId` | `string` | Yes      | The widget ID |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/wdgt_abc/disable-widget' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

Returns HTTP 200 with an empty body.


# Enable Widget
Source: https://docs.bleepay.com/api-reference/widgets/management/enable-widget



> Activate a disabled widget.

`POST /api/v1/widgets/:widgetId/enable-widget`

## Parameters

### Path

| Name       | Type     | Required | Description   |
| ---------- | -------- | -------- | ------------- |
| `widgetId` | `string` | Yes      | The widget ID |

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/wdgt_abc/enable-widget' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

Returns HTTP 200 with an empty body.


# Get Widget
Source: https://docs.bleepay.com/api-reference/widgets/management/get-widget



> Retrieve a widget by its ID.

`GET /api/v1/widgets/:widgetId`

## Parameters

### Path

| Name       | Type     | Required | Description   |
| ---------- | -------- | -------- | ------------- |
| `widgetId` | `string` | Yes      | The widget ID |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/wdgt_abc' \
  --header 'Authorization: Bearer <business_token>'
```

## Response

Returns the full widget configuration object. See [Create Widget](/api-reference/widgets/management/create-widget) for the field schema.

```json theme={null}
{
  "id": "wdgt_abc",
  "name": "Checkout Widget",
  "mode": "CUSTOMER_AMOUNT",
  "minAmount": "1",
  "maxAmount": "1000",
  "allowedNetworks": ["polygon", "ethereum"],
  "allowedCurrencies": ["USDC", "EURC"],
  "enabled": true,
  "createdAt": "2026-06-09T12:00:00.000Z",
  "updatedAt": "2026-06-09T12:00:00.000Z"
}
```


# Query Widgets
Source: https://docs.bleepay.com/api-reference/widgets/management/query-widgets



> List all widgets for a business.

`GET /api/v1/widgets`

## Parameters

### Query

| Name     | Type      | Required | Description                                                 |
| -------- | --------- | -------- | ----------------------------------------------------------- |
| `limit`  | `integer` | No       | Number of items (default 100)                               |
| `offset` | `integer` | No       | Pagination offset                                           |
| `since`  | `integer` | No       | Unix timestamp (ms) — return items created after this time  |
| `until`  | `integer` | No       | Unix timestamp (ms) — return items created before this time |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets' \
  --header 'Authorization: Bearer <business_token>'
```

## Response

Returns an array of widget objects. See [Get Widget](/api-reference/widgets/management/get-widget) for the object schema.

### Example response

```json theme={null}
[
  {
    "id": "wdgt_abc",
    "name": "Checkout Widget",
    "mode": "CUSTOMER_AMOUNT",
    "enabled": true,
    "createdAt": "2026-06-09T12:00:00.000Z"
  }
]
```


# Update Widget
Source: https://docs.bleepay.com/api-reference/widgets/management/update-widget



> Update a widget's configuration.

`POST /api/v1/widgets/:widgetId/update-widget`

All body parameters are optional — only provide the fields you want to change.

## Parameters

### Path

| Name       | Type     | Required | Description   |
| ---------- | -------- | -------- | ------------- |
| `widgetId` | `string` | Yes      | The widget ID |

### Body

Same shape as [Create Widget](/api-reference/widgets/management/create-widget), but all fields are optional.

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/wdgt_abc/update-widget' \
  --header 'Authorization: Bearer <business_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Checkout",
    "maxAmount": "5000"
  }'
```

## Response

Returns HTTP 200 with an empty body.


# Cancel Deposit Session
Source: https://docs.bleepay.com/api-reference/widgets/public/cancel-session



> Cancel a deposit session before funds are sent.

`POST /api/v1/widgets/deposit-sessions/:sessionId/cancel-session`

Cancels a deposit session. Only sessions in `CREATED` or `PENDING` status can be cancelled. Cancelled sessions move to `EXPIRED` status.

## Parameters

### Path

| Name        | Type     | Required | Description                      |
| ----------- | -------- | -------- | -------------------------------- |
| `sessionId` | `string` | Yes      | The deposit session ID to cancel |

### Body

No body parameters required.

## Request example

```shell theme={null}
curl --request POST 'https://payments.bleepay.com/api/v1/widgets/deposit-sessions/dep_a1b2c3d4e5f6/cancel-session' \
  --header 'X-Client-Secret: dep_secret_xyz...' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Response

### Response schema

| Field    | Type     | Description                          |
| -------- | -------- | ------------------------------------ |
| `status` | `string` | Result status                        |
| `error`  | `string` | Error message if cancellation failed |

### Example response

```json theme={null}
{
  "status": "cancelled"
}
```

### Error responses

| Status | Code            | Description                             |
| ------ | --------------- | --------------------------------------- |
| `400`  | `cannot_cancel` | Session is already confirmed or expired |
| `401`  | `unauthorized`  | Missing or invalid authentication       |
| `404`  | `not_found`     | Session not found                       |


# Create Deposit Session
Source: https://docs.bleepay.com/api-reference/widgets/public/create-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

```shell theme={null}
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": "customer@example.com",
    "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

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


# Get Widget Config
Source: https://docs.bleepay.com/api-reference/widgets/public/get-config



> Get the public configuration for a widget.

`GET /api/v1/widgets/:widgetId/config`

Returns the public configuration of a widget — the currencies it accepts, min/max amounts, and display settings. Used by the embedded widget to render the customer-facing payment form.

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

## Parameters

### Path

| Name       | Type     | Required | Description   |
| ---------- | -------- | -------- | ------------- |
| `widgetId` | `string` | Yes      | The widget ID |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/wdgt_abc/config' \
  --header 'X-Client-Secret: wdgt_secret_abc123...'
```

## Response

### Response schema

| Field    | Type               | Description                                                                    |
| -------- | ------------------ | ------------------------------------------------------------------------------ |
| `config` | `object` or `null` | Widget configuration, or `null` if the widget is inactive or domain-restricted |
| `reason` | `string`           | Reason why config is `null` (if applicable)                                    |

**Config object:**

| Field                     | Type               | Description                             |
| ------------------------- | ------------------ | --------------------------------------- |
| `name`                    | `string`           | Widget display name                     |
| `mode`                    | `string`           | `FIXED_AMOUNT` or `CUSTOMER_AMOUNT`     |
| `minAmount`               | `string`           | Minimum deposit amount                  |
| `maxAmount`               | `string`           | Maximum deposit amount                  |
| `allowedNetworks`         | `array`            | Accepted blockchain networks            |
| `allowedCurrencies`       | `array`            | Accepted currencies                     |
| `allowedDepositAddresses` | `array`            | Allowed destination addresses           |
| `allowedMethods`          | `array`            | Accepted payment methods                |
| `renderMode`              | `string`           | `IFRAME` or `POPUP`                     |
| `iconUrl`                 | `string` or `null` | Widget icon URL                         |
| `color`                   | `string` or `null` | Widget accent color                     |
| `emoji`                   | `string` or `null` | Widget emoji                            |
| `defaultCurrency`         | `string` or `null` | Default currency                        |
| `defaultCurrencyAddress`  | `string` or `null` | Default currency contract address       |
| `defaultNetwork`          | `string` or `null` | Default blockchain network              |
| `defaultDepositAddress`   | `string` or `null` | Default deposit destination             |
| `metadataSchema`          | `object` or `null` | JSON schema for custom metadata         |
| `allowAllOrigins`         | `boolean`          | Whether all origins are allowed         |
| `allowAllMethods`         | `boolean`          | Whether all payment methods are allowed |

### Example response

```json theme={null}
{
  "config": {
    "name": "Checkout Widget",
    "mode": "CUSTOMER_AMOUNT",
    "minAmount": "1",
    "maxAmount": "1000",
    "allowedNetworks": ["polygon", "ethereum"],
    "allowedCurrencies": ["USDC", "EURC"],
    "allowedMethods": [],
    "renderMode": "IFRAME",
    "iconUrl": null,
    "color": null,
    "emoji": null
  }
}
```

### Error responses

| Status | Code           | Description                       |
| ------ | -------------- | --------------------------------- |
| `401`  | `unauthorized` | Missing or invalid authentication |
| `404`  | `not_found`    | Widget not found                  |


# Get Deposit Session
Source: https://docs.bleepay.com/api-reference/widgets/public/get-session



> Check the status of a deposit session.

`GET /api/v1/widgets/deposit-sessions/:sessionId`

Returns the current state of a deposit session, including whether the payment has been detected on-chain and confirmed.

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

## Parameters

### Path

| Name        | Type     | Required | Description            |
| ----------- | -------- | -------- | ---------------------- |
| `sessionId` | `string` | Yes      | The deposit session ID |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/deposit-sessions/dep_a1b2c3d4e5f6' \
  --header 'X-Client-Secret: dep_secret_xyz...'
```

## Response

### Response schema

| Field             | Type               | Description                                                                   |
| ----------------- | ------------------ | ----------------------------------------------------------------------------- |
| `id`              | `string`           | Session identifier                                                            |
| `paymentStatus`   | `string`           | Status: `CREATED`, `PENDING`, `CONFIRMED`, `EXPIRED`, `UNDERPAID`, `OVERPAID` |
| `amount`          | `string`           | Payment amount                                                                |
| `currency`        | `string`           | Currency symbol                                                               |
| `network`         | `string`           | Blockchain network                                                            |
| `currencyAddress` | `string`           | Currency contract address                                                     |
| `depositAddress`  | `string`           | Destination address                                                           |
| `txId`            | `string` or `null` | Blockchain transaction hash (set when `PENDING` or `CONFIRMED`)               |
| `expiresAt`       | `string`           | ISO 8601 expiry timestamp                                                     |
| `confirmedAt`     | `string` or `null` | ISO 8601 confirmation timestamp                                               |

### Example response

```json theme={null}
{
  "id": "dep_a1b2c3d4e5f6",
  "paymentStatus": "CONFIRMED",
  "amount": "100",
  "currency": "USDC",
  "network": "polygon",
  "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "depositAddress": "0xMerchantWalletAddress",
  "txId": "0xabc123def456...",
  "expiresAt": "2026-06-09T12:30:00.000Z",
  "confirmedAt": "2026-06-09T12:05:00.000Z"
}
```

### Error responses

| Status | Code           | Description                       |
| ------ | -------------- | --------------------------------- |
| `401`  | `unauthorized` | Missing or invalid authentication |
| `404`  | `not_found`    | Session not found                 |


# Bleepay Wallet & Vouchers — A Native Payment Method
Source: https://docs.bleepay.com/home/architecture/bleepay-wallet



# Bleepay Wallet & Vouchers — A Native Payment Method

> A payer pays by entering a 6-digit code and confirming it in the non-custodial Bleepay Wallet app.

The voucher method lets a payment be initiated with a **6-digit code** instead of wallet addresses and network selection.

The payer's experience:

1. A **6-digit code** is generated (the voucher).
2. The payer **enters the code in the Widget** (or in a standalone integration).
3. Bleepay **generates the transaction(s) associated with the voucher**.
4. The payer **signs and sends** those transactions in the **Bleepay Wallet** app.

## The Bleepay Wallet

The Bleepay Wallet is a **mobile app (iOS / Android)** and is **non-custodial**: the user holds their own funds and keys. Bleepay's role is to **generate the transactions tied to a voucher** and present them in the app; the user then **signs and broadcasts them themselves**. Bleepay never holds the user's funds. This keeps the experience simple — a code and a tap — without Bleepay taking custody.

The wallet that generates voucher codes is currently the Bleepay Wallet; the design anticipates other wallets generating codes in future.

## Integration modes

* **Standalone** — integrated on its own as a payment method.
* **Inside the Widget** — surfaced as a payment option within the Widget, **enabled by default**.

## Voucher types: SIMPLE vs CUSTOM

The system supports two voucher types, chosen automatically from how the payee sets up the payment.

|                      | SIMPLE                                                 | CUSTOM                                                      |
| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
| Represents           | A plain token transfer (currency + amount + recipient) | Explicit, possibly multi-step transaction instructions      |
| Network selection    | Automatic                                              | Specified by payee                                          |
| Smart-contract calls | No                                                     | Yes                                                         |
| Supports FX          | **Yes**                                                | No                                                          |
| Typical use          | "Send me 100 USDC"                                     | Contract interaction, multi-step DeFi, conditional payments |

The general voucher lifecycle is **reserve → redeem → resolve**.

## Next steps

* [Payment flows](/architecture/payment-flows) — how vouchers move through the system.
* [Custody model](/architecture/custody-model) — non-custodial design.
* [Simple Payments](/web2-web3-payments/simple-payments) — using SIMPLE vouchers.


# Bleepay Widget — Crypto Payment Gateway
Source: https://docs.bleepay.com/home/architecture/bleepay-widget



# Bleepay Widget — Crypto Payment Gateway

> An embeddable (or white-label) gateway a merchant configures once to accept crypto, settling in crypto or fiat.

The Widget is the merchant-facing product. A merchant integrates it in one of two ways:

* **Embedded Widget** — a drop-in component on a checkout/payment page (the customer-visible "pay with crypto" experience).
* **White-label** — the same capability integrated under the merchant's own brand.

From the customer's point of view it is a simple form: choose a currency, enter or confirm an amount, send funds. All blockchain complexity is handled by the system.

## What the merchant configures

A merchant sets up one or more Widgets from a dashboard and configures:

* a **mode**: `FIXED_AMOUNT` (merchant sets the price) or `DYNAMIC_AMOUNT` (amount set dynamically, e.g. a checkout total, within min/max limits);
* **min/max** deposit amounts;
* accepted **blockchain networks and currencies**;
* the **wallet address** where funds should be sent;
* optional **domain restrictions** (which websites may host the Widget);
* optional **success/cancel redirect URLs**;
* an optional **metadata schema** (e.g. order IDs).

A merchant may have **up to 10 Widgets**, each independent.

In every settlement option, funds land at the **merchant's own address or a partner's address** — Bleepay does not sit in the middle holding them (see [Custody model](/architecture/custody-model)).

## Next steps

* [Bleepay Wallet](/architecture/bleepay-wallet) — the voucher-based payment method.
* [Payment flows](/architecture/payment-flows) — end-to-end flow details.
* [Custody model](/architecture/custody-model) — how funds move.


# Custody Model
Source: https://docs.bleepay.com/home/architecture/custody-model



# Custody Model

> Non-custodial across both products; Bleepay never holds users' funds.

"Custody" means holding, or being able to control and move, another party's funds or the keys to them. **Bleepay is non-custodial across both products** — it never holds users' funds.

| Product / path                | Custody           | What it means                                                                                                                                      |
| ----------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bleepay Widget (gateway)**  | **Non-custodial** | Funds land at the merchant's own address (or a partner's address for fiat payouts) — never an address Bleepay controls                             |
| **Bleepay Wallet (vouchers)** | **Non-custodial** | The Bleepay Wallet is a mobile app where the user holds their own funds and keys; Bleepay only builds the transaction, the user signs and sends it |

* On the **gateway**, payments move directly from the customer to the merchant's (or a partner's) address. Bleepay's role is to monitor the blockchain, validate each payment, and notify the merchant.
* In the **Bleepay Wallet**, the user controls their own funds. Bleepay generates the transactions linked to a voucher; the user **signs and broadcasts them from the iOS / Android app** with their own keys.

> The only party other than the user and merchant that ever holds funds is the **fiat payout partner**, and only transiently during the crypto→fiat off-ramp.

```mermaid theme={null}
flowchart LR
    subgraph Gateway [Widget gateway - non-custodial]
      C([Customer]) --> M[(Merchant / partner address)]
    end
    subgraph WalletPath [Bleepay Wallet - non-custodial]
      U([User holds own funds]) --> Sign[User signs & sends] --> S[(Payee)]
    end
```

## Next steps

* [Security](/architecture/security) — zero-trust and non-custodial model.
* [How money moves](/architecture/how-money-moves) — fund flows by scenario.


# Dependency Management
Source: https://docs.bleepay.com/home/architecture/dependencies



# Dependency Management

> Modular design to avoid vendor lock-in and ensure resilience.

To avoid vendor lock-in and improve resilience, Bleepay's architecture is **strictly modular**.

## Interchangeable off-ramps

The **fiat liquidation rail** is provider-agnostic. Bleepay can swap or add providers based on:

* Geographic coverage
* Fee structures
* Merchant-specific agreements
* Regulatory requirements

Merchants and partners are not tied to a single off-ramp provider.

## Pluggable bridging

**Stargate** is the current default for reliability and speed. The **bridging layer** is modular: alternative protocols can be plugged in to:

* Ensure continuous availability
* Mitigate third-party protocol risk
* Support different chains or cost/UX tradeoffs

This reduces dependence on a single bridge implementation.

## Multiple provider aggregation

Bleepay aggregates several providers for both FX and fiat off-ramp:

| Provider type                                | Role                                                                                      |
| -------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Fiat off-ramp partners** (e.g. Bridge.xyz) | Create and operate liquidation addresses, convert crypto→fiat, send fiat to bank accounts |
| **Crypto exchange / swap providers**         | Provide quotes and execute crypto→crypto swaps for in-flight FX                           |
| **Blockchain networks**                      | The settlement layer for on-chain transfers                                               |

## Benefits

* **Continuity**: If one provider or protocol has an outage or policy change, alternatives can be used.
* **Commercial flexibility**: Different partners and fee models can be supported per region or merchant.
* **Future-proofing**: New chains, bridges, or off-ramps can be integrated without redesigning the core orchestration.

## Next steps

* [Fees](/architecture/fees) — how network, routing, and liquidation costs are structured.
* [Payment flows](/architecture/payment-flows) — where off-ramp and swap fit.


# Fee Structure
Source: https://docs.bleepay.com/home/architecture/fees



# Fee Structure

> Transaction cost layers and commercial terms.

Transaction costs are typically categorized into a few layers. Exact numbers and commercial terms are finalized during onboarding with selected liquidity and settlement partners.

## Cost layers (overview)

| Layer                        | Typical range (indicative)       | Description                                                                           |
| ---------------------------- | -------------------------------- | ------------------------------------------------------------------------------------- |
| **Network & routing**        | \~0.06% baseline + LayerZero/gas | Atomic swap and bridge to USDC/USDT (or target stablecoin); gas and cross-chain fees. |
| **Liquidation & settlement** | \~0.5% – 1.5%                    | Stable-to-fiat conversion and SEPA/banking rails (provider-dependent).                |

* **Network & routing**: Covers DEX swap, bridge (e.g. Stargate/LayerZero), and gas. The baseline percentage is indicative; actual cost depends on chain, volume, and route.
* **Liquidation & settlement**: Covers the off-ramp provider's conversion and bank transfer fees. Range depends on partner, region, and volume.

## Commercial terms

* Final pricing and fee splits are agreed **during onboarding** with the selected liquidity and settlement partners.
* Merchants may see a single blended fee or a breakdown (e.g. Bleepay + network + liquidation); details are provided in the dashboard or contract.

## Next steps

* [Payment flows](/architecture/payment-flows) — where liquidation and settlement costs apply.
* [Integration overview](/web2-web3-payments/overview) — how to go live and access production pricing.


# How Money Moves
Source: https://docs.bleepay.com/home/architecture/how-money-moves



# How Money Moves

> Who holds funds at each step — Bleepay never does (only the fiat partner, and only briefly).

Where funds go and who holds them at each step, by scenario:

**A. Crypto in, same token out.** Customer sends token X on-chain → **merchant's own address**. Bleepay monitors, validates, notifies; it holds nothing.

**B. Crypto in, different crypto out (FX).** Payer sends token B → **swap/exchange service** converts → payee receives token A. Bleepay quotes and orchestrates.

**C. Crypto in, fiat out (off-ramp).** Payer sends crypto → (optional swap) → **liquidation address held by the fiat partner** → partner converts crypto→fiat → fiat to the payee's bank. The fiat partner holds and moves funds across the fiat leg; Bleepay arranges and orchestrates.

**D. Voucher payment.** The payer holds their own funds in the Bleepay Wallet app. Bleepay builds the voucher transaction; the **payer signs and sends it themselves**. Funds go from the payer to the payee; Bleepay never holds them.

## Summary

| Scenario      | Who holds funds                                  |
| ------------- | ------------------------------------------------ |
| Same token    | Merchant's own address                           |
| Crypto FX     | Swap service (transiently)                       |
| Fiat off-ramp | Fiat partner's liquidation address (transiently) |
| Voucher       | Payer holds own funds; signs and sends directly  |

```mermaid theme={null}
flowchart TD
    subgraph A[A. Same token]
      P1[Customer] --> M1[(Merchant's own address)]
    end
    subgraph B[B. Crypto FX]
      P2[Payer token B] --> SW{{Swap service}} --> PA[(Payee token A)]
    end
    subgraph C[C. Fiat off-ramp]
      P3[Payer crypto] --> SW2{{Swap?}} --> LQ[(Liquidation addr<br/>= partner)] --> BANK[(Payee bank)]
    end
    subgraph D[D. Voucher]
      U[Payer signs & sends<br/>own funds] --> SET[(Payee)]
    end
```

## Next steps

* [Custody model](/architecture/custody-model) — non-custodial across both products.
* [Security](/architecture/security) — zero-trust design.


# Onboarding & KYC/KYB
Source: https://docs.bleepay.com/home/architecture/onboarding-kyc-kyb



# Onboarding & KYC/KYB

> Merchants taking fiat complete KYC/KYB; crypto-only merchants have a lighter path.

KYC (Know Your Customer — individuals) and KYB (Know Your Business — entities) are the identity-verification steps a business completes when getting set up.

* A merchant that registers and wants to **receive fiat** (have crypto payments converted and paid out to a bank account) completes **KYC/KYB** as part of onboarding. This is a standard requirement wherever payments reach the traditional banking system, and the fiat payout partner has its own onboarding requirements too.
* Onboarding collects identity information about the business and the people behind it and, for fiat payouts, the bank account details funds will be sent to.
* A merchant who only settles in **crypto** (to their own wallet address) has a lighter onboarding path, since funds never enter the banking system through Bleepay.

## Next steps

* [Payment flows](/architecture/payment-flows) — where off-ramp and liquidation fit.
* [Security](/architecture/security) — zero-trust model.


# Payment Flows
Source: https://docs.bleepay.com/home/architecture/payment-flows



# Payment Flows

> Four flows, from a plain same-token deposit to a full crypto→fiat payout.

## Widget deposit (same token)

The base case: a customer pays a merchant on-chain, in the token the merchant accepts, with no conversion.

1. **Merchant configures a Widget** — mode, min/max, accepted networks/currencies, the destination wallet address, domain restrictions, optional metadata. A client secret is issued for embedding.
2. **Merchant embeds the Widget** on their site.
3. **Customer opens the Widget** — it fetches public config; the system validates the Widget is active and (if set) the host domain is allowed.
4. **Widget creates a Deposit Session** — the system validates every field (amount within min/max, allowed network, allowed currency, deposit address in the allowed list, metadata against schema), creates the session in `CREATED` status with a **30-minute expiry**, and issues a one-time client secret.
5. **Customer sends funds** from their own wallet to the deposit address.
6. **Payment detected** — the system matches the on-chain transaction to the session; status → `PENDING`; `deposit.pending` webhook dispatched.
7. **Payment confirmed** — after required block confirmations, status → `CONFIRMED`; transaction hash and timestamp recorded; `deposit.confirmed` webhook dispatched.
8. **Merchant notified** — a signed (HMAC-SHA256) webhook to each registered endpoint; up to 3 retries at 30-second intervals.

Edge cases: `EXPIRED` (no funds in 30 min), `UNDERPAID`, `OVERPAID`, customer cancellation (only from `CREATED`/`PENDING`), and domain-restriction blocks.

```mermaid theme={null}
flowchart LR
    Payer([Customer wallet]) -- "token X on-chain" --> MerchantAddr[(Merchant's own address)]
    Bleepay[[Bleepay system]] -. "monitors chain<br/>validates, notifies" .-> MerchantAddr
```

Funds move directly from the customer's wallet to the merchant's own address; Bleepay monitors, validates, and notifies.

## Voucher payment (6-digit code)

1. A **6-digit code** (voucher) is generated in the Bleepay Wallet.
2. The payer **enters the code in the Widget** (or a standalone integration).
3. Bleepay **builds the transaction(s)** associated with the voucher (lifecycle **reserve → redeem → resolve**):
   * **reserve** — the voucher is set aside for a payment;
   * **redeem** — the payee defines the expected payment (currency, amount, recipient), making it **SIMPLE**, or supplies explicit networks/payments/extras, making it **CUSTOM**;
   * **resolve** — the transaction is finalised for signing.
4. The payer **signs and sends** the transaction in the Bleepay Wallet app, from their own funds.

The payer holds their own funds throughout; Bleepay prepares the transaction but the payer signs and broadcasts it. A SIMPLE voucher can also carry FX.

```mermaid theme={null}
flowchart TD
    Gen[Bleepay Wallet app<br/>generates 6-digit code]
    Enter[Widget / integration<br/>payer enters code]
    Build[Bleepay builds<br/>voucher transaction]
    Sign[Payer signs & sends<br/>in Bleepay Wallet app]
    Settle[(Payee receives value)]

    Gen --> Enter --> Build --> Sign --> Settle
```

## FX — crypto ↔ crypto

In-flight conversion between two crypto-assets on the same blockchain network, so a payee can be paid in one token while the payer pays in another.

1. **Payee sets the expected payment** — e.g. "I want 100 USDC."
2. **Payer chooses a different currency** — e.g. "I'll pay with ETH," giving their wallet address.
3. **System calculates the rate** — looks up market prices, gets a quote from one of several integrated exchange providers, accounts for fees and slippage, and determines the exact amount the payer must send.
4. **Conversion executes on resolve** — the swap runs as part of the payment; the payee receives the requested token.

Constraints: SIMPLE vouchers only; both currencies on the same network; both must be swap-supported ("bridgeable"); a minimum value may apply.

Bleepay integrates **multiple swap/exchange providers** and routes each pair to a suitable one, rather than relying on a single venue.

```mermaid theme={null}
flowchart LR
    Payer([Payer wallet<br/>token B]) --> Swap{{Swap / exchange service}}
    Swap --> Payee[(Payee<br/>token A)]
    Bleepay[[Bleepay system]] -. "quotes, builds tx,<br/>orchestrates swap" .-> Swap
```

## FX & fiat off-ramp (crypto → bank account)

The payee receives traditional money in a bank account while the payer pays in crypto. The conversion to fiat and the bank transfer are handled by a fiat integration partner.

1. **Payee sets a fiat expected payment** — currency (USD, EUR, GBP, …), amount, bank account details, and a payment rail (ACH, wire, SEPA, Faster Payments).
2. **A liquidation address is created** — Bleepay contacts a fiat off-ramp partner (e.g. **Bridge.xyz**), which returns a dedicated crypto deposit address configured to convert incoming crypto to fiat and pay the bank account.
3. **Payer chooses a crypto to pay with**.
4. **System calculates the rate** — including any crypto→crypto step, crypto→fiat fees, bank-transfer fees, and margins.
5. **Two-stage conversion on resolve:**
   * **Stage 1 (if needed):** crypto→crypto swap so the token matches what the liquidation address expects.
   * **Stage 2:** crypto arrives at the liquidation address; the **partner** detects it, converts crypto→fiat, and sends fiat to the payee's bank via the chosen rail.

A liquidation address is a single-purpose crypto address: crypto in → fiat out to a preset bank account, created per payment by the partner. Because a fiat payout is involved, the receiving merchant completes KYC/KYB (see [Onboarding and KYC/KYB](/architecture/onboarding-kyc-kyb)).

```mermaid theme={null}
flowchart LR
    Payer([Payer wallet<br/>crypto]) --> Swap{{Swap<br/>stage 1, if needed}}
    Swap --> Liq[(Liquidation address<br/>operated by fiat partner)]
    Payer -. "or directly if token matches" .-> Liq
    Liq --> Partner[[Fiat partner<br/>e.g. Bridge.xyz]]
    Partner --> Bank[(Payee bank account<br/>fiat via ACH/SEPA/wire)]
    Bleepay[[Bleepay system]] -. "creates liquidation addr,<br/>quotes, orchestrates" .-> Liq
```

## Next steps

* [How money moves](/architecture/how-money-moves) — who holds funds at each step.
* [Custody model](/architecture/custody-model) — non-custodial design.
* [Security](/architecture/security) — zero-trust model.


# Security
Source: https://docs.bleepay.com/home/architecture/security



# Security

> Zero-trust, non-custodial model and session integrity.

Bleepay follows a **zero-trust, non-custodial** model and keeps orchestration strictly separate from asset custody.

## Client-side signing

**Private keys** remain in the user's wallet. Bleepay provides transaction payloads; **all cryptographic signatures are created locally** in the wallet.

Bleepay never has access to private keys and cannot sign or broadcast on behalf of the user.

## Session integrity

* **6-digit codes** are ephemeral and bound to a specific payment intent (session). This limits replay attacks and unauthorized redirection.
* Each voucher is **single-use**: after redemption and retrieval by the payer, the session is finalized and the code is unreserved.
* Communication between the wallet and Bleepay can be **signed** (e.g. with the payer's key) so the server can verify that requests and redemptions belong to the correct payer.

## Real-time validation

* The engine can **verify fiat requirements against on-chain swap parameters** before the user signs, helping prevent price manipulation or slippage exploits.
* Settlement and routing logic are designed to align with the stated amount and currency (e.g. EUR) within agreed tolerances.

## Progressive decentralization (roadmap)

To reduce single points of failure, the roadmap includes moving **orchestration** from a centralized engine toward a **distributed node network**, aiming for a more trustless architecture over time.

Custody and signing remain with the user regardless of how orchestration is distributed.

## Summary

| Principle       | Implementation                                                                |
| --------------- | ----------------------------------------------------------------------------- |
| Non-custodial   | User holds keys; Bleepay never holds funds.                                   |
| Zero-trust      | Server validates signed requests; no trust in a central custodian for assets. |
| Session binding | Codes bound to intent; single-use; time-limited.                              |
| Validation      | Fiat vs on-chain checks before signing where applicable.                      |

## Next steps

* [Custody model](/architecture/custody-model) — non-custodial across products.
* [How money moves](/architecture/how-money-moves) — fund flows by scenario.
* [Terminology](/reference/terminology) — payer, payee, voucher, session.


# System Overview
Source: https://docs.bleepay.com/home/architecture/system-overview

High-level overview of the Bleepay system.

# System Overview

Bleepay offers two complementary products. They can be used independently, but the second is designed to plug into the first.

## Bleepay Widget — a crypto payment gateway

A merchant integrates Bleepay by embedding the Widget or via a white-label integration, and can then accept cryptocurrency payments from their customers. The customer pays in a supported token; the merchant can settle in a stablecoin or have Bleepay convert the payment to fiat and pay out to a bank account. When the customer's token differs from what the merchant wants, Bleepay arranges the FX in the background.

## Bleepay Wallet & Vouchers — a native payment method

A payment method based on a **6-digit code** (a voucher). It can be integrated standalone or surfaced inside the Widget, where it is enabled by default. The payer enters the code, and confirms the payment in the **Bleepay Wallet** — a mobile app where they sign and send the transaction themselves.

## The two products at a glance

|                                 | Bleepay Widget                            | Bleepay Wallet & Vouchers                   |
| ------------------------------- | ----------------------------------------- | ------------------------------------------- |
| **What it is**                  | A crypto payment gateway                  | A code-based payment method + wallet app    |
| **Who integrates it**           | Merchant (embedded or white-label)        | Merchant (standalone, or inside the Widget) |
| **How the customer pays**       | Sends crypto via a simple form            | Enters a 6-digit code, confirms in the app  |
| **Settlement for the merchant** | Crypto (same token or stablecoin) or fiat | Same, including FX                          |
| **Custody**                     | Non-custodial                             | Non-custodial                               |

```mermaid theme={null}
flowchart TD
    Customer([Customer / Payer])
    Widget[Bleepay Widget<br/>embedded or white-label]
    Voucher[Voucher method<br/>6-digit code]
    Wallet[Bleepay Wallet app<br/>user signs & sends]
    MerchantWallet[(Merchant settlement<br/>stablecoin wallet)]
    Bank[(Merchant bank account<br/>fiat)]

    Customer --> Widget
    Widget -. "enabled by default" .-> Voucher
    Voucher --> Wallet
    Wallet --> Widget
    Widget --> MerchantWallet
    Widget -- "FX + off-ramp" --> Bank
```

## What a merchant can receive (settlement options)

| Option                      | What the merchant gets            | Conversion                       |
| --------------------------- | --------------------------------- | -------------------------------- |
| **Crypto, same token**      | The exact token the customer paid | None                             |
| **Crypto, different token** | A stablecoin (e.g. USDC/EURC)     | Crypto→crypto FX                 |
| **Fiat to bank account**    | Traditional money (EUR, etc.)     | Crypto→fiat off-ramp via partner |

## Next steps

* [Bleepay Widget](/architecture/bleepay-widget) — the gateway product in detail.
* [Bleepay Wallet](/architecture/bleepay-wallet) — vouchers and the wallet app.
* [Payment flows](/architecture/payment-flows) — how each flow works end-to-end.


# Benefits for Merchants
Source: https://docs.bleepay.com/home/e-commerce/benefits



# Benefits for Merchants

> Why merchants choose Bleepay for crypto payments.

Summary of why and when Bleepay is a good fit for e-commerce.

## One simple API, integrate in minutes

* Standard financial parameters: amount, currency, wallet address or IBAN, webhook URL, order ID.
* No smart contracts, no chain configuration, no wallet infrastructure on your side.
* Comparable integration effort to adding Stripe or PayPal.

## Minimal frontend changes

* Add Bleepay as a payment option and capture the voucher code when the user selects it.
* Use the built-in white-labeled UI or embed the code input in your own layout.
* No wallet connection flows or extension handling on your site.

## No wallet infrastructure to maintain

* Bleepay and the user's wallet handle RPC, gas, chains, and signing.
* You don't run nodes, manage keys, or deal with chain upgrades.
* Fewer moving parts and less operational risk.

## Compatible with standard checkouts

* Fits into existing payment method selection and order flow.
* Webhook-based confirmation fits standard "payment received → fulfill order" logic.
* No need to redesign checkout for crypto.

## Fiat settlement and reporting

* For Web2 mode: funds arrive in your bank account (e.g. SEPA/ELIXIR).
* For Web3 mode: funds arrive on-chain to your wallet address.
* You can track transactions and payouts in the Bleepay dashboard.
* Simplifies accounting: you receive fiat or stablecoin, not a basket of tokens.

## Non-custodial for users

* Users keep custody of their keys; each payment is explicitly authorized.
* Reduces regulatory and reputational risk associated with custodial flows.
* Aligns with "user signs, user controls" expectations in crypto.

## Next steps

* [E-Commerce overview](/e-commerce/overview)
* [Integration overview](/web2-web3-payments/overview)


# Checkout Flow
Source: https://docs.bleepay.com/home/e-commerce/checkout-flow



# Checkout Flow

> User and merchant steps in the Bleepay checkout experience.

This page describes the checkout flow from the customer's and merchant's perspective.

## Customer journey

1. **Browse and cart** — Customer shops as usual on your site.
2. **Select Bleepay** — At checkout, they choose "Pay with Bleepay" (or your branded label).
3. **Get a code** — They open their Bleepay-compatible wallet (same device or another), generate a 6-digit session code.
4. **Enter code** — They type (or paste) the code into the payment form on your site.
5. **Confirm in wallet** — Their wallet shows the transaction (amount, recipient, fees); they approve.
6. **Done** — They see success on your site; you receive funds and can fulfill the order.

No wallet connection on your domain, no extension, no popups. Just a code and a confirmation step in the wallet.

## Merchant steps

1. **Add Bleepay to checkout** — Integrate the API and pass the voucher code, expected payment parameters, and order ID when the user selects Bleepay.
2. **Show code entry** — Provide an input for the user's 6-digit code.
3. **Handle webhook** — When you receive `payment.settled`, mark the order as paid and fulfill it.
4. **Monitor** — Use the Bleepay dashboard to track transactions and payouts.

## UX best practices

* **Clear instructions**: Tell the user to open their wallet, generate a code, and enter it (and that the code expires after a short time).
* **Error handling**: Handle invalid/expired codes and show a clear message or retry option.
* **Mobile**: The flow works on mobile; ensure the code input is easy to use on small screens.

## Diagram (high level)

```
[Your site]         [Bleepay]           [User wallet]
    |                   |                     |
    | 1. Start session  |                     |
    |------------------>|                     |
    |                   | 2. User generates   |
    |                   |    code             |
    |                   |<--------------------|
    | 3. User enters code|                    |
    |------------------>| 4. Redeem & build tx|
    |                   |-------------------->| 5. Sign
    |                   |<--------------------|
    | 6. Webhook (settled)                    |
    |<------------------|                     |
    | 7. Fulfill order  |                     |
```

## Next steps

* [Integration overview](/web2-web3-payments/overview) — technical integration steps.
* [Webhooks](/e-commerce/webhooks) — handling server-side events.


# overview
Source: https://docs.bleepay.com/home/e-commerce/overview



# E-Commerce Overview

> Accept crypto payments and receive fiat, without crypto accounting.

Bleepay lets merchants **accept crypto payments** and **receive fiat** — without dealing with crypto accounting. The flow is a familiar checkout experience: no wallet connection on your site, no popups, no browser extensions.

## Why Bleepay for E-Commerce?

Crypto payments, without crypto complexity.

Bleepay removes the operational and UX friction usually associated with accepting crypto, while keeping the model **non-custodial** for the user. The customer pays with any supported token; you receive fiat.

## How it works for merchants

**Checkout** — Customer shops as usual and selects Bleepay at checkout. No wallet connection is required on your site.

**Payment** — Customer enters their six-digit code and confirms the transaction in their wallet. You receive fiat directly to your bank account.

**Monitoring** — Track transactions, view revenue, and manage payouts in one place. Bleepay handles the crypto; you see the fiat.

## Benefits

| Benefit                  | Description                                                                     |
| ------------------------ | ------------------------------------------------------------------------------- |
| One simple API           | Integrate in minutes with a small set of parameters.                            |
| Minimal frontend changes | Add Bleepay as a payment method; the code input can be embedded in your layout. |
| No wallet infrastructure | You don't run wallets, RPC, or chain logic.                                     |
| Standard checkouts       | Fits into existing checkout flows like any other payment provider.              |
| Fiat settlement          | Funds land in your IBAN; no crypto treasury or accounting unless you want it.   |

## Next steps

* [Checkout flow](/e-commerce/checkout-flow) — UX and integration details.
* [Benefits](/e-commerce/benefits) — more on why merchants choose Bleepay.
* [Webhooks](/e-commerce/webhooks) — event types, payloads, and verification.


# Webhooks
Source: https://docs.bleepay.com/home/e-commerce/webhooks



# Webhooks

> Payment events, payloads, and how to handle them securely.

Bleepay sends HTTP POST requests to your registered webhook endpoints when payment-related events occur. Use these to update your order state and fulfill orders.

## Endpoint requirements

* **URL**: The webhook URL you register for your business.
* **Method**: POST
* **Content-Type**: `application/json`
* **Signature**: HMAC-SHA256 in the `X-Platform-Signature` header. Verify this to ensure the request came from Bleepay.
* **Response**: Return `200 OK` quickly so Bleepay can consider the delivery successful. Process asynchronously if needed.

## Event types

| Event               | When it fires                                                                       |
| ------------------- | ----------------------------------------------------------------------------------- |
| `deposit.created`   | A deposit session has been created.                                                 |
| `deposit.pending`   | An on-chain transaction has been detected and is awaiting confirmations.            |
| `deposit.confirmed` | The transaction has received the required block confirmations. Use this to fulfill. |
| `deposit.expired`   | The deposit session expired without receiving funds (30-minute window).             |
| `deposit.underpaid` | The customer sent less than the required amount.                                    |
| `deposit.overpaid`  | The customer sent more than the required amount.                                    |

Always check the `type` field and handle idempotency (e.g. by `order_id` or `tx_id`).

## Example payload

```json theme={null}
{
    "id": "evt_abc123",
    "type": "deposit.confirmed",
    "data": {
        "sessionId": "dep_xyz789",
        "orderId": "ORDER-5678",
        "status": "CONFIRMED",
        "amount": "100.00",
        "currency": "EURC",
        "network": "polygon",
        "txHash": "0xTransactionHash",
        "depositAddress": "0xDepositAddress",
        "customerEmail": "customer@example.com",
        "customerReference": "ref_123",
        "metadata": {}
    }
}
```

## Best practices

1. **Verify signatures**: Always validate the `X-Platform-Signature` header using your webhook signing secret to ensure the payload originated from Bleepay.
2. **Idempotency**: Process each event by its `id` so duplicate deliveries don't double-fulfill.
3. **Async processing**: Acknowledge with 200 quickly; do heavy work (DB, external APIs) in a background job.
4. **Retries**: Bleepay retries failed deliveries up to 3 times at 30-second intervals. Your handler must remain idempotent.

## Setting up webhooks

Webhook endpoints are configured per business in the dashboard:

1. Register an endpoint URL.
2. Select which event types to subscribe to (e.g. `deposit.confirmed`, `deposit.expired`).
3. Store the signing secret returned at creation time — it is shown only once.
4. Use the secret to verify the `X-Platform-Signature` header on incoming requests.

## Next steps

* [E-Commerce overview](/e-commerce/overview) — role of webhooks in the merchant flow.
* [Integration overview](/web2-web3-payments/overview) — full parameter reference.


# Core Concepts
Source: https://docs.bleepay.com/home/getting-started/core-concepts



# Core Concepts

> Vouchers, sessions, settlement, and the Bleepay execution flow.

Understanding these concepts will help you integrate and operate Bleepay correctly.

## Voucher (6-digit code)

A **voucher** is a short-lived, human-readable code generated by the payer's wallet and bound to an authorization context. It acts as an **ephemeral proxy** for payment authorization.

* **Format**: Typically 6 digits (numeric) or 6 alphanumeric characters, depending on mode.
* **Transmission**: Can be passed by any channel: typed, spoken, QR, NFC, or messaging.
* **Lifecycle**: Reserved at generation, unreserved when the session is completed or expired.
* **Security**: Does not expose public or private keys; only the payer's wallet can sign the resulting transaction.

## Session

A **voucher session** is the short-lived state on Bleepay's side that links:

* One or more voucher codes
* The payer's identity (bound cryptographically)
* Transaction parameters (amount, currency, destination, etc.)

A session can contain **multiple transactions** — not just a single payment. Each voucher within a session is treated independently, with its own lifecycle, but all share the same session context for grouping and tracking. The session exists from voucher generation until all transaction objects are retrieved and authorized by the payer. After that, the session is finalized and voucher codes are returned to the pool.

## Payment flow (high level)

1. **Payer** logs in and opens a context → receives a context code that links their identity to the payment session.
2. **Payer** shares the context code with the payee (typed, spoken, QR, etc.).
3. **Payee** authenticates using their API key (`x-api-key` header), reserves a voucher using the context code (receives a 6-digit code), and redeems it by specifying what they expect to receive (`expectedPayment`) — currency, amount, and destination address.
4. **Bleepay** validates the voucher, syncs transaction metadata, and builds the transaction (swap/bridge/transfer) for the appropriate chain and token.
5. **Payer** reviews, signs in their wallet, and submits the receipt via `resolve-voucher`; the wallet broadcasts to the network.
6. **Settlement** — funds arrive at the payee's address (or via liquidation partner for fiat).

## Non-custodial model

* **Client-side signing**: Private keys stay in the user's wallet. Bleepay provides transaction payloads; all signatures happen locally.
* **No custody**: Bleepay never holds user funds. Settlement is on-chain or via regulated off-ramp partners.
* **Session integrity**: Codes are ephemeral and bound to a specific payment intent, reducing replay and misuse.

## Chain-agnostic merchant experience

Merchants integrate using **financial metadata only**: amount, currency, wallet address. They do not:

* Choose chains or tokens (the system determines the network from the currency)
* Manage gas or RPC
* Write or deploy smart contracts

Bleepay's backend handles routing, gas, cross-chain, and DEX logic so the merchant stays chain-agnostic.

## Next steps

* [Terminology](/reference/terminology) — full glossary of protocol terms.
* [Protocol flow](/reference/protocol-flow) — voucher generation, redemption, and settlement steps.
* [Voucher modes](/reference/voucher-modes) — numeric vs alphanumeric codes.


# Introduction
Source: https://docs.bleepay.com/home/getting-started/introduction



# Introduction

> What Bleepay is and how it solves payment friction in crypto.

Bleepay is a **payment system for crypto** that lets users authorize transactions with a **short-lived six-digit code**. No browser extensions, no multi-step modals, no complicated infrastructure to maintain.

Use the code to pay at online stores, connect to dApps, make peer-to-peer payments, or add an extra verification step before signing.

One simple UX across Web2 and Web3.

## The problem

**Crypto already works. Paying with it doesn't.**

The infrastructure is there. The liquidity is there. But when someone actually wants to buy something, they hit a wall:

* Wallet connections break
* Browser extensions fail on mobile
* Popups get blocked

Spending crypto should be as simple as spending anything else.

## The solution

Bleepay replaces that friction with **a six-digit code**.

1. You **generate a code** in your wallet.
2. You **enter the code** at checkout (or in a dApp).
3. Done.

* **No extensions** — Nothing to install. No connections to maintain. No permissions to grant.
* **Non-custodial** — Each transaction is authorized individually. Your crypto stays in your wallet until you approve the payment.
* **Fiat for merchants** — For merchants, Bleepay works like any other payment method. Add it to checkout, receive fiat directly to your bank account.

**Crypto in. Fiat out. Simple for both sides.**

## What Bleepay is not

| Not           | But                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| Only a wallet | Bleepay is a **payment method**. The Bleepay wallet showcases the experience, but any wallet can integrate it. |
| A crypto card | No deposits, no standing permissions.                                                                          |
| Custodial     | Private keys stay in the user's wallet. Bleepay never holds funds.                                             |

## Who built this

The team behind **LayerZero** and **Stargate**:

* **LayerZero** — messaging, connecting every chain.
* **Stargate** — liquidity, moving assets across networks.
* **Bleepay** — payments, turning that stack into something anyone can use.

Three layers. One solution.

## Next steps

* [Quickstart](/getting-started/quickstart) — run your first integration.
* [Core concepts](/getting-started/core-concepts) — vouchers, sessions, and settlement.
* [Integration overview](/web2-web3-payments/overview) — for merchants and developers.


# Quickstart
Source: https://docs.bleepay.com/home/getting-started/quickstart



# Quickstart

> Get your first Bleepay payment flow running in minutes.

This guide walks through the payee (merchant/dApp) side of a Bleepay voucher payment. The payer uses a Bleepay-compatible wallet — you don't implement that side.

## Prerequisites

* A Bleepay account with API credentials
* A Bleepay-compatible wallet (e.g. Bleepay Wallet) for the payer
* cURL or any HTTP client

## Flow overview

```text theme={null}
Payer (wallet)          Bleepay API            Payee (you)
     |                       |                     |
     | open context           |                     |
     |---------------------->|                     |
     |<-- context code -------|                     |
     |                       |                     |
     |   (share context code: QR, link, NFC, etc.) |
     |-------------------------------------------->|
     |                       |  reserve-voucher     |
     |                       |  (x-api-key)         |
     |                       |<---------------------|
     |                       |-- voucher "482916" ->|
     |                       |                     |
     |                       |  redeem-voucher      |
     |                       |  (expectedPayment)   |
     |                       |<---------------------|
     |                       |                     |
     | resolve-voucher       |                     |
     | (sign & submit)       |                     |
     |---------------------->|                     |
```

Your responsibility is the **payee side** (right column). The payer side happens in their wallet.

## 1. Payer opens a context in their wallet

The payer uses a Bleepay-compatible wallet to authenticate and open a payment context. The wallet returns a **context code** — a short alphanumeric string the payer shares with you.

This step happens entirely inside the payer's wallet. You just need to provide a way for the payer to give you the context code (QR scan, text input, deeplink, etc.).

## 2. Authenticate as the payee

Pass your API key in the `x-api-key` header on every request. No separate sign-in step is needed.

```
x-api-key: <your_api_key>
```

## 3. Reserve a voucher

Reserve a voucher within the payer's context. This generates a 6-digit voucher code.

```
POST /api/v1/vouchers/reserve-voucher
x-api-key: <your_api_key>

{
    "code": "A1B2C3"
}
```

**Response:**

```json theme={null}
{
    "id": "vch_482916",
    "code": "482916",
    "status": "RESERVED",
    "expiresAt": "2026-06-09T12:02:00Z"
}
```

## 4. Redeem the voucher

Specify what you expect to receive — currency, amount, network, and destination address. The `expectedPayment` parameter tells Bleepay to create a **SIMPLE** voucher with automatic network selection.

```
POST /api/v1/vouchers/vch_482916/redeem-voucher
x-api-key: <your_api_key>

{
    "expectedPayment": {
        "network": "polygon",
        "currency": "EURC",
        "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
        "amount": "100",
        "wallet": {
            "address": "0xYourWalletAddress"
        }
    }
}
```

**Response:**

```json theme={null}
{
    "id": "vch_482916",
    "status": "REDEEMED",
    "type": "SIMPLE",
    "expectedPayment": {
        "network": "polygon",
        "currency": "EURC",
        "amount": "100",
        "wallet": { "address": "0xYourWalletAddress" }
    }
}
```

## 5. Payer signs and resolves

The payer reviews the transaction in their wallet, signs it, and the wallet submits the receipt. This happens on the payer's side — no action needed from you.

Poll the voucher to track its status until it reaches `RESOLVED`:

```
GET /api/v1/vouchers/vch_482916
x-api-key: <your_api_key>
```

The voucher moves through states: `RESERVED` → `REDEEMED` → `RESOLVED`. Poll every 2–5 seconds until the final state is reached. For production, register a webhook endpoint instead of polling.

## Complete payee-side example

```javascript theme={null}
const apiKey = 'your_api_key';

// 1. Reserve a voucher using the context code the payer shared with you
const reserveRes = await fetch('/api/v1/vouchers/reserve-voucher', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  },
  body: JSON.stringify({ code: contextCode })
});
const voucher = await reserveRes.json();

// 2. Redeem with expected payment
await fetch(`/api/v1/vouchers/${voucher.id}/redeem-voucher`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey
  },
  body: JSON.stringify({
    expectedPayment: {
      network: 'polygon',
      currency: 'EURC',
      currencyAddress: '0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b',
      amount: '100',
      wallet: { address: '0xYourWalletAddress' }
    }
  })
});

// 3. Poll until resolved
let status;
while (status !== 'RESOLVED') {
  const res = await fetch(`/api/v1/vouchers/${voucher.id}`, {
    headers: { 'x-api-key': apiKey }
  });
  const data = await res.json();
  status = data.status;
  if (status === 'RESOLVED') break;
  await new Promise(r => setTimeout(r, 3000));
}
```

## Next steps

* [Integration overview](/web2-web3-payments/overview) — full parameter reference and Web2 vs Web3 modes.
* [Simple Payments](/web2-web3-payments/simple-payments) — SIMPLE vouchers, FX, and negotiation.
* [Webhooks](/e-commerce/webhooks) — event-driven settlement tracking.


# Protocol Flow
Source: https://docs.bleepay.com/home/reference/protocol-flow



# Protocol Flow

> Detailed voucher generation, redemption, and settlement sequence.

This page describes the **algorithmic flow** of the Bleepay voucher-based protocol: generation, transmission, redemption, invoice retrieval, and settlement.

## Phase 1: Voucher generation

* **S101** — Payer starts a digital payment in the wallet. Wallet builds `VOUCHER_INIT` (e.g. payer identifier, optional context, timestamp, nonce).
* **S102** — Wallet signs `VOUCHER_INIT` with the payer's private key (e.g. ECDSA/Ed25519).
* **S103** — Request sent over secure transport (e.g. HTTPS/TLS 1.3 or gRPC).
* **S104** — Payment server verifies signature, timestamp, nonce.
* **S105** — Server generates a unique voucher code (e.g. 6-char alphanumeric via CSPRNG).
* **S106** — Server creates a session record (voucher, payer ref, TTL, context) in storage.
* **S107** — Server returns `VOUCHER_ISSUE` (voucher code, TTL, session metadata).
* **S108** — Wallet displays the voucher to the user.

## Phase 2: Voucher transmission

* **S109** — Payer transmits the voucher by any channel: manual entry (numeric or alphanumeric), QR, NFC, BLE, messaging, etc. The system is transport-agnostic.

## Phase 3: Redemption and invoice generation

* **S201** — Payee interface captures the voucher and builds `VOUCHER_REDEEM` (voucher code + payee transaction parameters: amount, asset, destination, network).
* **S202** — Payee sends `VOUCHER_REDEEM` over secure transport.
* **S203** — Server looks up the active session by voucher; verifies TTL has not expired.
* **S204** — Server builds a blockchain-compatible **unsigned** transaction object `TX_UNSIGNED` (e.g. destination, asset, amount, nonce placeholder, fee/gas template, optional contract calldata). No signature or private-key operation is applied on the server.
* **S205** — Server marks the session as pending-signature and sends `TX_PENDING_NOTIFY` to the payer's wallet (e.g. WebSocket/push) so the wallet knows `TX_UNSIGNED` is ready for retrieval.

## Phase 4: Invoice retrieval and payer authorization

* **S206** — Wallet receives the notification and sends `TX_FETCH` (voucher/session ref), signed by the payer's private key.
* **S207** — Server verifies the signature against the payer bound to the session and returns `TX_UNSIGNED`.
* **S208** — Server finalizes the session: marks it completed, deletes session metadata, unreserves the voucher code and returns it to the pool.
* **S209** — Wallet displays transaction details (amount, asset, destination, fees).
* **S210** — If allowed by the protocol, the wallet may fill or adjust dynamic fields (e.g. nonce, max fee) before signing.
* **S211** — After payer confirmation, the wallet validates `TX_UNSIGNED` and signs it, producing `TX_SIGNED`.

## Phase 5: Signing and settlement

* **S212** — Wallet broadcasts `TX_SIGNED` via the network's native interface (e.g. JSON-RPC/Web3, REST, node API).
* **S213** — The blockchain processes and settles the transaction according to its consensus rules.
* **S214** — Wallets and systems update balances/status from on-chain confirmations.

## State machine

```
RESERVED → REDEEMED (via redeemVoucher)
RESERVED → DISCARDED (via discardVoucher)
REDEEMED → RESOLVED (via resolveVoucher)
REDEEMED → DISCARDED (via discardVoucher)
Any → EXPIRED (automatic, when expiresAt < now)
```

## Message types (summary)

| Message             | Direction        | Purpose                                        |
| ------------------- | ---------------- | ---------------------------------------------- |
| VOUCHER\_INIT       | Wallet → Server  | Voucher generation request.                    |
| VOUCHER\_ISSUE      | Server → Wallet  | Voucher code and session data.                 |
| VOUCHER\_REDEEM     | Payee → Server   | Redemption request with payee parameters.      |
| TX\_PENDING\_NOTIFY | Server → Wallet  | Pending invoice ready for retrieval.           |
| TX\_FETCH           | Wallet → Server  | Signed request to retrieve transaction object. |
| TX\_UNSIGNED        | Server → Wallet  | Unsigned transaction for signing.              |
| TX\_SIGNED          | Wallet → Network | Signed transaction for broadcast.              |

Encoding and transport (JSON, CBOR, gRPC, etc.) can vary; the logical sequence and roles are as above.

## Next steps

* [Terminology](/reference/terminology) — definitions of voucher, session, invoice, etc.
* [Voucher modes](/reference/voucher-modes) — numeric vs alphanumeric.
* [Simple Payments](/web2-web3-payments/simple-payments) — SIMPLE voucher examples.


# Terminology
Source: https://docs.bleepay.com/home/reference/terminology



# Terminology

> Glossary of terms used in the Bleepay protocol and documentation.

Definitions aligned with the Bleepay protocol and patent documentation.

## Core terms

| Term                           | Definition                                                                                                                                                                                                                                                                                           |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payment network                | A network built around centralized and/or distributed nodes that maintains a ledger and allows owning and transferring digitized assets.                                                                                                                                                             |
| Cryptocurrency / digital asset | A digitally native asset used as medium of exchange, store of value, or unit of account on a payment network (e.g. Bitcoin, Ether, stablecoins).                                                                                                                                                     |
| Payment                        | A transaction that creates a new entry on the ledger indicating transfer of assets between payer and payee (analogous to a bank transfer within that network).                                                                                                                                       |
| Payer                          | The user or entity that initiates a transaction and authorizes the transfer. Operates a wallet with the necessary credentials (e.g. private key). Only the payer can generate a voucher and authorize its redemption.                                                                                |
| Payee                          | The user or entity that receives the payment. The payee does not need to operate a wallet; they can use a terminal, merchant backend, or other interface to submit the voucher for redemption.                                                                                                       |
| Wallet                         | Software or hardware that holds cryptographic credentials, signs messages/transactions, and interacts with the payment network. In Bleepay, the wallet may also generate vouchers and sign voucher-related messages.                                                                                 |
| Payer's wallet                 | The wallet used by the payer to generate vouchers, receive transaction invoices, and authorize blockchain transactions. It is the only component that can produce signatures binding a voucher to an authorization context.                                                                          |
| Payee interface                | Any interface (POS, merchant system, web, mobile app) through which the payee receives the voucher and initiates redemption. It does not need private keys or signing capability.                                                                                                                    |
| Payment server                 | A network service that coordinates voucher lifecycle: validates generation/retrieval requests, reserves/unreserves voucher codes, manages short-lived session records, and provides transaction objects to the payer for signing. It does not hold private keys or initiate blockchain transactions. |

## Voucher and session

| Term               | Definition                                                                                                                                                                                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Voucher            | A short-lived, human-readable code or token generated by the payer's wallet and bound to an authorization context. It serves as an ephemeral proxy for payment authorization and can be transmitted without exposing cryptographic material.                                                                  |
| Voucher code       | The literal sequence of digits or alphanumeric characters that uniquely identifies a voucher during its validity period. Entered, spoken, or transmitted to the payee and then submitted to the payment server for redemption. Reserved at generation, unreserved when the session completes.                 |
| Voucher session    | Short-lived state on the payment server that associates a voucher code with the payer's identity and transaction parameters. Exists from voucher generation until the transaction object is retrieved by the payer; then the session is finalized and the code is released.                                   |
| Session record     | The stored representation of a voucher session (e.g. voucher code, session id, TTL, payer binding, context). Does not contain private keys or signed transactions.                                                                                                                                            |
| Transaction object | A structured representation of a transaction produced after voucher redemption (e.g. recipient, asset, amount, network, calldata). Sent to the payer's wallet for signing and then broadcast to the blockchain.                                                                                               |
| Invoice            | The intermediate representation of a transaction request created when the payee redeems a voucher. Produced by the payment server from payee details and the voucher session. The payer fetches, reviews, and authorizes it in the wallet; upon authorization it becomes a signed transaction for settlement. |

## Technical

| Term              | Definition                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Smart contract    | Code executed to produce a result (e.g. transfer of funds). Can be on the payment network's ledger or in an external module.   |
| Device / computer | Equipment that processes digital data (e.g. phone, laptop, cloud VM). A user device is under the control of a particular user. |

## Next steps

* [Protocol flow](/reference/protocol-flow) — how these terms apply in the sequence of steps.
* [Voucher modes](/reference/voucher-modes) — numeric vs alphanumeric codes.


# Voucher Modes
Source: https://docs.bleepay.com/home/reference/voucher-modes



# Voucher Modes

> Numeric vs alphanumeric voucher formats and when each is used.

The Bleepay system supports two voucher modes to balance **compatibility** with existing terminals and **scalability** in digital environments.

## Numeric mode

* **Format**: Short sequence of **digits** (e.g. 6 digits).
* **Use case**: Compatible with legacy POS devices and keypads that accept only numeric input (e.g. ISO/IEC 7812-1, ANSI X4.13).
* **Examples**: Countertop payment terminals, integrated POS, kiosks, ATMs, older keypad-based merchant terminals.
* **Transmission**: User can read the code aloud or enter it manually; works in low-tech retail environments.

## Alphanumeric mode

* **Format**: Short sequence of **letters and digits** (e.g. 6 alphanumeric characters).
* **Use case**: Modern interfaces that support full keyboard or alphanumeric entry.
* **Benefits**: Larger space of unique codes in parallel → better scalability and lower code-collision risk.
* **Examples**: Touchscreen POS, smart POS, merchant web/mobile dashboards, self-checkout kiosks with software keypads.

## Mode selection

Mode can be chosen **dynamically** based on:

* Terminal capabilities
* Merchant configuration
* User or context preference

When the payee uses a numeric-only terminal, the payer's wallet can generate a **numeric** voucher. When the interface supports alphanumeric input, the wallet can generate an **alphanumeric** voucher for higher throughput and security.

Supporting both keeps **interoperability** with legacy hardware while allowing **high-volume** operation in modern setups.

## Next steps

* [Terminology](/reference/terminology) — voucher, voucher code, session.
* [Protocol flow](/reference/protocol-flow) — where the voucher is generated and redeemed.


# Integration Overview
Source: https://docs.bleepay.com/home/web2-web3-payments/overview



# Integration Overview

> How Bleepay fits into your stack and what you need to integrate.

Bleepay is built as a **drop-in** payment layer. The full Web3 stack — gas management, cross-chain routing, DEX interactions — is abstracted into a standard API workflow. For developers, integrating Bleepay is comparable to integrating Stripe or PayPal.

Bleepay allows a merchant to receive **crypto (Web3)** or **fiat (Web2)**. You do not need to specify which operation mode to use — the system automatically determines it based on the receiving currency. If the expected payment currency is a stablecoin like EURC or USDC, Bleepay handles the crypto settlement. If the expected currency is a fiat currency like EUR or USD, Bleepay routes through a fiat off-ramp partner to deliver funds to the merchant's bank account.

## What you need to provide

Integration is driven by **standard financial metadata**. Your engineering team does **not** need to:

* Write or deploy smart contracts
* Run or manage blockchain nodes
* Handle gas, RPC, or wallet connections on the frontend

### Parameters

| Parameter         | Web3 (Crypto) | Web2 (Fiat) | Purpose                                                            |
| ----------------- | :-----------: | :---------: | ------------------------------------------------------------------ |
| `amount`          |    Required   |   Required  | Transaction amount in the settlement currency.                     |
| `currency`        |    Required   |   Required  | Settlement currency (e.g. EURC, USDC for Web3; EUR, USD for Web2). |
| `currencyAddress` |    Required   |      —      | Contract address of the settlement token on-chain.                 |
| `network`         |    Required   |      —      | Blockchain network for settlement (e.g. polygon, ethereum).        |
| `wallet.address`  |    Required   |      —      | Payee's wallet address where crypto funds will be sent.            |

\| `order_id`                 | Required      | Required    | Your internal order or payment reference (idempotency, reconciliation). |

### Webhooks

Businesses can register webhook endpoints to receive payment lifecycle events. Each webhook endpoint is configured with:

* A **URL** to deliver events to
* A list of **event types** to subscribe to (e.g. `deposit.confirmed`, `deposit.expired`)
* A **signing secret** for HMAC-SHA256 payload verification

Webhooks are dispatched as signed HTTP POST requests. The signature is included in the `X-Platform-Signature` header. Failed deliveries are retried up to 3 times with 30-second intervals.

## How it works on your side

1. **Payer opens a context** — The payer authenticates and opens a payment context. This generates a context code that links the payer's identity to the payment session.
2. **Payee reserves a voucher** — The payee (merchant) authenticates using their API key (`x-api-key` header) and reserves a voucher using the context code, receiving a 6-digit code. This creates a secure, short-lived link between the payer's assets and the payment intent.
3. **Payee redeems the voucher** — The payee submits `expectedPayment` — what currency, how much, and where to send it. This sets the terms of the payment.
4. **Transaction is built** — Bleepay constructs the transaction calldata based on the expected payment. For SIMPLE vouchers, the network is determined automatically from the currency. For fiat payouts, Bleepay routes through a liquidation partner.
5. **Payer resolves** — The payer reviews the transaction in their wallet, signs it, and submits the receipt via `resolve-voucher`. The wallet broadcasts the transaction to the network.
6. **Wait for settlement** — On-chain payments settle once confirmed by the network. Fiat payouts settle when the liquidation partner completes the bank transfer. Poll the voucher status or listen for webhooks to track progress.

## Environments

| Environment    | Use case                                        |
| -------------- | ----------------------------------------------- |
| **Sandbox**    | Testing; no real funds or bank transfers.       |
| **Production** | Live payments; real crypto and fiat settlement. |

## Next steps

* [Simple Payments](/web2-web3-payments/simple-payments) — create a single EURC payment with SIMPLE voucher.
* [Sessions](/web2-web3-payments/sessions) — group multiple vouchers in a session.
* [Smart Contracts](/web2-web3-payments/smart-contracts) — interact with contracts via CUSTOM vouchers.
* [Webhooks](/e-commerce/webhooks) — event types, payloads, and verification.


# Sessions
Source: https://docs.bleepay.com/home/web2-web3-payments/sessions



# Sessions

> Group multiple vouchers in a session for multi-payment flows.

A session groups multiple vouchers together under a single context. Each voucher within the session is treated **independently** — with its own code, lifecycle, and settlement — but they share the same session for tracking and coordination.

Each voucher in a session has the same capabilities as a standalone payment: SIMPLE vouchers support FX, network auto-detection, and straightforward token transfers.

## Why use sessions?

* **Multi-payment checkout**: A customer pays for multiple items as separate transactions but tracked together.
* **Split payments**: Pay different recipients from a single user session.
* **Multi-currency**: Accept EURC for one item and USDC for another, both in the same session.

## Flow overview

1. **Payer** opens their wallet, authenticates, and opens a context — shares the context code with you.
2. **You authenticate** using your API key (`x-api-key` header).
3. **You open a session** using the context code.
4. **Payer** joins the session in their wallet.
5. **You reserve and redeem** each voucher independently within the session.
6. **Payer** resolves each voucher independently in their wallet.
7. **You close** the session when done.

## Example: Two payments (EURC + USDC) in one session

The payer has already opened their wallet and shared a context code with you.

### 1. Authenticate and open a session

Pass your API key in the `x-api-key` header. No separate sign-in step is needed.

```
POST /api/v1/vouchers/sessions/session-open
x-api-key: <your_api_key>

{
    "code": "A1B2C3"
}
```

Response: `{ "id": "ses_xyz", "code": "D4E5F6", "status": "OPEN" }`

The payer joins the session in their wallet.

### 2. Reserve and redeem first voucher (EURC)

```
POST /api/v1/vouchers/sessions/ses_xyz/reserve-voucher
x-api-key: <your_api_key>

{}
```

Response: `{ "id": "vch_482916", "code": "482916", "status": "RESERVED" }`

```
POST /api/v1/vouchers/vch_482916/redeem-voucher
x-api-key: <your_api_key>

{
    "expectedPayment": {
        "network": "polygon",
        "currency": "EURC",
        "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
        "amount": "100",
        "wallet": {
            "address": "0xYourWalletAddress"
        }
    }
}
```

### 3. Reserve and redeem second voucher (USDC)

```
POST /api/v1/vouchers/sessions/ses_xyz/reserve-voucher
x-api-key: <your_api_key>

{}
```

Response: `{ "id": "vch_739104", "code": "739104", "status": "RESERVED" }`

```
POST /api/v1/vouchers/vch_739104/redeem-voucher
x-api-key: <your_api_key>

{
    "expectedPayment": {
        "network": "polygon",
        "currency": "USDC",
        "currencyAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
        "amount": "50",
        "wallet": {
            "address": "0xYourWalletAddress"
        }
    }
}
```

### 4. Payer resolves, you close

The payer signs and submits receipts for each voucher in their wallet. Once all are resolved, close the session:

```
POST /api/v1/vouchers/sessions/ses_xyz/session-close
x-api-key: <your_api_key>

{}
```

### Diagram

```text theme={null}
Payer (wallet)          Bleepay              Payee (you)
     |                     |                     |
     | open context        |                     |
     |-------------------->|                     |
     |<-- code "A1B2C3" ---|                     |
     |                     |                     |
     |   (share context code)                    |
     |------------------------------------------>|
     |                     |  session-open (x-api-key)
     |                     |<---------------------|
     |                     |-- ses_xyz --------->|
     |                     |                     |
     | join session        |                     |
     |-------------------->|                     |
     |                     |                     |
     |                     |  reserve vch_482916    |
     |                     |<---------------------|
     |                     |  redeem vch_482916     |
     |                     |<---------------------|
     |                     |                     |
     |                     |  reserve vch_739104    |
     |                     |<---------------------|
     |                     |  redeem vch_739104     |
     |                     |<---------------------|
     |                     |                     |
     | resolve vch_482916     |                     |
     |-------------------->|                     |
     | resolve vch_739104     |                     |
     |-------------------->|                     |
     |                     |                     |
     |                     |  session-close      |
     |                     |<---------------------|
     |                     |                     |
     |          funds → your address (EURC + USDC)|
```

## Key points

* Each voucher in a session is **independent** — status, lifecycle, and settlement are tracked per-voucher.
* Each voucher has the **same capabilities** as a standalone SIMPLE payment (FX, auto-network, etc.).
* The session groups them for coordination but does not couple their fates.
* Close the session once all vouchers are resolved.

## Next steps

* [Simple Payments](/web2-web3-payments/simple-payments) — single voucher payments.
* [Smart Contracts](/web2-web3-payments/smart-contracts) — CUSTOM voucher for contract interactions.


# Simple Payments
Source: https://docs.bleepay.com/home/web2-web3-payments/simple-payments



# Simple Payments

> Using a SIMPLE voucher to create a single token payment with built-in FX.

A SIMPLE voucher is the easiest way to accept a payment. You specify what currency you want, how much, and where to send it — Bleepay handles everything else including network selection, gas, and FX (foreign exchange).

Using a SIMPLE voucher enables the payer to take advantage of **FX out of the box**. You request payment in one currency (e.g. EURC), and the payer can pay with a different currency they hold (e.g. USDC on the same network). The system automatically calculates the exchange rate and handles the conversion.

## Flow

1. **Payer** opens their Bleepay-compatible wallet, authenticates, and opens a context — the wallet displays a context code.
2. **Payer** shares the context code with you (QR, link, NFC, etc.).
3. **You authenticate** using your API key (`x-api-key` header).
4. **You reserve** a voucher using the context code → receive a 6-digit voucher code.
5. **You redeem** the voucher with `expectedPayment` specifying what you want to receive.
6. (Optional) **Payer negotiates** — if they don't hold the requested currency, their wallet proposes an alternative. Bleepay calculates the FX rate automatically.
7. **Payer** reviews the transaction in their wallet, signs, and submits the receipt — the wallet resolves the voucher.
8. **Settlement** — funds arrive at your address.

## Example: Single EURC payment

The payer has already opened their wallet and shared a context code with you.

### 1. Authenticate

Pass your API key in the `x-api-key` header on every request. No separate sign-in step is needed.

### 2. Reserve a voucher

```
POST /api/v1/vouchers/reserve-voucher
x-api-key: <your_api_key>

{
    "code": "A1B2C3"
}
```

Response: `{ "id": "vch_482916", "code": "482916", "status": "RESERVED" }`

### 3. Redeem with expectedPayment

```
POST /api/v1/vouchers/vch_482916/redeem-voucher
x-api-key: <your_api_key>

{
    "expectedPayment": {
        "network": "polygon",
        "currency": "EURC",
        "currencyAddress": "0x73b3db5a96a4b9d9bcfc22b8f1b3d85a5e5b5e5b",
        "amount": "100",
        "wallet": {
            "address": "0xYourWalletAddress"
        }
    }
}
```

The system detects no `networks`, `payments`, or `extras` were provided, so it automatically creates a **SIMPLE** voucher. The network is derived from the currency.

### 4. Payer resolves

The payer reviews the transaction in their wallet, signs it, and the wallet submits the receipt. Poll until the status reaches `RESOLVED`:

```
GET /api/v1/vouchers/vch_482916
x-api-key: <your_api_key>
```

### (Optional) FX negotiation

If the payer doesn't hold EURC, their wallet can negotiate by proposing a different currency they do hold (e.g. USDC). Bleepay calculates the exchange rate automatically and fills in the required amount, accounting for fees and slippage. This happens on the payer's side — no action needed from you beyond handling the updated `suppliedPayment` in the voucher response.

### Diagram

```text theme={null}
Payer (wallet)          Bleepay              Payee (you)
     |                     |                     |
     | open context        |                     |
     |-------------------->|                     |
     |<-- context code -----|                     |
     |                     |                     |
     |   (share context code via QR/link/etc.)   |
     |------------------------------------------>|
     |                     |  reserve-voucher     |
     |                     |  (x-api-key)         |
     |                     |<---------------------|
     |                     |-- code "482916" ---->|
     |                     |                     |
     |                     |  redeem-voucher      |
     |                     |  (expectedPayment)   |
     |                     |<---------------------|
     |                     |                     |
     | negotiate (opt.)    |                     |
     |-------------------->|                     |
     |                     |                     |
     | resolve-voucher     |                     |
     |-------------------->|                     |
     |                     |                     |
     |              funds → your address         |
```

## When to use SIMPLE

* Basic token transfers
* Payments where you want a specific currency and amount
* Scenarios where FX flexibility is desired
* Any straightforward "send me X of token Y" use case

## Next steps

* [Sessions](/web2-web3-payments/sessions) — group multiple vouchers in a session.
* [Smart Contracts](/web2-web3-payments/smart-contracts) — complex interactions with CUSTOM vouchers.
* [Integration overview](/web2-web3-payments/overview) — full parameter reference.


# Smart Contracts
Source: https://docs.bleepay.com/home/web2-web3-payments/smart-contracts



# Smart Contracts

> Using a CUSTOM voucher to interact with smart contracts — for staking, DeFi, and complex on-chain actions.

CUSTOM vouchers give you **full control** over transaction details. Instead of a simple "send me X of token Y," you specify explicit transaction instructions — networks, payments, and extras. This enables smart contract interactions like staking, swapping through a specific DEX, NFT minting, and multi-step DeFi operations.

CUSTOM vouchers do **not** support FX. They are for scenarios where you define exactly what on-chain actions must occur.

## Flow

1. **Payer** opens their wallet, authenticates, and opens a context — shares the context code with you.
2. **You authenticate** using your API key (`x-api-key` header).
3. **You reserve** a voucher using the context code.
4. **You redeem** with explicit `networks`, `payments`, and `extras` — the system detects these and creates a **CUSTOM** voucher.
5. **Payer** reviews the transaction in their wallet, signs, and submits the receipt.

## Example: Staking contract call

A dApp wants the payer to stake tokens into a staking contract.

The payer has already opened their wallet and shared a context code with you.

### 1. Authenticate and reserve

Pass your API key in the `x-api-key` header. No separate sign-in step is needed.

```
POST /api/v1/vouchers/reserve-voucher
x-api-key: <your_api_key>

{
    "code": "A1B2C3"
}
```

Response: `{ "id": "vch_591234", "code": "591234", "status": "RESERVED" }`

### 2. Encode the contract call

Given a staking contract with this interface:

```solidity theme={null}
interface IStaking {
    function stake(uint256 amount) external;
}
```

Use the ABI to encode the function calldata:

```javascript theme={null}
import { encodeFunctionData } from 'viem';

const stakingAbi = [
  {
    name: 'stake',
    type: 'function',
    inputs: [{ name: 'amount', type: 'uint256' }],
    outputs: [],
  },
];

const stakeData = encodeFunctionData({
  abi: stakingAbi,
  functionName: 'stake',
  args: [1000000000000000000n], // 1 token (18 decimals)
});
// → 0xa694fc3a0000000000000000000000000000000000000000000000000de0b6b3a7640000
```

### 3. Redeem with CUSTOM configuration

```
POST /api/v1/vouchers/vch_591234/redeem-voucher
x-api-key: <your_api_key>

{
    "networks": [
        {
            "network": "ethereum",
            "type": "evm",
            "chainId": "1"
        }
    ],
    "payments": [
        {
            "type": "send_transaction",
            "input": {
                "from": "{payer}",
                "to": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
                "value": "0",
                "data": "0xa694fc3a0000000000000000000000000000000000000000000000000de0b6b3a7640000"
            }
        }
    ],
    "extras": []
}
```

The system detects `networks`, `payments`, and `extras` were provided (and no `expectedPayment`), so it automatically creates a **CUSTOM** voucher. The `{payer}` placeholder is substituted by the payer's wallet at resolution time.

### 4. Payer resolves

The payer reviews the staking transaction in their wallet, signs it, and the wallet submits the receipt. Poll until `RESOLVED`:

```
GET /api/v1/vouchers/vch_591234
x-api-key: <your_api_key>
```

### Diagram

```text theme={null}
Payer (wallet)          Bleepay              Payee (you / dApp)
     |                     |                     |
     | open context        |                     |
     |-------------------->|                     |
     |<-- code "A1B2C3" ---|                     |
     |                     |                     |
     |   (share context code)                    |
     |------------------------------------------>|
     |                     |  reserve-voucher    |
     |                     |  (x-api-key)        |
     |                     |<---------------------|
     |                     |-- code "591234" --->|
     |                     |                     |
     |                     |  redeem-voucher     |
     |                     |  (networks, payments,|
     |                     |   extras)           |
     |                     |<---------------------|
     |                     |                     |
     |                     |  type = CUSTOM      |
     |                     |                     |
     | resolve-voucher     |                     |
     | (signs staking tx)  |                     |
     |-------------------->|                     |
     |                     |                     |
     | staking contract called on-chain          |
```

## When to use CUSTOM

* Smart contract interactions (staking, lending, governance)
* Multi-step transactions (approve + transfer, batch calls)
* Custom on-chain logic that can't be expressed as a simple transfer
* dApp flows requiring explicit network and calldata control

## Limitations

* **No FX**: CUSTOM vouchers do not support automatic currency conversion.
* **No automatic network selection**: You must specify the blockchain network explicitly.
* **No expectedPayment**: CUSTOM vouchers use `payments` and `extras` instead of `expectedPayment`.

## Next steps

* [Simple Payments](/web2-web3-payments/simple-payments) — SIMPLE vouchers for straightforward transfers.
* [Sessions](/web2-web3-payments/sessions) — group vouchers in a session.
* [Web3 processing](/integrations/processing) — swaps, DeFi, and complex on-chain actions.


# Bleepay Documentation
Source: https://docs.bleepay.com/index



<Frame>
  <img alt="184" title="184" />

  <img alt="184" title="184" />
</Frame>

> Non-custodial payment orchestration connecting Web3 liquidity to traditional fiat rails. Pay with any token, receive fiat.

Pay with a **6-digit code**. No extensions. No wallet popups. Crypto in, fiat out.

## Why Bleepay?

Bleepay is a **non-custodial orchestration layer** that connects Web3 liquidity to traditional fiat rails. Users pay with **any token on any chain** via human-friendly **6-digit codes**; settlement is delivered as **fiat** to the merchant's bank account through regulated partners.

* **No browser extensions** — no popups, no connection friction
* **No custody** — private keys stay in the user's wallet; each transaction is authorized individually
* **Chain-agnostic** — one integration for merchants; Bleepay handles gas, routing, and DEX logic
* **Fiat out** — merchants receive funds to IBAN via SEPA/ELIXIR; no crypto accounting

## Contents

### Getting Started

* [Index](index)
* [Introduction](/home/getting-started/introduction) — What Bleepay is and why it exists
* [Core Concepts](/home/getting-started/core-concepts) — Vouchers, sessions, and settlement
* [Quickstart](/home/getting-started/quickstart) — Your first EURC payment via the API

### Web2/Web3 Payments

* [Integration Overview](/home/web2-web3-payments/overview) — Parameters, webhooks, and how Bleepay fits into your stack
* [Simple Payments](/home/web2-web3-payments/simple-payments) — SIMPLE vouchers for token transfers with built-in FX
* [Sessions](/home/web2-web3-payments/sessions) — Group multiple vouchers into a single session
* [Smart Contracts](/home/web2-web3-payments/smart-contracts) — CUSTOM vouchers for contract interactions

### E-Commerce

* [Overview](/home/e-commerce/overview) — Accept crypto at checkout, receive fiat
* [Benefits](/home/e-commerce/benefits) — Why merchants choose Bleepay
* [Checkout Flow](/home/e-commerce/checkout-flow) — Customer and merchant steps
* [Webhooks](/home/e-commerce/webhooks) — Event types, payloads, and verification

### Integrations

* [Overview](/home/integration/dapps) — How Bleepay integrates into dapps
* [Wallet Providers](/home/integration/wallet-providers) — Integrate Bleepay into a wallet
* [dApp Integration](/home/integration/developers) — Code-based wallet connections for dApps
* [Web3 Processing](/home/integration/processing) — Swaps, DeFi, and complex on-chain actions

### Architecture

* [System Overview](/home/architecture/system-overview) — The two products at a glance
* [Bleepay Widget](/home/architecture/bleepay-widget) — Crypto payment gateway
* [Bleepay Wallet](/home/architecture/bleepay-wallet) — Vouchers and the wallet app
* [Payment Flows](/home/architecture/payment-flows) — Deposit, voucher, FX, and fiat off-ramp
* [How Money Moves](/home/architecture/how-money-moves) — Fund flows by scenario
* [Custody Model](/home/architecture/custody-model) — Non-custodial across both products
* [Onboarding & KYC/KYB](/home/architecture/onboarding-kyc-kyb) — Identity verification for merchants
* [Security](/home/architecture/security) — Zero-trust and non-custodial model
* [Dependency Management](/home/architecture/dependencies) — Modular provider architecture
* [Fee Structure](/home/architecture/fees) — Cost layers and commercial terms

### Reference

* [Terminology](/home/reference/terminology) — Glossary of protocol terms
* [Protocol Flow](/home/reference/protocol-flow) — Voucher lifecycle from generation to settlement
* [Voucher Modes](/home/reference/voucher-modes) — Numeric vs alphanumeric voucher formats