# Webhooks de depósito

> Versión en Markdown de la documentación pública de la API v1 de Bifrost Crypto, para agentes de IA y generadores de código. El mismo contenido de las páginas HTML, generado de la misma fuente, sin navegación ni estilos.
>
> Versión HTML: https://bifrostcrypto.com/es/docs/webhooks-receipts
> Archivos relacionados: [ai.md](https://bifrostcrypto.com/ai/es.md) · [Postman](https://bifrostcrypto.com/postman-collection.json) · [OpenAPI](https://bifrostcrypto.com/openapi.json) · [llms.txt](https://bifrostcrypto.com/llms.txt)
> Otros idiomas: [Português](https://bifrostcrypto.com/ai/pt-BR/webhooks-receipts.md) · [English](https://bifrostcrypto.com/ai/en/webhooks-receipts.md) · [Français](https://bifrostcrypto.com/ai/fr/webhooks-receipts.md)
> API v1 · último cambio de contrato el 2026-10-10

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_detected` · Pago 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. Hasta hoy ningún pago detectado por Bifrost ha sido revertido; vea payment_reversed.

```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_confirmed` · Pago 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_reversed` · Pago revertido

Puede estar tranquilo: hasta hoy ningún pago recibido por Bifrost ha sido revertido.

Este aviso existe solo por las redes L2, como Arbitrum, Optimism y Base. En ellas, el pago se detecta en cuanto entra en un bloque de la L2 (payment_detected), en segundos, y se vuelve definitivo cuando ese bloque se finaliza en la red principal (payment_confirmed), unos minutos después. En teoría, una transacción puede deshacerse en ese intervalo. Es rarísimo, pero como la posibilidad existe, preferimos documentarlo.

Si ocurre, el crédito de ese depósito se retira del saldo, data.status viene como reversed y reversal_reason indica el motivo. A partir de ahí, check-payin y list-payin también devuelven status reversed.

Si usted libera el producto solo en payment_confirmed, este aviso no le afecta. Si lo libera en payment_detected, basta con vincular este aviso al pedido por internal_reference.

```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_duplicated`** (Solo 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.