# Pagos, con su último estado conocido GET /v1/payments Pagos creados por esta API, con su último estado conocido, del más nuevo al más viejo. Para el estado más fresco de uno, usa `GET /v1/payments/{id}`. | Dato | Valor | |---|---| | Método y ruta | `GET /v1/payments` | | Servidor | `https://widget.fital.xyz` | | `operationId` | `listPayments` | | Acceso | Llave con el scope `payments:read` | | Firma de petición | No aplica | | Idempotencia | No aplica | - Es una vista guardada: no lee en vivo y no lleva `freshness`. Puede ir una vuelta por detrás del detalle. Ver [Lista y detalle](/docs/conceptos/#lista-y-detalle). - `failure_code` llega en `null` en esta lista, también con `failed`: léelo en `GET /v1/payments/{id}` o en `payment.failed`. ## Encabezados de la petición | Encabezado | Obligatorio | Descripción | |---|---|---| | `Authorization` | Sí | `Bearer` y tu llave. | | `X-Fital-Scenario` | No | Sólo simuladores: elige la respuesta que quieres practicar. | ## Parámetros | Parámetro | En | Tipo | Obligatorio | Descripción | |---|---|---|---|---| | `limit` | consulta | texto | No | Filas por página, de 1 a 100. Por omisión, 25. | | `cursor` | consulta | texto | No | Valor de `next_cursor` de la página anterior. Hasta 1000 caracteres. | ## Respuestas correctas ### 200 Correcto | Campo | Tipo | Obligatorio | Descripción | |---|---|---|---| | `data` | lista de objeto | Sí | Filas de esta página. | | `data[].amount` | texto o `null` | Sí | Monto pedido. | | `data[].beneficiary_id` | texto o `null` | Sí | Beneficiario del pago. | | `data[].created_at` | texto o `null` | Sí | Fecha de creación. ISO 8601 en UTC. | | `data[].currency` | texto o `null` | Sí | Moneda pedida. | | `data[].external_ref` | texto o `null` | Sí | Tu referencia. | | `data[].failure_code` | texto o `null` | Sí | Código del catálogo de errores si el pago falló, null en cualquier otro estado. En `GET /v1/payments` siempre es null: léelo en `GET /v1/payments/{id}` o en `payment.failed`. Trata la lista como extensible. `payment_rejected`: Rechazado sin un motivo más específico. `insufficient_funds`: Saldo insuficiente al ejecutar. `limit_exceeded`: Se superó el tope acumulado de la empresa o un límite del riel. `amount_below_minimum`: El monto quedó por debajo del mínimo aplicable. `account_restricted`: La cuenta tiene una restricción. `in_review`: Una revisión detuvo la ejecución. `quote_changed`: El débito superaría lo permitido. `quote_expired`: La cotización venció antes de ejecutar. | | `data[].final_amount` | texto o `null` | Sí | Monto final, cuando se conoce. | | `data[].final_currency` | texto o `null` | Sí | Moneda del monto final. | | `data[].freshness` | objeto | No | De dónde sale `status`. Sólo en `GET /v1/payments/{id}`. | | `data[].freshness.as_of` | texto o `null` | Sí | Hora de esa lectura, de la última que se aplicó o de la cancelación confirmada. Null si aún no hay ninguna. ISO 8601 en UTC. | | `data[].freshness.status` | texto | Sí | De dónde sale `status`. `current`: `status` sale de una lectura de ahora. `delayed`: La lectura no concluyó y `status` es lo último que se sabe. No lo tomes como un resultado nuevo. | | `data[].id` | texto | Sí | Identificador del pago, con prefijo `pay_`. | | `data[].metadata` | objeto | Sí | Los pares que enviaste al crear el pago. | | `data[].reference` | texto o `null` | Sí | Concepto del pago. | | `data[].status` | texto | Sí | Estado público. `processing`: Aceptado y en curso, o aún sin confirmar. Consúltalo hasta un estado terminal. `in_review`: En revisión. No lo repitas: el pago ya existe. `completed`: Se pagó. Aún puede pasar a `returned`. `failed`: No se hizo y no queda dinero en tránsito. `returned`: Se devolvió y el saldo ya volvió. `canceled`: Se canceló antes de ejecutarse. | | `has_more` | booleano | Sí | true si hay más filas después de esta página. | | `next_cursor` | texto o `null` | Sí | Cursor de la página siguiente. null si no hay. | #### Valores de `data[].failure_code` | Valor | Significado | |---|---| | `payment_rejected` | Rechazado sin un motivo más específico. | | `insufficient_funds` | Saldo insuficiente al ejecutar. | | `limit_exceeded` | Se superó el tope acumulado de la empresa o un límite del riel. | | `amount_below_minimum` | El monto quedó por debajo del mínimo aplicable. | | `account_restricted` | La cuenta tiene una restricción. | | `in_review` | Una revisión detuvo la ejecución. | | `quote_changed` | El débito superaría lo permitido. | | `quote_expired` | La cotización venció antes de ejecutar. | Con `failed`, `GET /v1/payments/{id}` y `payment.failed` siempre traen un código: `payment_rejected` si no hay uno más específico. En cualquier otro estado, y en la lista `GET /v1/payments`, es `null`. Trata la lista como extensible. #### Valores de `data[].freshness.status` | Valor | Significado | |---|---| | `current` | `status` sale de una lectura de ahora. | | `delayed` | La lectura no concluyó y `status` es lo último que se sabe. No lo tomes como un resultado nuevo. | #### Valores de `data[].status` | Valor | Significado | |---|---| | `processing` | Aceptado y en curso, o aún sin confirmar. Consúltalo hasta un estado terminal. | | `in_review` | En revisión. No lo repitas: el pago ya existe. | | `completed` | Se pagó. Aún puede pasar a `returned`. | | `failed` | No se hizo y no queda dinero en tránsito. | | `returned` | Se devolvió y el saldo ya volvió. | | `canceled` | Se canceló antes de ejecutarse. | ```json { "data": [ { "amount": "1500.00", "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "created_at": "2026-11-04T18:00:00.000Z", "currency": "MXN", "external_ref": "pedido-7731", "failure_code": null, "final_amount": "1500.00", "final_currency": "MXN", "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "metadata": {}, "reference": "Factura 1042", "status": "completed" } ], "has_more": false, "next_cursor": null } ``` ## Encabezados de la respuesta | Encabezado | Contenido | |---|---| | `X-Request-Id` | Identificador de la petición. Cítalo con soporte. | | `Retry-After` | Segundos a esperar, con `429` y a veces con `503`. | ## Errores Todos usan la forma de [Errores](/docs/errores/): `error.code`, `message`, `request_id`, `details`, `retryable` y `docs_url`. Decide por `code`. | HTTP | Código | Cuándo sale | `retryable` | |---|---|---|---| | 400 | [`invalid_request`](/docs/errores/#invalid_request) | Algún parámetro o campo no cumple el esquema. Mira `details.fields`. | `false` | | 401 | [`invalid_api_key`](/docs/errores/#invalid_api_key) | La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida. | `false` | | 401 | [`wrong_environment`](/docs/errores/#wrong_environment) | La llave es de otro ambiente. | `false` | | 403 | [`forbidden_scope`](/docs/errores/#forbidden_scope) | La llave no tiene el scope de esta operación. `details.required_scope` lo nombra. | `false` | | 403 | [`ip_not_allowed`](/docs/errores/#ip_not_allowed) | La IP de origen no está activa en la lista de esa llave. | `false` | | 429 | [`rate_limited`](/docs/errores/#rate_limited) | Superaste un límite de peticiones. Llega con `Retry-After`. | `true` | | 500 | [`internal_error`](/docs/errores/#internal_error) | Fallo nuestro. El resultado de la petición no se conoce. | `true` | | 503 | [`service_unavailable`](/docs/errores/#service_unavailable) | El servicio no está disponible por ahora. El resultado de la petición no se conoce. | `true` | ### Ejemplos de error `400 invalid_request`: ```json { "error": { "code": "invalid_request", "message": "Petición inválida", "request_id": "0123456789abcdef0123456789abcdef", "details": { "fields": { "limit": "Entre 1 y 100" } }, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request" } } ``` `401 invalid_api_key`: ```json { "error": { "code": "invalid_api_key", "message": "Credencial inválida", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key" } } ``` `403 forbidden_scope`: ```json { "error": { "code": "forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0123456789abcdef0123456789abcdef", "details": { "required_scope": "payments:read" }, "retryable": false, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope" } } ``` `429 rate_limited`: ```json { "error": { "code": "rate_limited", "message": "Demasiadas peticiones", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": true, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited" } } ``` `500 internal_error`: ```json { "error": { "code": "internal_error", "message": "Error interno", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": true, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error" } } ``` `503 service_unavailable`: ```json { "error": { "code": "service_unavailable", "message": "Servicio no disponible", "request_id": "0123456789abcdef0123456789abcdef", "details": {}, "retryable": true, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable" } } ``` ## Reintentos Es una lectura: repetirla no tiene efecto. - `429 rate_limited`: Espera lo que indique `Retry-After` y repite. - `500 internal_error`: Repite con espera exponencial. - `503 service_unavailable`: Repite con espera exponencial. Respeta `Retry-After` si viene. Ver [Reintentos](/docs/recetas/reintentos/) y [Límites](/docs/limites/). ## Muestras **Variables de estas muestras: simulador público, sin cuenta** Define esto en tu terminal. Con estos valores las muestras corren tal cual contra el simulador público: ```bash export FITAL_API="https://widget.fital.xyz/explorar/v1" export FITAL_KEY="sk_test_sandbox_publica" ``` En la cuenta de prueba o en producción cambia la base, la llave y el secreto, y sustituye los `id` de ejemplo por los tuyos. Ver [Ambientes](/docs/ambientes/). ```bash curl -sS "$FITAL_API/payments" \ -H "Authorization: Bearer $FITAL_KEY" ``` ```js const r = await fetch(`${process.env.FITAL_API}/payments`, { headers: { Authorization: `Bearer ${process.env.FITAL_KEY}`, }, }); console.log(r.status, await r.json()); ``` ```python import json, os, urllib.error, urllib.request pet = urllib.request.Request(os.environ["FITAL_API"] + "/payments", method="GET", headers={"Authorization": "Bearer " + os.environ["FITAL_KEY"]}) try: with urllib.request.urlopen(pet) as r: print(r.status, json.load(r)) except urllib.error.HTTPError as e: print(e.code, e.read().decode()) ``` ```php true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('FITAL_KEY'), ], ]); echo curl_exec($c), "\n"; ``` ## Guías - [Conceptos](/docs/conceptos/) - [Paginación](/docs/paginacion/) - [Autenticación](/docs/autenticacion/) - [Conciliar](/docs/recetas/conciliar/) - [Pago masivo](/docs/recetas/pago-masivo/) - [Pago SPEI](/docs/recetas/pago-spei/)