Webhooks de depósito

Notificaciones de un payin, desde que la transferencia aparece en la red hasta que el monto está disponible en su saldo.

Pagos parciales

Un depósito se marca como completed, y se envían payment_detected / payment_confirmed, cuando received_amount alcanza minimum_payment por ciento de crypto_amount. minimum_payment se define por cuenta; por debajo de 100, el cliente puede haber pagado menos que la factura. Antes de entregar, compare data.received_amount con data.crypto_amount (ambos en data.crypto_currency) y decida qué hacer con la diferencia.

payment_detectedPago detectado

La transacción apareció en la red y el payin está completado, pero este no es el estado final. funds_available es false y finality_status es pending_finality mientras el bloque aún pueda reorganizarse. Si necesita agilidad, puede liberar el producto con este aviso. El monto queda retenido y no forma parte del saldo disponible hasta que la red alcance las confirmaciones requeridas.

Liberar el producto en esta etapa es una decisión suya. Un retiro de ese monto se rechaza hasta el payment_confirmed.

json

{
  "data": {
    "status": "success",
    "wallet": "0xDeaD0000000000000000000000000000000000a1",
    "network": "BinanceSmartChain",
    "paid_with": [
      {
        "amount": "25.000000000000000000",
        "currency": "USDT"
      }
    ],
    "created_at": "2026-03-01 12:00:00",
    "cross_token": false,
    "fiat_amount": "25.00",
    "network_fee": "0.00000500",
    "confirmed_at": null,
    "percent_rate": "0.50",
    "reference_id": "11111111-1111-4111-8111-111111111111",
    "transactions": "[\"0xabc0000000000000000000000000000000000000000000000000000000000def\"]",
    "confirmations": null,
    "crypto_amount": "25.00000000",
    "customer_info": "customer@example.com",
    "fiat_currency": "USD",
    "is_duplicated": false,
    "crypto_currency": "USDT",
    "finality_status": "pending_finality",
    "funds_available": false,
    "is_wallet_fixed": false,
    "received_amount": "25.00000000",
    "reversal_reason": null,
    "internal_reference": "22222222-2222-4222-8222-222222222222",
    "received_amount_fiat": "25.00",
    "estimated_release_seconds": null,
    "received_amount_fiat_current": "25.00"
  },
  "event": "payment_detected",
  "timestamp": "2026-03-01 12:02:00"
}

payment_confirmedPago confirmado

El bloque es final. funds_available es true y el monto está disponible en su saldo. Acredite al cliente de forma definitiva con este evento.

json

{
  "data": {
    "status": "success",
    "wallet": "0xDeaD0000000000000000000000000000000000a1",
    "network": "BinanceSmartChain",
    "paid_with": [
      {
        "amount": "25.000000000000000000",
        "currency": "USDT"
      }
    ],
    "created_at": "2026-03-01 12:00:00",
    "cross_token": false,
    "fiat_amount": "25.00",
    "network_fee": "0.00000500",
    "confirmed_at": null,
    "percent_rate": "0.50",
    "reference_id": "11111111-1111-4111-8111-111111111111",
    "transactions": "[\"0xabc0000000000000000000000000000000000000000000000000000000000def\"]",
    "confirmations": null,
    "crypto_amount": "25.00000000",
    "customer_info": "customer@example.com",
    "fiat_currency": "USD",
    "is_duplicated": false,
    "crypto_currency": "USDT",
    "finality_status": "final",
    "funds_available": true,
    "is_wallet_fixed": false,
    "received_amount": "25.00000000",
    "reversal_reason": null,
    "internal_reference": "22222222-2222-4222-8222-222222222222",
    "received_amount_fiat": "25.00",
    "estimated_release_seconds": null,
    "received_amount_fiat_current": "25.00"
  },
  "event": "payment_confirmed",
  "timestamp": "2026-03-01 12:03:00"
}

payment_reversedPago revertido

