Crear un cobro

Crea un cobro y devuelve la instrucción para quien paga. Exige Idempotency-Key y firma. Envía amount o destination_amount. 201 si quedó creado; 202 si aún no se confirma: repite con la misma clave.

Dato	Valor
Método y ruta	`POST /v1/collections`
Servidor	`https://widget.fital.xyz`
`operationId`	`createCollection`
Acceso	Llave con el scope `collections:write`
Firma de petición	Obligatoria en producción y en la cuenta de prueba. El simulador público no la valida. Ver Firma de petición
Idempotencia	Obligatoria, con `Idempotency-Key`. Ver Idempotencia

Envía amount, lo que paga tu cliente, o destination_amount, lo que quieres recibir. Al menos uno.
payer lleva los datos de quien paga, y se comprueba contra payer_fields de GET /v1/collection-methods. countrySymbol, en 2 letras, sólo si quien paga es de otro país que la moneda: si no, se deduce de la moneda.
202 significa que el alta aún no se confirma: instruction y expires_at llegan en null. Repite con la misma clave, o consulta el id.

Encabezados de la petición

Encabezado	Obligatorio	Descripción
`Authorization`	Sí	`Bearer` y tu llave.
`Content-Type`	Sí	`application/json`.
`Idempotency-Key`	Sí	Clave única de esta operación, de 8 a 200 caracteres. Repetirla con el mismo cuerpo devuelve la misma respuesta durante 7 días. Con otro cuerpo da `422 idempotency_key_reused`, también pasado ese plazo.
`X-Fital-Timestamp`	Sí	Hora Unix en segundos. Se acepta hasta 300 s de diferencia.
`X-Fital-Signature`	Sí	Firma `v1=` de la petición con el secreto de firma de la llave.
`X-Fital-Scenario`	No	Sólo simuladores: elige la respuesta que quieres practicar.

Cuerpo

Campo	Tipo	Obligatorio	Descripción
`amount`	texto	No	Monto que paga tu cliente. Envía éste o `destination_amount`.
`currency`	texto	Sí	Moneda del cobro.
`description`	texto	No	Concepto del cobro, hasta 140 caracteres imprimibles. Hasta 140 caracteres.
`destination_amount`	texto	No	Monto que quieres recibir. Envía éste o `amount`.
`expires_at`	texto	No	Vencimiento deseado. Tiene que ser futuro en un cobro `efectivo`, que sin este campo vence a los 3 días. ISO 8601 en UTC.
`external_ref`	texto	No	Tu referencia del cobro. Vuelve en el cobro y en sus eventos. Hasta 120 caracteres.
`metadata`	objeto	No	Hasta 20 pares clave y valor tuyos.
`method`	texto	Sí	Método de `GET /v1/collection-methods`. `efectivo`, disponible bajo solicitud a FITAL, cobra en tiendas de México, en MXN: se paga con una referencia y se envía `amount`, no `destination_amount`. Hasta 40 caracteres.
`payer`	objeto	No	Datos de quien paga. `payer_fields` de `GET /v1/collection-methods` dice qué pide cada método: sin un campo `required`, o con un valor fuera de `options`, la respuesta es `400 invalid_request` con el campo en `details.fields`, antes de crear nada. `countrySymbol`, en 2 letras, sólo si quien paga es de otro país que la moneda.
`quote_id`	texto	No	Cotización previa del cobro, si la tienes. Hasta 100 caracteres.

{
  "currency": "MXN",
  "method": "spei",
  "amount": "1250.00",
  "payer": {
    "firstName": "CLIENTE",
    "lastName": "FICTICIO",
    "email": "pagos@empresa-ejemplo.com"
  },
  "description": "Pedido 7731",
  "external_ref": "pedido-7731"
}

Respuestas correctas

201 Creado

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

202 Aceptado: el resultado final llega después

Misma forma que la respuesta anterior.

