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

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:

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

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

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 — full parameter reference and Web2 vs Web3 modes.
• Simple Payments — SIMPLE vouchers, FX, and negotiation.
• Webhooks — event-driven settlement tracking.