# Conceptos

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`](/docs/operaciones/listar-saldos/) da lo disponible por moneda. [`GET /v1/wallets`](/docs/operaciones/listar-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`](/docs/operaciones/listar-cuentas-para-recibir/) da las cuentas donde puedes recibir fondos, y [`POST /v1/receiving-accounts`](/docs/operaciones/abrir-cuenta-para-recibir/) abre una nueva, como en [Cuentas para recibir](/docs/recetas/cuentas-para-recibir/). [`GET /v1/limits`](/docs/operaciones/consultar-limites/) 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}`](/docs/operaciones/consultar-pago/) y `payment.failed` traen `failure_code`, un código del [catálogo de errores](/docs/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`](/docs/operaciones/listar-pagos/) no lo trae: ahí siempre es `null`. Los valores están en [Consultar un pago](/docs/operaciones/consultar-pago/#valores-de-failure_code).

`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](/docs/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](/docs/webhooks/eventos/#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}`](/docs/operaciones/consultar-pago/) 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`](/docs/operaciones/listar-pagos/) 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`](/docs/operaciones/listar-pagos/). 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}`](/docs/operaciones/consultar-pago/) 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`](/docs/operaciones/crear-cotizacion/) 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 el `pay_` hasta un estado terminal.
- Tomar `delayed` como un resultado nuevo. Es lo último que se sabe.
- Decidir sobre un pago con [`GET /v1/payments`](/docs/operaciones/listar-pagos/). Es una vista: usa el detalle.
- Pagar a un beneficiario sin aprobar: responde `422 beneficiary_not_approved`.

## Qué sigue

[Ambientes](/docs/ambientes/) y [Autenticación](/docs/autenticacion/).