# Recibir un pago

> 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/guide-payin
> 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/guide-payin.md) · [English](https://bifrostcrypto.com/ai/en/guide-payin.md) · [Français](https://bifrostcrypto.com/ai/fr/guide-payin.md)
> API v1 · último cambio de contrato el 2026-10-10

Desde elegir el token hasta entregar el pedido, con payins creados por la API.

## 1. Elija el token y la red

GET /v1/summary/tokens lista los tokens de la plataforma por red, con min_receipt y max_receipt. La lista no está filtrada por su cuenta: la creación del payin confirma si el token acepta depósitos para usted en esa red.

```bash
curl "https://bridge.bifrostcrypto.com/v1/summary/tokens" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY"
```

## 2. Cree el payin

POST /v1/payin con un reference_id único en su sistema, el monto (process_by crypto_amount o fiat_amount), webhook_url y, si quiere, expires_at en segundos (4 horas por defecto). Guarde el internal_reference de la respuesta y muestre al cliente la wallet, y el memo cuando el token lo exija.

```bash
curl -X POST "https://bridge.bifrostcrypto.com/v1/payin" \
  -H "X-Bifrost-Invoke: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference_id":"order_1001","crypto_currency":"USDT","network":"BinanceSmartChain","process_by":"crypto_amount","crypto_amount":"50","webhook_url":"https://your-site.com/webhook","customer_info":"customer_42"}'
```

## 3. Reciba el webhook

Verifique X-Bifrost-Signature sobre el cuerpo crudo, responda 2xx en menos de 30 segundos y procese después. El mismo aviso puede llegar más de una vez: elimine duplicados por data.internal_reference junto con event.

## 4. Compruebe el monto antes de entregar

El payin queda completado cuando received_amount alcanza minimum_payment por ciento de crypto_amount, que puede ser menos que el total. Compare data.received_amount con data.crypto_amount y decida qué hacer con la diferencia.

## 5. Elija cuándo entregar

payment_detected significa que la transferencia se vio (funds_available false): entregar ahora es su decisión y conlleva el riesgo de una reversión. payment_confirmed significa que es final (funds_available true).

## 6. Trate las excepciones

payment_reversed: la red deshizo el pago y se retiró el crédito; check-payin pasa a devolver status reversed. is_duplicated true: un pago extra o en otra red generó un payin nuevo con referencias propias; vincúlelo al pedido por customer_info.

## 7. Concilie

GET /v1/check-payin/{internal_reference} devuelve el payin en cualquier momento. GET /v1/statements lista los movimientos del saldo: DEPOSIT para el crédito, RATE y FEE para los cargos.

## Qué hacer cuando algo falla

POST /v1/payin no tiene Idempotency-Key. El reference_id es lo que impide un segundo payin.

| Situación | Qué hacer |
| --- | --- |
| Timeout o sin respuesta en POST /v1/payin | Reenvíe con el mismo reference_id. Si la respuesta es duplicate_reference_id, la primera solicitud funcionó: obténgala con GET /v1/list-payin?reference_id=… |
| 400 | Corrija la solicitud. Reenviarla sin cambios da la misma respuesta. |
| 500, 502 o 503 | No se creó nada. Reintente más tarde con el mismo reference_id. |
| 429 | Espere los segundos indicados en Retry-After. |
| El webhook no llegó | Las entregas se repiten hasta 10 veces, con unos 5 minutos entre ellas. Mientras tanto, consulte el payin con GET /v1/check-payin/{internal_reference}. |

> Los payins creados en el panel no los devuelve la API.