Modos de integración

Redirect Gateway (solo online)

El comercio redirige al cliente a la pasarela hospedada de B4bit Pay. Es el flujo más simple de integrar: basta con una llamada al backend y una redirección.

Variante A — con input_currency

El merchant pre-selecciona la moneda antes de redirigir. La pasarela muestra dirección + monto listos.

1. GET /currencies           → obtener símbolos disponibles
2. POST /orders/             → indicar expected_output_amount + input_currency + URLs
3. web_url devuelto          → redirigir al cliente
4. webhook llega en cambio de estado

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/

Variante B — sin input_currency

El cliente elige la moneda en la pasarela. Útil cuando no conoce las preferencias de su cliente.

1. POST /orders/             → solo expected_output_amount + URLs
2. web_url devuelto          → redirigir
3. cliente elige moneda en la pasarela de B4bit Pay

Consejo

Si usa la Variante B, la respuesta no incluye payment_uri, address, tag_memo ni expected_input_amount — esos campos se generan cuando el cliente elige la moneda en la pasarela.

API Gateway (online y offline)

El merchant recibe todos los datos del pago y los muestra en su propia UI. Útil para TPV físicos, apps móviles propias o integraciones profundas.

1. POST /orders/             → con input_currency obligatorio
2. respuesta completa        → payment_uri, address, tag_memo, expected_input_amount, rate
3. merchant renderiza QR / muestra dirección en su pantalla
4. cliente paga desde su wallet
5. webhook notifica cambios de estado

Campos clave en la respuesta

• payment_uri — URI tipo bitcoin:<address>?amount=X listo para codificar en un QR.
• address — dirección destino en la blockchain.
• tag_memo — obligatorio en XRP / XLM / ALGO. Muestre junto con la dirección.
• expected_input_amount — cantidad exacta de cripto a pagar.
• rate — precio de la cripto en USDC al momento (bloqueado durante la validez de la orden).

Precaución

TAG/MEMO — si input_currency es XRP, XLM o ALGO, muestre el tag_memo con la misma prominencia visual que la dirección. Si el cliente no lo envía, los fondos se pierden.

Bitcoin Lightning (BTCL)

Lightning Network no usa direcciones. La respuesta de POST /orders/ con input_currency=BTCL devuelve un invoice BOLT11 en el campo payment_uri.

El cliente lo paga desde su wallet Lightning (Wallet of Satoshi, Phoenix, Zeus, etc.). La confirmación es prácticamente instantánea.

Cuál elegir

Caso de uso	Modo recomendado
E-commerce web estándar	Redirect Gateway (Variante A o B)
Checkout in-site con UX totalmente propia	API Gateway
Punto de venta físico (TPV, caja)	API Gateway
App móvil propia	API Gateway
Link de pago compartible	Redirect Gateway (Variante B)

Ver también los modos de pago disponibles desde el dashboard sin API.