Integración API

B4bit Pay expone una API REST pequeña y enfocada (5 endpoints) que cubre todo el ciclo de vida de un pago en cripto.

• Base URL: https://pos.b4bit.com/api/v1
• Autenticación: cabecera X-Device-Id (la API key del dispositivo)
• Notificaciones: webhook firmado HMAC-SHA256 por cada cambio de estado
• Redoc oficial: https://pos.b4bit.com/redoc

Consulte también la Referencia API para el detalle endpoint por endpoint.

Dos modos de integración

B4bit Pay soporta dos flujos distintos. Elija el que mejor se adapte a su caso de uso.

Redirect Gateway (solo online)

Usted redirige al cliente a la pasarela hospedada de B4bit Pay. Es el camino más simple y rápido de integrar.

Variante con input_currency:

1. El comercio llama a GET /currencies para conocer las opciones disponibles.
2. El comercio llama a POST /orders/ con expected_output_amount, input_currency, URLs de redirección y descripción.
3. B4bit Pay responde con web_url; su servidor redirige al cliente allí.

Variante sin input_currency:

1. El comercio solo llama a POST /orders/ con importe y URLs.
2. El cliente elige la moneda directamente en la pasarela de B4bit Pay.
3. B4bit Pay devuelve web_url; su servidor redirige.

API Gateway (online y offline)

Usted muestra los datos del pago directamente en su UI (típico en TPV físicos).

1. El comercio llama a POST /orders/ con expected_output_amount + input_currency.
2. B4bit Pay responde con payment_uri, address, tag_memo, expected_input_amount, rate.
3. El comercio construye el QR o muestra la información en su pantalla.
4. El cliente paga desde su wallet.
5. B4bit Pay notifica el cambio de estado vía webhook.

Precaución

TAG/MEMO: si input_currency es XRP, XLM o ALGO, el tag_memo es obligatorio al pagar. Si no se envía, los fondos se pierden. Muéstrelo siempre al cliente con la misma prominencia que la dirección.

Ejemplo rápido

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())

Mapeo a estados de su merchant

Los 11 estados de pago de B4bit Pay se pueden resumir en 4 estados típicos de un merchant:

Estado B4bit Pay	Estado merchant
NR / PE / AC con safe=false	Pending
CO / AC con safe=true / CM	Processing (o Paid)
CA / EX	Cancelled
FA / OC / IA	Failed
DE	Deleted

El campo safe indica si el pago ya tiene una confirmación blockchain y es seguro liberar producto/servicio.

Siguientes pasos

Referencia API 5 endpoints con request/response completo.

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

Quickstart Guía de 5 minutos con ejemplos.

Modos de integración Redirect vs API Gateway en detalle.