Cobros, con su último estado conocido

Cobros creados por esta API, con el último estado conocido, del más nuevo al más viejo.

Dato	Valor
Método y ruta	`GET /v1/collections`
Servidor	`https://widget.fital.xyz`
`operationId`	`listCollections`
Acceso	Llave con el scope `collections:read`
Firma de petición	No aplica
Idempotencia	No aplica

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 que paga tu cliente.
`data[].created_at`	texto o `null`	Sí	Fecha de creación. ISO 8601 en UTC.
`data[].currency`	texto o `null`	Sí	Moneda del cobro.
`data[].destination_amount`	texto o `null`	Sí	Monto que recibes.
`data[].expires_at`	texto o `null`	Sí	Vencimiento del cobro. ISO 8601 en UTC.
`data[].external_ref`	texto o `null`	Sí	Tu referencia.
`data[].id`	texto	Sí	Identificador del cobro, con prefijo `col_`.
`data[].instruction`	objeto o `null`	Sí	Cómo pagar. null mientras no esté lista.
`data[].instruction.type`	texto o `null`	Sí	Tipo de instrucción. Depende del método: trata la lista como extensible. `LINK`: `value` es una dirección que se abre para pagar. `QR`: `value` se muestra o se copia, como un QR o un texto de pago. `REFERENCE`: `value` es la referencia que quien paga da en la tienda, en un cobro `efectivo`. `clabe`: `value` es una CLABE. Sólo en sandbox.
`data[].instruction.value`	texto o `null`	Sí	Dato que usa quien paga.
`data[].metadata`	objeto	Sí	Los pares que enviaste al crear el cobro.
`data[].method`	texto o `null`	Sí	Método del cobro.
`data[].status`	texto	Sí	Estado del cobro. `processing`: El alta aún no se confirma. `pending`: Espera el pago. `paid`: Pagado. No vuelve atrás. En `efectivo`, la tienda ya confirmó el pago y el abono a tu cuenta llega después. `expired`: Venció sin pago. No vuelve atrás. `failed`: No se pudo crear o completar.
`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[].instruction.type`

Valor	Significado
`LINK`	`value` es una dirección que se abre para pagar.
`QR`	`value` se muestra o se copia, como un QR o un texto de pago.
`REFERENCE`	`value` es la referencia que quien paga da en la tienda, en un cobro `efectivo`.
`clabe`	`value` es una CLABE. Sólo en la cuenta de prueba.

Depende del método. Trata la lista como extensible.

Valores de `data[].status`

Valor	Significado
`processing`	El alta aún no se confirma.
`pending`	Espera el pago.
`paid`	Pagado. No vuelve atrás.
`expired`	Venció sin pago. No vuelve atrás.
`failed`	No se pudo crear o completar.

{
  "data": [
    {
      "amount": "1250.00",
      "created_at": "2026-11-04T18:00:00.000Z",
      "currency": "MXN",
      "destination_amount": null,
      "expires_at": "2026-11-05T18:00:00.000Z",
      "external_ref": "pedido-7731",
      "id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW",
      "instruction": {
        "type": "clabe",
        "value": "999180000000000022"
      },
      "metadata": {},
      "method": "spei",
      "status": "pending"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Instrucción clabe: sólo en sandbox.:

{
  "data": [
    {
      "amount": "1250.00",
      "created_at": "2026-11-04T18:00:00.000Z",
      "currency": "MXN",
      "destination_amount": null,
      "expires_at": "2026-11-05T18:00:00.000Z",
      "external_ref": "pedido-7731",
      "id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW",
      "instruction": {
        "type": "clabe",
        "value": "999180000000000022"
      },
      "metadata": {},
      "method": "spei",
      "status": "pending"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Instrucción REFERENCE: quien paga da value en la tienda.:

{
  "data": [
    {
      "amount": "1250.00",
      "created_at": "2026-11-04T18:00:00.000Z",
      "currency": "MXN",
      "destination_amount": null,
      "expires_at": "2026-11-05T18:00:00.000Z",
      "external_ref": "pedido-7731",
      "id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW",
      "instruction": {
        "type": "REFERENCE",
        "value": "999000000000000000000000000022"
      },
      "metadata": {},
      "method": "efectivo",
      "status": "pending"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Instrucción LINK: value se abre para pagar.:

{
  "data": [
    {
      "amount": "1250.00",
      "created_at": "2026-11-04T18:00:00.000Z",
      "currency": "MXN",
      "destination_amount": null,
      "expires_at": "2026-11-05T18:00:00.000Z",
      "external_ref": "pedido-7731",
      "id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW",
      "instruction": {
        "type": "LINK",
        "value": "https://empresa-ejemplo.com/pagar/4hQvN8sL"
      },
      "metadata": {},
      "method": "spei",
      "status": "pending"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Instrucción QR: value se muestra o se copia.:

{
  "data": [
    {
      "amount": "1250.00",
      "created_at": "2026-11-04T18:00:00.000Z",
      "currency": "MXN",
      "destination_amount": null,
      "expires_at": "2026-11-05T18:00:00.000Z",
      "external_ref": "pedido-7731",
      "id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW",
      "instruction": {
        "type": "QR",
        "value": "00020101021226580014ejemplo0212FICTICIO12345204000053034845802MX"
      },
      "metadata": {},
      "method": "spei",
      "status": "pending"
    }
  ],
  "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: error.code, message, request_id, details, retryable y docs_url. Decide por code.

HTTP	Código	Cuándo sale	`retryable`
400	`invalid_request`	Algún parámetro o campo no cumple el esquema. Mira `details.fields`.	`false`
401	`invalid_api_key`	La llave falta, está mal formada, venció o fue revocada, o la empresa está suspendida.	`false`
401	`wrong_environment`	La llave es de otro ambiente.	`false`
403	`forbidden_scope`	La llave no tiene el scope de esta operación. `details.required_scope` lo nombra.	`false`
403	`ip_not_allowed`	La IP de origen no está activa en la lista de esa llave.	`false`
429	`rate_limited`	Superaste un límite de peticiones. Llega con `Retry-After`.	`true`
500	`internal_error`	Fallo nuestro. El resultado de la petición no se conoce.	`true`
503	`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:

{
  "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:

{
  "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:

{
  "error": {
    "code": "forbidden_scope",
    "message": "La llave no tiene permiso para esta operación",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {
      "required_scope": "collections:read"
    },
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope"
  }
}

429 rate_limited:

{
  "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:

{
  "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:

{
  "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 y Límites.

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:

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.

op-listar-cobros.sh

curl -sS "$FITAL_API/collections" \
  -H "Authorization: Bearer $FITAL_KEY"

Guías

Ver esta página en Markdown

Cobros, con su último estado conocido

Encabezados de la peticiónCopiar enlace

ParámetrosCopiar enlace

Respuestas correctasCopiar enlace

200 CorrectoCopiar enlace

Valores de data[].instruction.typeCopiar enlace

Valores de data[].statusCopiar enlace

Encabezados de la respuestaCopiar enlace

ErroresCopiar enlace

Ejemplos de errorCopiar enlace

ReintentosCopiar enlace

MuestrasCopiar enlace

GuíasCopiar enlace

En esta página