Una reorganización deshizo el depósito y el crédito fue retirado. data.status es reversed y reversal_reason indica el motivo. Desde ese momento check-payin y list-payin también devuelven status reversed, así que una integración que consulta por polling también lo ve. Si el producto ya se había liberado en payment_detected, concilie esa entrega con este aviso.

json

{
  "data": {
    "status": "reversed",
    "wallet": "0xDeaD0000000000000000000000000000000000a1",
    "network": "BinanceSmartChain",
    "paid_with": [
      {
        "amount": "25.000000000000000000",
        "currency": "USDT"
      }
    ],
    "created_at": "2026-03-01 12:00:00",
    "cross_token": false,
    "fiat_amount": "25.00",
    "network_fee": "0.00000500",
    "confirmed_at": null,
    "percent_rate": "0.50",
    "reference_id": "11111111-1111-4111-8111-111111111111",
    "transactions": "[\"0xabc0000000000000000000000000000000000000000000000000000000000def\"]",
    "confirmations": null,
    "crypto_amount": "25.00000000",
    "customer_info": "customer@example.com",
    "fiat_currency": "USD",
    "is_duplicated": false,
    "crypto_currency": "USDT",
    "finality_status": "reorged",
    "funds_available": false,
    "is_wallet_fixed": false,
    "received_amount": "25.00000000",
    "reversal_reason": "reorg",
    "internal_reference": "22222222-2222-4222-8222-222222222222",
    "received_amount_fiat": "25.00",
    "estimated_release_seconds": null,
    "received_amount_fiat_current": "25.00"
  },
  "event": "payment_reversed",
  "timestamp": "2026-03-01 12:04:00"
}

Cuando la detección ya es final

En algunas redes el pago es final en cuanto se detecta. payment_confirmed se envía justo después de payment_detected; payment_detected ya trae finality_status final, y payment_confirmed puede traer finality_status null. Decida por event y funds_available: no todo payment_detected retiene el monto.

Campos del depósito

Campo	Tipo	Descripción
funds_available	boolean	false mientras el monto está retenido. true cuando puede retirarse.
finality_status	string \| null	pending_finality mientras corren las confirmaciones, final cuando el bloque está consolidado, reorged cuando el depósito se deshizo. Puede ser null en un payment_confirmed de un pago que ya era final al detectarse.
confirmations	number \| null	Reservado para el recuento de confirmaciones. Hoy siempre es null; no dependa de él.
estimated_release_seconds	number \| null	Reservado para la estimación de espera hasta la liberación. Hoy siempre es null; no dependa de él.
reversal_reason	string \| null	Por qué se retiró el crédito. Null en payment_detected y payment_confirmed.
received_amount	string	Monto en cripto acreditado en el recibo.
received_amount_fiat	string	Valor fiat del monto recibido a la cotización de la invoice.
received_amount_fiat_current	string	Valor fiat a la cotización del momento en que se armó el webhook. Cae a la cotización de la invoice si el precio en vivo no está disponible.
cross_token	boolean	true cuando el cliente pagó con un token distinto del token de la invoice.
paid_with	array	Tokens realmente recibidos on-chain. Cada ítem tiene currency y amount.
is_wallet_fixed	boolean	true cuando el depósito cayó en una dirección fija.

is_duplicatedSolo Payin

true cuando Bifrost creó este payin por su cuenta, para un pago que no correspondía a un payin abierto: un pago extra a una dirección cuyo payin ya estaba completado, o un pago en una red distinta de la factura. Es un payin nuevo, con internal_reference propio y un reference_id generado por Bifrost. El monto se acredita en su saldo y el aviso va al webhook_url del payin original.

Cuando is_duplicated es true, el reference_id no es suyo. Vincule el pago a su pedido por customer_info o wallet. El payin también aparece en List Payins y Check Specific Payin.

customer_info

Su propio identificador del cliente, como ID de usuario, e-mail o número de pedido. Se devuelve en los webhooks y listados, así sabe de quién es cada transacción, incluidos los payins que Bifrost crea por su cuenta (pagos adicionales y depósitos en direcciones fijas), cuyo reference_id genera Bifrost.