{
  "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.
`Idempotent-Replayed`	`true` si la respuesta repite una anterior con esa clave.
`Location`	Ruta del recurso, con `201` y `202`.
`Retry-After`	Segundos a esperar, con `429`, con `409 idempotency_in_progress` 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`	Falta `amount` o `destination_amount`, o algún campo no cumple el esquema. También sin un campo `required` de `payer_fields`, o con un valor fuera de `options`: `details.fields` lo nombra como `payer.<campo>`.	`false`
400	`idempotency_key_required`	Falta `Idempotency-Key`.	`false`
400	`idempotency_key_invalid`	La clave no mide entre 8 y 200 caracteres, o viene duplicada.	`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`
401	`invalid_signature`	Falta la firma, no coincide o tiene más de 5 minutos.	`false`
403	`account_restricted`	La cuenta tiene una restricción.	`false`
403	`not_enabled`	El método no está activado para tu empresa.	`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`
409	`collection_not_ready`	El cobro aún no se puede crear porque falta una revisión de tu cuenta.	`false`
409	`idempotency_in_progress`	Una petición anterior con esa clave sigue en curso. Llega con `Retry-After`.	`true`
413	`invalid_request`	El cuerpo supera 64 KB.	`false`
422	`rail_unavailable`	El país del método no está disponible por ahora.	`true`
422	`in_review`	Una revisión de tu cuenta frena la operación.	`true`
422	`method_unavailable`	El método no está disponible.	`false`
422	`amount_out_of_range`	El monto está fuera del rango del método.	`false`
422	`collection_rejected`	El cobro se rechazó.	`false`
422	`idempotency_key_reused`	Usaste esa clave con otro cuerpo, también pasados 7 días.	`false`
429	`rate_limited`	Superaste un límite de peticiones. Llega con `Retry-After`.	`true`
429	`sandbox_limit` (sólo cuenta de prueba)	Alcanzaste 100 pagos y cobros de hoy.	`false`
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": {
        "amount": "Valor inválido"
      }
    },
    "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 account_restricted:

{
  "error": {
    "code": "account_restricted",
    "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted"
  }
}

409 collection_not_ready:

{
  "error": {
    "code": "collection_not_ready",
    "message": "Operación rechazada",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#collection_not_ready"
  }
}

413 invalid_request:

{
  "error": {
    "code": "invalid_request",
    "message": "Petición inválida",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": false,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request"
  }
}

422 rail_unavailable:

{
  "error": {
    "code": "rail_unavailable",
    "message": "Operación rechazada",
    "request_id": "0123456789abcdef0123456789abcdef",
    "details": {},
    "retryable": true,
    "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_unavailable"
  }
}

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

Ante un timeout, repite con la misma clave. Un 400 por payer no crea nada, pero la clave conserva ese cuerpo: el cuerpo corregido necesita otra Idempotency-Key. Con la misma responde 422 idempotency_key_reused.

409 idempotency_in_progress: Espera Retry-After y repite con la misma clave.
422 rail_unavailable: Repite más tarde.
422 in_review: Mira retryable. Con true, repite con la misma clave cuando la revisión se levante. Con false, el rechazo quedó registrado y esa clave lo repite: usa una clave nueva tras la revisión.
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"
export FITAL_SIGNING_SECRET="secreto_de_firma_de_prueba_publico"

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

CUERPO='{"currency":"MXN","method":"spei","amount":"1250.00","payer":{"firstName":"CLIENTE","lastName":"FICTICIO","email":"pagos@empresa-ejemplo.com"},"description":"Pedido 7731","external_ref":"pedido-7731"}'
CLAVE="ejemplo-crear-cobro"
TS=$(date +%s)
HASH=$(printf '%s' "$CUERPO" | openssl dgst -sha256 -r | cut -d' ' -f1)
FIRMA=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" POST /v1/collections "$HASH" "$CLAVE" \
  | openssl dgst -sha256 -hmac "$FITAL_SIGNING_SECRET" -r | cut -d' ' -f1)
curl -sS -X POST "$FITAL_API/collections" \
  -H "Authorization: Bearer $FITAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CLAVE" \
  -H "X-Fital-Timestamp: $TS" \
  -H "X-Fital-Signature: v1=$FIRMA" \
  -d "$CUERPO"

Guías

Ver esta página en Markdown

Encabezados de la peticiónCopiar enlace

CuerpoCopiar enlace

Respuestas correctasCopiar enlace

201 CreadoCopiar enlace

Valores de instruction.typeCopiar enlace

Valores de statusCopiar enlace

202 Aceptado: el resultado final llega despuésCopiar enlace

Encabezados de la respuestaCopiar enlace

ErroresCopiar enlace

Ejemplos de errorCopiar enlace

ReintentosCopiar enlace

MuestrasCopiar enlace

GuíasCopiar enlace

En esta página