APIConceptos
Una empresa, una cuenta FITAL, y lo que se mueve dentro de ella.
Tu empresa tiene una cuenta FITAL. Sobre ella hay saldos, beneficiarios, cotizaciones, pagos, cobros, depósitos y movimientos. Cada recurso tiene un identificador con prefijo.
| Concepto | Prefijo | Qué es |
|---|---|---|
| Beneficiario | ben_ | Destino de un pago. Se aprueba en el panel antes de poder pagarle |
| Cotización | quo_ | Monto de débito indicativo, con vencimiento |
| Pago | pay_ | Salida de dinero a un beneficiario |
| Cobro | col_ | Instrucción para que un cliente te pague |
| Dirección de depósito | dep_ | Dirección para recibir un token por una red |
| Depósito | dpt_ | Dinero recibido, con los datos del pagador si el riel los informa |
| Movimiento | mov_ | Cualquier entrada o salida de tu cuenta |
Saldos y cuentas para recibir
GET /v1/balances da lo disponible por moneda. GET /v1/wallets da lo mismo por wallet, con su red: la suma por moneda coincide, salvo redondeo al centavo, y las wallets sólo se consultan. GET /v1/receiving-accounts da las cuentas donde puedes recibir fondos, y POST /v1/receiving-accounts abre una nueva, como en Cuentas para recibir. GET /v1/limits da los rieles habilitados y el máximo aplicable, si existe.
Beneficiarios
El alta por API crea el beneficiario pendiente. La aprobación ocurre en el panel y nunca por API: una llave robada no puede pagar a un destino nuevo. No hay espera ni tope de monto; sí hay aprobación.
| Estado | Significado |
|---|---|
processing | El alta sigue en curso |
pending_approval | Falta aprobarlo en el panel |
approved | Ya se le puede pagar |
rejected | No se aprobó |
deleted | Se dio de baja |
Pagos
El riel sale del beneficiario, no lo eliges en la petición. Queda fijo al crear el pago: dar de baja al beneficiario después no lo cambia. Estos son los estados públicos:
| Estado | Significado | ¿Terminal? |
|---|---|---|
processing | Aceptado y en curso, o aún sin confirmar | No |
in_review | En revisión. No repitas el pago | No |
completed | Se pagó. Aún puede pasar a returned | Sí |
failed | No se hizo y no queda dinero en tránsito | Sí |
returned | Se devolvió y el saldo ya volvió | Sí |
canceled | Se canceló antes de ejecutarse | Sí |
Trata estas listas como extensibles: un valor nuevo no rompe la versión. Tu código debe tolerar un estado que no conoce.
Con failed, GET /v1/payments/{id} y payment.failed traen failure_code, un código del catálogo de errores. Nunca llega en null en un pago failed: sin un motivo más específico, o si el detalle ya no se puede leer, es payment_rejected. La lista GET /v1/payments no lo trae: ahí siempre es null. Los valores están en Consultar un pago.
processing tampoco garantiza que el pago siga avanzando. Si un pago se reenvía y ese reenvío cae, sigue en processing hasta que FITAL lo cierre, y entonces llega su estado final. No lo repitas. Si lleva demasiado tiempo así, escribe a soporte con el pay_.
Un estado terminal se puede corregir
Terminal significa que no esperas otro cambio, no que sea imposible. Una lectura parcial no mueve el estado de un pago, salvo un rechazo ya cerrado. Una lectura concluyente sí, también hacia atrás: un completed que se devuelve o un canceled que se reabre cambian de estado y publican su evento. Ver Orden. Esto aplica a pagos, no a cobros.
Qué confirma un completed
completed exige confirmación del riel. En latam la da el banco de destino: mientras no llegue, el pago sigue en processing. Si no se sabe el riel de un pago, ninguna lectura nueva lo da por completed: el detalle responde lo último que se sabe, con freshness.status en delayed, y su movimiento sale en processing con read_status: "partial".
Frescura del detalle
GET /v1/payments/{id} lee el estado en vivo y dice de dónde salió en freshness. Ese campo sólo existe en el detalle.
freshness.status | Qué significa | freshness.as_of |
|---|---|---|
current | status sale de una lectura de ahora | La hora de esa lectura |
delayed | La lectura no concluyó: status es lo último que se sabe | La hora de la última lectura aplicada o de la cancelación confirmada. null si aún no hay ninguna |
Con delayed, no tomes status como un resultado nuevo: consulta otra vez más tarde. Una cancelación confirmada responde canceled con delayed hasta que una lectura la confirme. Si ese pago responde después processing con current, se reabrió de verdad.
Lista y detalle
GET /v1/payments es una vista guardada: no lee en vivo y no lleva freshness. Puede ir una vuelta de sincronización por detrás del detalle, también justo después de cancelar, y se pone al día sola. Esa vuelta es la misma que publica los eventos: normalmente tarda de 20 a 120 segundos. Para decidir sobre un pago, usa el detalle.
Vigilancia de un pago completado
Un pago completed en latam se vigila leyendo el riel durante 120 días desde la primera lectura que lo vio completado. Después, una devolución tardía puede no generar evento ni aparecer en GET /v1/payments. Ese plazo no garantiza que una devolución no llegue más tarde.
En los demás rieles nada lee el riel por su cuenta: la devolución se conoce por el aviso del riel. Es el caso normal, y entonces llega payment.returned. Si ese aviso no llegara y nadie consultara el pago, la devolución no se vería, ni dentro de esos 120 días ni después.
En cualquier riel, GET /v1/payments/{id} lee en vivo y da el estado real. Si tu cierre depende de un pago, consúltalo ahí. Si esa consulta ve otro estado, el pago vuelve a vigilarse y el cambio se publica.
Cotizaciones
POST /v1/quotes devuelve cuánto se debitaría, en source_amount y source_currency. Es indicativa y vence en expires_at, a los 60 segundos en producción. Si envías su quote_id al crear el pago, el débito no puede superar lo cotizado.
Errores comunes
- Dar por fallido un pago en
processing. Consulta elpay_hasta un estado terminal. - Tomar
delayedcomo un resultado nuevo. Es lo último que se sabe. - Decidir sobre un pago con
GET /v1/payments. Es una vista: usa el detalle. - Pagar a un beneficiario sin aprobar: responde
422 beneficiary_not_approved.