# Crear un cobro POST /v1/collections 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](/docs/autenticacion/#firma-de-petición) | | Idempotencia | **Obligatoria**, con `Idempotency-Key`. Ver [Idempotencia](/docs/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`](/docs/operaciones/listar-metodos-de-cobro/). `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. | ```json { "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. | ```json { "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.: ```json { "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.: ```json { "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: ```json { "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: ```json { "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. ```json { "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](/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) | 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.`. | `false` | | 400 | [`idempotency_key_required`](/docs/errores/#idempotency_key_required) | Falta `Idempotency-Key`. | `false` | | 400 | [`idempotency_key_invalid`](/docs/errores/#idempotency_key_invalid) | La clave no mide entre 8 y 200 caracteres, o viene duplicada. | `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` | | 401 | [`invalid_signature`](/docs/errores/#invalid_signature) | Falta la firma, no coincide o tiene más de 5 minutos. | `false` | | 403 | [`account_restricted`](/docs/errores/#account_restricted) | La cuenta tiene una restricción. | `false` | | 403 | [`not_enabled`](/docs/errores/#not_enabled) | El método no está activado para tu empresa. | `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` | | 403 | [`kyb_required`](/docs/errores/#kyb_required) | La empresa no tiene KYB aprobado o aún no está inscrita. | `false` | | 403 | [`account_not_active`](/docs/errores/#account_not_active) | La cuenta no está activa. | `false` | | 409 | [`collection_not_ready`](/docs/errores/#collection_not_ready) | El cobro aún no se puede crear porque falta una revisión de tu cuenta. | `false` | | 409 | [`idempotency_in_progress`](/docs/errores/#idempotency_in_progress) | Una petición anterior con esa clave sigue en curso. Llega con `Retry-After`. | `true` | | 413 | [`invalid_request`](/docs/errores/#invalid_request) | El cuerpo supera 64 KB. | `false` | | 422 | [`rail_unavailable`](/docs/errores/#rail_unavailable) | El país del método no está disponible por ahora. | `true` | | 422 | [`in_review`](/docs/errores/#in_review) | Una revisión de tu cuenta frena la operación. | `true` | | 422 | [`method_unavailable`](/docs/errores/#method_unavailable) | El método no está disponible. | `false` | | 422 | [`amount_out_of_range`](/docs/errores/#amount_out_of_range) | El monto está fuera del rango del método. | `false` | | 422 | [`collection_rejected`](/docs/errores/#collection_rejected) | El cobro se rechazó. | `false` | | 422 | [`idempotency_key_reused`](/docs/errores/#idempotency_key_reused) | Usaste esa clave con otro cuerpo, también pasados 7 días. | `false` | | 429 | [`rate_limited`](/docs/errores/#rate_limited) | Superaste un límite de peticiones. Llega con `Retry-After`. | `true` | | 429 | [`sandbox_limit`](/docs/errores/#sandbox_limit) (sólo cuenta de prueba) | Alcanzaste 100 pagos y cobros de hoy. | `false` | | 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": { "amount": "Valor inválido" } }, "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 account_restricted`: ```json { "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`: ```json { "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`: ```json { "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`: ```json { "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`: ```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 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](/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" 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](/docs/ambientes/). ```bash 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" ``` ```js import { createHash, createHmac } from 'node:crypto'; const cuerpo = JSON.stringify({"currency":"MXN","method":"spei","amount":"1250.00","payer":{"firstName":"CLIENTE","lastName":"FICTICIO","email":"pagos@empresa-ejemplo.com"},"description":"Pedido 7731","external_ref":"pedido-7731"}); const clave = 'ejemplo-crear-cobro'; const ts = String(Math.floor(Date.now() / 1000)); const hash = createHash('sha256').update(cuerpo).digest('hex'); const firma = createHmac('sha256', process.env.FITAL_SIGNING_SECRET) .update([ts, 'POST', '/v1/collections', hash, clave].join('\n')).digest('hex'); const r = await fetch(`${process.env.FITAL_API}/collections`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.FITAL_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': clave, 'X-Fital-Timestamp': ts, 'X-Fital-Signature': `v1=${firma}`, }, body: cuerpo, }); console.log(r.status, await r.json()); ``` ```python import hashlib, hmac, json, os, time, urllib.error, urllib.request cuerpo = json.dumps({"currency":"MXN","method":"spei","amount":"1250.00","payer":{"firstName":"CLIENTE","lastName":"FICTICIO","email":"pagos@empresa-ejemplo.com"},"description":"Pedido 7731","external_ref":"pedido-7731"}).encode() clave = "ejemplo-crear-cobro" ts = str(int(time.time())) canon = "\n".join([ts, "POST", "/v1/collections", hashlib.sha256(cuerpo).hexdigest(), clave]) firma = hmac.new(os.environ["FITAL_SIGNING_SECRET"].encode(), canon.encode(), hashlib.sha256).hexdigest() pet = urllib.request.Request(os.environ["FITAL_API"] + "/collections", method="POST", data=cuerpo, headers={"Authorization": "Bearer " + os.environ["FITAL_KEY"], "Content-Type": "application/json", "Idempotency-Key": clave, "X-Fital-Timestamp": ts, "X-Fital-Signature": "v1=" + firma}) 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_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('FITAL_KEY'), 'Content-Type: application/json', 'Idempotency-Key: ' . $clave, 'X-Fital-Timestamp: ' . $ts, 'X-Fital-Signature: v1=' . $firma, ], CURLOPT_POSTFIELDS => $cuerpo, ]); echo curl_exec($c), "\n"; ``` ## Guías - [Cobros](/docs/recetas/cobros/) - [Cobertura](/docs/cobertura/) - [Autenticación](/docs/autenticacion/) - [Idempotencia](/docs/idempotencia/) - [Lista de migración](/docs/migracion/)