Integration modes

Redirect Gateway (online only)

The merchant redirects the customer to B4bit Pay’s hosted gateway. This is the simplest flow to integrate: just a single backend call and a redirect.

Variant A — with input_currency

The merchant pre-selects the currency before redirecting. The gateway shows the address and amount ready to pay.

1. GET /currencies           → fetch available symbols
2. POST /orders/             → send expected_output_amount + input_currency + URLs
3. returned web_url          → redirect the customer
4. webhook arrives on status change

cURL

curl -X POST \
-H "X-Device-Id: $B4BIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "expected_output_amount": 2500.0,
  "fiat": "MXN",
  "input_currency": "USDC_POLYGON_NXTB",
  "merchant_urlok": "https://tu-sitio.com/pago/ok",
  "merchant_urlko": "https://tu-sitio.com/pago/error",
  "notes": "Pedido ORD-123",
  "reference": "ORD-123"
}' \
https://pos.b4bit.com/api/v1/orders/

Variant B — without input_currency

The customer picks the currency on the gateway. Useful when you don’t know your customer’s preferences.

1. POST /orders/             → only expected_output_amount + URLs
2. returned web_url          → redirect
3. customer picks currency on the B4bit Pay gateway

Tip

With Variant B, the response does not include payment_uri, address, tag_memo, or expected_input_amount — those fields are generated when the customer picks a currency on the gateway.

API Gateway (online and offline)

The merchant receives all payment data and renders it in its own UI. Useful for physical POS, native mobile apps, or deep integrations.

1. POST /orders/             → input_currency is required
2. full response             → payment_uri, address, tag_memo, expected_input_amount, rate
3. merchant renders QR / displays address on its screen
4. customer pays from their wallet
5. webhook delivers status changes

Key response fields

• payment_uri — URI like bitcoin:<address>?amount=X, ready to encode in a QR.
• address — destination address on the blockchain.
• tag_memo — required for XRP / XLM / ALGO. Display it alongside the address.
• expected_input_amount — exact amount of crypto to pay.
• rate — price of the crypto in USDC at that moment (locked for the order’s validity window).

Caution

TAG/MEMO — if input_currency is XRP, XLM, or ALGO, display tag_memo with the same visual prominence as the address. If the customer omits it, the funds are lost.

Bitcoin Lightning (BTCL)

Lightning Network does not use addresses. The POST /orders/ response with input_currency=BTCL returns a BOLT11 invoice in the payment_uri field.

The customer pays it from their Lightning wallet (Wallet of Satoshi, Phoenix, Zeus, etc.). Confirmation is practically instant.

Which to choose

Use case	Recommended mode
Standard web e-commerce	Redirect Gateway (Variant A or B)
In-site checkout with fully custom UX	API Gateway
Physical point of sale (POS, register)	API Gateway
Native mobile app	API Gateway
Shareable payment link	Redirect Gateway (Variant B)

See also the payment modes available from the dashboard without API.