API Integration

B4bit Pay exposes a small, focused REST API (5 endpoints) that covers the entire lifecycle of a crypto payment.

• Base URL: https://pos.b4bit.com/api/v1
• Authentication: X-Device-Id header (the device API key)
• Notifications: HMAC-SHA256 signed webhook on every state change
• Official Redoc: https://pos.b4bit.com/redoc

See also the API Reference for endpoint-by-endpoint details.

Two integration modes

B4bit Pay supports two different flows. Choose the one that best fits your use case.

Redirect Gateway (online only)

You redirect the customer to the hosted B4bit Pay gateway. It is the simplest and fastest path to integrate.

Variant with input_currency:

1. The merchant calls GET /currencies to learn the available options.
2. The merchant calls POST /orders/ with expected_output_amount, input_currency, redirect URLs and description.
3. B4bit Pay responds with web_url; your server redirects the customer there.

Variant without input_currency:

1. The merchant only calls POST /orders/ with amount and URLs.
2. The customer chooses the currency directly on the B4bit Pay gateway.
3. B4bit Pay returns web_url; your server redirects.

API Gateway (online and offline)

You display the payment data directly in your UI (typical in physical POS terminals).

1. The merchant calls POST /orders/ with expected_output_amount + input_currency.
2. B4bit Pay responds with payment_uri, address, tag_memo, expected_input_amount, rate.
3. The merchant builds the QR code or displays the information on their screen.
4. The customer pays from their wallet.
5. B4bit Pay notifies the state change via webhook.

Caution

TAG/MEMO: if input_currency is XRP, XLM or ALGO, tag_memo is required at payment time. If it is not sent, the funds are lost. Always display it to the customer with the same prominence as the address.

Quick example

cURL

curl -H "X-Device-Id: $B4BIT_API_KEY" \
https://pos.b4bit.com/api/v1/currencies

Node (undici)

import { fetch } from 'undici';

const res = await fetch('https://pos.b4bit.com/api/v1/currencies', {
headers: { 'X-Device-Id': process.env.B4BIT_API_KEY },
});
console.log(await res.json());

Python

import os, requests

res = requests.get(
  'https://pos.b4bit.com/api/v1/currencies',
  headers={'X-Device-Id': os.environ['B4BIT_API_KEY']},
)
print(res.json())

Mapping to your merchant states

The 11 B4bit Pay payment states can be summarized into 4 typical merchant states:

B4bit Pay state	Merchant state
NR / PE / AC with safe=false	Pending
CO / AC with safe=true / CM	Processing (or Paid)
CA / EX	Cancelled
FA / OC / IA	Failed
DE	Deleted

The safe field indicates whether the payment already has one blockchain confirmation and it is safe to release the product/service.

Next steps

API Reference 5 endpoints with complete request/response.

Webhook HMAC-SHA256, X-NONCE, test vectors.

Quickstart 5-minute guide with examples.

Integration modes Redirect vs API Gateway in detail.