Recibir un pago

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

  1. 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. 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. 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. 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. 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. 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. 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ónQué hacer
Timeout o sin respuesta en POST /v1/payinReenví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=…
400Corrija la solicitud. Reenviarla sin cambios da la misma respuesta.
500, 502 o 503No se creó nada. Reintente más tarde con el mismo reference_id.
429Espere 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.