Campos del pago (schema Payment)

El schema Payment del endpoint GET /orders/info/{identifier} devuelve ~25 campos. Muchos tienen nombres obvios, pero otros necesitan contexto. Esta página los aclara.

Identificación

• identifier (UUID4) — ID único del pago asignado por B4bit Pay. Úselo como clave externa en su sistema.
• reference (string) — Su propio ID interno (el que pasó al crear la orden). Sirve para correlacionar.
• merchant_device_id (int) y merchant_device (string) — ID y nombre del dispositivo que cobró.

Estado

• status — enum de 11 valores (NR, PE, AC, IA, CO, CA, EX, OC, FA, DE, CM). Ver estados de pago.
• created_at, edited_at — timestamps ISO 8601 UTC.
• expired_time — cuándo expira la orden si no se paga (ISO 8601).

Importes

Precaución

Todos los importes monetarios (fiat_amount, received_amount, etc.) del schema Payment están expresados en USDC, no en la divisa fiat del merchant. La divisa que el merchant seleccionó al crear la orden queda reflejada en el campo fiat, pero los valores numéricos son siempre el equivalente en USDC.

• fiat_amount — importe en USDC equivalente al expected_output_amount que pasó al crear la orden (B4bit convierte con el rate bloqueado al crear).
• crypto_amount — cantidad total de cripto que debe recibir para liquidar esa orden.
• unconfirmed_amount — visto en mempool, sin confirmaciones blockchain.
• confirmed_amount — con ≥1 confirmación blockchain.
• received_amount — importe recibido, también en USDC (suma confirmada convertida al rate).
• percentage — % del crypto_amount recibido ya. Útil para mostrar barra de progreso al cliente.

Moneda / red

• currency_id — símbolo granular de B4bit Pay (por ejemplo USDC_POLYGON_NXTB). En el webhook se llama currency sin _id.
• fiat — divisa fiat de la orden (MXN, EUR, etc.). En el webhook se llama fiat_currency.
• language — idioma de la pasarela (por defecto ES).

Blockchain

• address — dirección destino donde el cliente envía la cripto.
• tag_memo — TAG / MEMO obligatorio en XRP / XLM / ALGO. Si es null, la moneda no lo requiere.
• rbf (boolean) — “Replace By Fee”. Solo puede ser true en BTC. Indica que una transacción pendiente podría ser reemplazada por otra con fee más alta. Asuma pago no estable mientras rbf=true.

Flags de seguridad

• safe (boolean) — ★ el campo más importante después de status. true indica que el pago tiene suficientes confirmaciones para considerarse estable. Úselo como señal para liberar producto/servicio.
• good_fee (boolean) — indica si el fee de red de la transacción entrante es adecuado. Si false, la confirmación podría tardar más.
• balance_based (string) — campo interno relacionado con transacciones que consumen balance pre-cargado. Para merchants estándar, irrelevante.

URLs de redirección (solo respuesta del create, no del info)

• web_url — URL de la pasarela hospedada (para Redirect Gateway).
• url_ok, url_ko, url_standby — redirects configurados por el merchant.

Notas y metadatos

• notes — descripción del producto/servicio.
• internal_data — campo libre que usted puede usar para meta propia (hasta 1024 chars).

Transacciones

• transactions — array de objetos con cada transacción blockchain detectada:
  • confirmed (boolean)
  • currency
  • amount
  • tx_hash (solo lectura)
  • block (número de bloque donde se confirmó)
  • created_at

Consejo

Si un pago acaba en OC (Out of Condition) pero hay múltiples transacciones, revise cada una en transactions para entender si el cliente pagó en partes o si una transacción se quedó sin confirmar.

Campo crítico en resumen

Si solo va a persistir 4 campos, persista:

• identifier — para lookups futuros.
• status — estado actual.
• safe — señal de “puedo liberar”.
• edited_at — para deduplicar webhooks y ordenar cambios.