Un cobro

Un cobro de tu empresa, con su estado actual. paid y expired no vuelven atrás.

Dato	Valor
Método y ruta	`GET /v1/collections/{id}`
Servidor	`https://widget.fital.xyz`
`operationId`	`getCollection`
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
`id`	ruta	texto	Sí	Identificador del recurso. Hasta 250 caracteres.

Respuestas correctas

200 Correcto

Campo	Tipo	Obligatorio	Descripción
`amount`	texto o `null`	Sí	Monto que paga tu cliente.
`created_at`	texto o `null`	Sí	Fecha de creación. ISO 8601 en UTC.
`currency`	texto o `null`	Sí	Moneda del cobro.
`destination_amount`	texto o `null`	Sí	Monto que recibes.
`expires_at`	texto o `null`	Sí	Vencimiento del cobro. ISO 8601 en UTC.
`external_ref`	texto o `null`	Sí	Tu referencia.
`id`	texto	Sí	Identificador del cobro, con prefijo `col_`.
`instruction`	objeto o `null`	Sí	Cómo pagar. null mientras no esté lista.
`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.
`instruction.value`	texto o `null`	Sí	Dato que usa quien paga.
`metadata`	objeto	Sí	Los pares que enviaste al crear el cobro.
`method`	texto o `null`	Sí	Método del cobro.
`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.

Valores de `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 `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.

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

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

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

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

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

Instrucción LINK: value se abre para pagar:

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

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

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

Pagado:

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

Venció sin pago:

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

Alta sin confirmar:

{
  "amount": "1250.00",
  "created_at": "2026-11-04T18:00:00.000Z",
  "currency": "MXN",
  "destination_amount": null,
  "expires_at": null,
  "external_ref": "pedido-7731",
  "id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW",
  "instruction": null,
  "metadata": {},
  "method": "spei",
  "status": "processing"
}

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`
403	`kyb_required`	La empresa no tiene KYB aprobado o aún no está inscrita.	`false`
403	`account_not_active`	La cuenta no está activa.	`false`
404	`not_found`	El cobro no existe o es de otra empresa.	`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"
  }
}

404 not_found:

{
  "error": {
    "code": "not_found",
    "message": "No encontrado",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found"
  }
}

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-consultar-cobro.sh

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

Guías

Ver esta página en Markdown

Encabezados de la peticiónCopiar enlace

ParámetrosCopiar enlace

Respuestas correctasCopiar enlace

200 CorrectoCopiar enlace

Valores de instruction.typeCopiar enlace

Valores de statusCopiar enlace

Encabezados de la respuestaCopiar enlace

ErroresCopiar enlace

Ejemplos de errorCopiar enlace

ReintentosCopiar enlace

MuestrasCopiar enlace

GuíasCopiar enlace

En esta página