{ "components": { "parameters": {}, "schemas": { "Balance": { "additionalProperties": false, "properties": { "available": { "description": "Saldo disponible en esa moneda, como decimal en texto.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "currency": { "description": "Moneda del saldo.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" } }, "required": [ "currency", "available" ], "type": "object" }, "Beneficiary": { "additionalProperties": false, "properties": { "country": { "description": "País de la cuenta, si se conoce.", "type": [ "string", "null" ] }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Identificador del beneficiario, con prefijo `ben_`.", "example": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "pattern": "^ben_[A-Za-z0-9]{1,76}$", "type": "string" }, "rail": { "description": "Riel del beneficiario. null mientras el alta no se confirme. `mxn_spei`: SPEI, en México. `usd_ach`: ACH, en Estados Unidos. `usd_wire`: Wire, en Estados Unidos. `eur_sepa`: SEPA, en la zona euro. `gbp_fps`: Faster Payments, en Reino Unido. `cop`: Bre-B, en Colombia. `pix`: PIX, en Brasil. `latam`: Transferencia local en otros países de América Latina.", "type": [ "string", "null" ] }, "status": { "description": "Sólo con `approved` se le puede pagar. La aprobación se hace en el panel. `processing`: El alta sigue en curso. `pending_approval`: Falta aprobarlo en el panel. `approved`: Ya se le puede pagar. `rejected`: No se aprobó. `deleted`: Se dio de baja.", "enum": [ "processing", "pending_approval", "approved", "rejected", "deleted" ], "type": "string" } }, "required": [ "id", "rail", "country", "status", "created_at" ], "type": "object" }, "BeneficiaryCreate": { "oneOf": [ { "additionalProperties": false, "properties": { "clabe": { "description": "CLABE de 18 dígitos.", "pattern": "^\\d{18}$", "type": "string" }, "holder_name": { "description": "Titular de la cuenta destino.", "maxLength": 140, "minLength": 1, "type": "string" }, "rail": { "description": "Riel de pago. Decide qué campos se piden. `mxn_spei`: SPEI, en México.", "enum": [ "mxn_spei" ], "type": "string" } }, "required": [ "rail", "holder_name", "clabe" ], "type": "object" }, { "additionalProperties": false, "properties": { "account_number": { "description": "Número de cuenta, de 4 a 17 dígitos.", "pattern": "^\\d{4,17}$", "type": "string" }, "account_type": { "description": "Tipo de cuenta. `checking`: Cuenta de cheques o corriente. `savings`: Cuenta de ahorro.", "enum": [ "checking", "savings" ], "type": "string" }, "address": { "additionalProperties": false, "description": "Domicilio del titular.", "properties": { "city": { "description": "Ciudad.", "maxLength": 100, "minLength": 1, "type": "string" }, "country": { "description": "País, en código de 3 letras.", "maxLength": 3, "minLength": 3, "type": "string" }, "postal_code": { "description": "Código postal.", "maxLength": 20, "minLength": 1, "type": "string" }, "state": { "description": "Estado o provincia.", "maxLength": 100, "minLength": 1, "type": "string" }, "street_line_1": { "description": "Calle y número.", "maxLength": 35, "minLength": 4, "type": "string" } }, "required": [ "street_line_1", "city", "state", "postal_code", "country" ], "type": "object" }, "holder_name": { "description": "Titular de la cuenta destino.", "maxLength": 140, "minLength": 1, "type": "string" }, "rail": { "description": "Riel de pago. Decide qué campos se piden. `usd_ach`: ACH, en Estados Unidos.", "enum": [ "usd_ach" ], "type": "string" }, "routing_number": { "description": "Número de ruta, 9 dígitos.", "pattern": "^\\d{9}$", "type": "string" } }, "required": [ "rail", "holder_name", "routing_number", "account_number", "account_type", "address" ], "type": "object" }, { "additionalProperties": false, "properties": { "account_number": { "description": "Número de cuenta, de 4 a 17 dígitos.", "pattern": "^\\d{4,17}$", "type": "string" }, "account_type": { "description": "Tipo de cuenta. `checking`: Cuenta de cheques o corriente. `savings`: Cuenta de ahorro.", "enum": [ "checking", "savings" ], "type": "string" }, "address": { "additionalProperties": false, "description": "Domicilio del titular.", "properties": { "city": { "description": "Ciudad.", "maxLength": 100, "minLength": 1, "type": "string" }, "country": { "description": "País, en código de 3 letras.", "maxLength": 3, "minLength": 3, "type": "string" }, "postal_code": { "description": "Código postal.", "maxLength": 20, "minLength": 1, "type": "string" }, "state": { "description": "Estado o provincia.", "maxLength": 100, "minLength": 1, "type": "string" }, "street_line_1": { "description": "Calle y número.", "maxLength": 35, "minLength": 4, "type": "string" } }, "required": [ "street_line_1", "city", "state", "postal_code", "country" ], "type": "object" }, "holder_name": { "description": "Titular de la cuenta destino.", "maxLength": 140, "minLength": 1, "type": "string" }, "rail": { "description": "Riel de pago. Decide qué campos se piden. `usd_wire`: Wire, en Estados Unidos.", "enum": [ "usd_wire" ], "type": "string" }, "routing_number": { "description": "Número de ruta, 9 dígitos.", "pattern": "^\\d{9}$", "type": "string" } }, "required": [ "rail", "holder_name", "routing_number", "account_number", "account_type", "address" ], "type": "object" }, { "additionalProperties": false, "properties": { "bic": { "description": "Código BIC del banco.", "maxLength": 11, "minLength": 8, "type": "string" }, "holder_name": { "description": "Titular de la cuenta destino.", "maxLength": 140, "minLength": 1, "type": "string" }, "iban": { "description": "IBAN de la cuenta.", "maxLength": 34, "minLength": 15, "type": "string" }, "iban_country": { "description": "País del IBAN, en código de 3 letras.", "maxLength": 3, "minLength": 3, "type": "string" }, "rail": { "description": "Riel de pago. Decide qué campos se piden. `eur_sepa`: SEPA, en la zona euro.", "enum": [ "eur_sepa" ], "type": "string" } }, "required": [ "rail", "holder_name", "iban", "bic", "iban_country" ], "type": "object" }, { "additionalProperties": false, "properties": { "account_number": { "description": "Número de cuenta, 8 dígitos.", "pattern": "^\\d{8}$", "type": "string" }, "holder_name": { "description": "Titular de la cuenta destino.", "maxLength": 140, "minLength": 1, "type": "string" }, "rail": { "description": "Riel de pago. Decide qué campos se piden. `gbp_fps`: Faster Payments, en Reino Unido.", "enum": [ "gbp_fps" ], "type": "string" }, "sort_code": { "description": "Sort code, 6 dígitos.", "pattern": "^\\d{6}$", "type": "string" } }, "required": [ "rail", "holder_name", "account_number", "sort_code" ], "type": "object" }, { "additionalProperties": false, "properties": { "bre_b_key": { "description": "Llave Bre-B del titular.", "maxLength": 100, "minLength": 1, "type": "string" }, "holder_name": { "description": "Titular de la cuenta destino.", "maxLength": 140, "minLength": 1, "type": "string" }, "rail": { "description": "Riel de pago. Decide qué campos se piden. `cop`: Bre-B, en Colombia.", "enum": [ "cop" ], "type": "string" } }, "required": [ "rail", "holder_name", "bre_b_key" ], "type": "object" }, { "additionalProperties": false, "properties": { "document": { "description": "Documento del titular.", "maxLength": 20, "type": "string" }, "holder_name": { "description": "Titular de la cuenta destino.", "maxLength": 140, "minLength": 1, "type": "string" }, "pix_key": { "description": "Llave PIX del titular.", "maxLength": 100, "minLength": 1, "type": "string" }, "rail": { "description": "Riel de pago. Decide qué campos se piden. `pix`: PIX, en Brasil.", "enum": [ "pix" ], "type": "string" } }, "required": [ "rail", "holder_name", "pix_key" ], "type": "object" }, { "additionalProperties": false, "properties": { "account_number": { "description": "Número de cuenta. `GET /v1/latam/countries` dice qué pide cada país.", "maxLength": 40, "minLength": 4, "type": "string" }, "account_type": { "description": "Tipo de cuenta, si el país lo pide. `GET /v1/latam/countries` dice qué pide cada país. `checking`: Cuenta de cheques o corriente. `savings`: Cuenta de ahorro.", "enum": [ "checking", "savings" ], "type": "string" }, "country": { "description": "País de la cuenta, en código de 2 letras.", "maxLength": 2, "minLength": 2, "type": "string" }, "currency": { "description": "Moneda de la cuenta, en código de 3 letras.", "maxLength": 3, "minLength": 3, "type": "string" }, "document": { "description": "Documento del titular, si el país lo pide.", "maxLength": 30, "type": "string" }, "document_type": { "description": "Tipo de documento del titular, si el país lo pide. `GET /v1/latam/countries` dice qué pide cada país.", "maxLength": 20, "type": "string" }, "entity": { "description": "Banco o entidad, si el país lo pide. Los valores salen de `GET /v1/latam/countries/{country}/entities`.", "maxLength": 40, "type": "string" }, "holder_name": { "description": "Titular de la cuenta destino.", "maxLength": 140, "minLength": 1, "type": "string" }, "rail": { "description": "Riel de pago. Decide qué campos se piden. `latam`: Transferencia local en otros países de América Latina.", "enum": [ "latam" ], "type": "string" } }, "required": [ "rail", "holder_name", "country", "currency", "account_number" ], "type": "object" } ] }, "Collection": { "additionalProperties": false, "properties": { "amount": { "description": "Monto que paga tu cliente.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Moneda del cobro.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "destination_amount": { "description": "Monto que recibes.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "expires_at": { "description": "Vencimiento del cobro.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "external_ref": { "description": "Tu referencia.", "type": [ "string", "null" ] }, "id": { "description": "Identificador del cobro, con prefijo `col_`.", "type": "string" }, "instruction": { "additionalProperties": false, "description": "Cómo pagar. null mientras no esté lista.", "properties": { "type": { "description": "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.", "type": [ "string", "null" ] }, "value": { "description": "Dato que usa quien paga.", "type": [ "string", "null" ] } }, "required": [ "type", "value" ], "type": [ "object", "null" ] }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Los pares que enviaste al crear el cobro.", "type": "object" }, "method": { "description": "Método del cobro.", "type": [ "string", "null" ] }, "status": { "description": "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.", "enum": [ "processing", "pending", "paid", "expired", "failed" ], "type": "string" } }, "required": [ "id", "status", "currency", "method", "amount", "destination_amount", "instruction", "expires_at", "external_ref", "metadata", "created_at" ], "type": "object" }, "CollectionCreate": { "additionalProperties": false, "properties": { "amount": { "description": "Monto que paga tu cliente. Envía éste o `destination_amount`.", "example": "1250.00", "pattern": "^([1-9]\\d{0,14}(\\.\\d{1,2})?|0\\.([1-9]\\d?|0[1-9]))$", "type": "string" }, "currency": { "description": "Moneda del cobro.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" }, "description": { "description": "Concepto del cobro, hasta 140 caracteres imprimibles.", "maxLength": 140, "pattern": "^[^\\p{C}\\p{Zl}\\p{Zp}]*$", "type": "string" }, "destination_amount": { "description": "Monto que quieres recibir. Envía éste o `amount`.", "example": "1250.00", "pattern": "^([1-9]\\d{0,14}(\\.\\d{1,2})?|0\\.([1-9]\\d?|0[1-9]))$", "type": "string" }, "expires_at": { "description": "Vencimiento deseado. Tiene que ser futuro en un cobro `efectivo`, que sin este campo vence a los 3 días.", "format": "date-time", "type": "string" }, "external_ref": { "description": "Tu referencia del cobro. Vuelve en el cobro y en sus eventos.", "maxLength": 120, "pattern": "^[^\\p{C}\\p{Zl}\\p{Zp}]*$", "type": "string" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Hasta 20 pares clave y valor tuyos.", "type": "object" }, "method": { "description": "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`.", "maxLength": 40, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "type": "string" }, "payer": { "additionalProperties": { "maxLength": 200, "type": "string" }, "description": "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.", "type": "object" }, "quote_id": { "description": "Cotización previa del cobro, si la tienes.", "maxLength": 100, "type": "string" } }, "required": [ "currency", "method" ], "type": "object" }, "CollectionEstimate": { "additionalProperties": false, "properties": { "amount": { "description": "Monto estimado.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "currency": { "description": "Moneda del monto.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "exchange_rate": { "description": "Tipo de cambio aplicado, si hay conversión.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "expires_at": { "description": "Vigencia de la estimación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "fee": { "description": "Comisión.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "fee_currency": { "description": "Moneda de la comisión.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "indicative": { "description": "Siempre true: es una estimación.", "type": "boolean" }, "max_amount": { "description": "Monto máximo del método.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "min_amount": { "description": "Monto mínimo del método.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "plan_fee_pct": { "description": "Comisión de tu plan, en porcentaje.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "receive_amount": { "description": "Lo que recibirías. null en `efectivo`: se fija al conciliar el pago.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "receive_currency": { "description": "Moneda de lo que recibirías.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "total_cost_pct": { "description": "Costo total, en porcentaje.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] } }, "required": [ "amount", "currency", "receive_amount", "receive_currency", "fee", "fee_currency", "plan_fee_pct", "exchange_rate", "indicative", "expires_at", "min_amount", "max_amount", "total_cost_pct" ], "type": "object" }, "CollectionEstimateRequest": { "additionalProperties": false, "properties": { "amount": { "description": "Monto a estimar.", "example": "1250.00", "pattern": "^([1-9]\\d{0,14}(\\.\\d{1,2})?|0\\.([1-9]\\d?|0[1-9]))$", "type": "string" }, "currency": { "description": "Moneda del cobro.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" }, "method": { "description": "Método de cobro.", "maxLength": 40, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "type": "string" } }, "required": [ "currency", "method", "amount" ], "type": "object" }, "CollectionMethod": { "additionalProperties": false, "properties": { "available": { "description": "true si se puede usar ahora.", "type": "boolean" }, "country": { "description": "País del método.", "type": [ "string", "null" ] }, "currency": { "description": "Moneda del método.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "max_amount": { "description": "Monto máximo.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "method": { "description": "Nombre a usar en `method`.", "type": [ "string", "null" ] }, "min_amount": { "description": "Monto mínimo.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "payer_fields": { "description": "Lo que el método pide en `payer` al crear el cobro.", "items": { "$ref": "#/components/schemas/CollectionPayerField" }, "type": "array" } }, "required": [ "country", "currency", "method", "available", "min_amount", "max_amount", "payer_fields" ], "type": "object" }, "CollectionPayerField": { "additionalProperties": false, "properties": { "name": { "description": "Clave dentro de `payer`. `firstName`: Nombre, o razón social. `lastName`: Apellido. `email`: Correo. `phone`: Teléfono con su prefijo internacional. `documentType`: Tipo de documento. `documentNumber`: Número de documento.", "type": "string" }, "options": { "description": "Valores admitidos. null si es texto libre.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "phone_prefix": { "description": "Prefijo del país, como `+57`. null si no aplica.", "type": [ "string", "null" ] }, "required": { "description": "true si el cobro se rechaza sin este dato.", "type": "boolean" } }, "required": [ "name", "required", "options", "phone_prefix" ], "type": "object" }, "Deposit": { "additionalProperties": false, "properties": { "amount": { "description": "Monto recibido.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "concept": { "description": "Concepto que escribió quien pagó.", "type": [ "string", "null" ] }, "credited_amount": { "description": "Monto acreditado a tu saldo.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "credited_currency": { "description": "Moneda acreditada.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "currency": { "description": "Moneda recibida.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "id": { "description": "Identificador del depósito, con prefijo `dpt_`.", "type": "string" }, "payer": { "$ref": "#/components/schemas/Payer", "description": "Quién pagó. null si no hay datos legibles: nunca se inventa." }, "receipt_url": { "description": "Enlace https al comprobante, si existe.", "type": [ "string", "null" ] }, "received_at": { "description": "Fecha del depósito.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "reference": { "description": "Referencia del depósito.", "type": [ "string", "null" ] }, "status": { "description": "Estado del depósito. `in_review`: El depósito está en revisión. Aún no es dinero disponible. `received`: El dinero ya está acreditado. `returned`: El depósito se devolvió.", "enum": [ "in_review", "received", "returned" ], "type": "string" }, "tracking_key": { "description": "Clave de rastreo del banco.", "type": [ "string", "null" ] } }, "required": [ "id", "status", "amount", "currency", "credited_amount", "credited_currency", "received_at", "reference", "concept", "tracking_key", "receipt_url", "payer" ], "type": "object" }, "DepositAddress": { "additionalProperties": false, "properties": { "address": { "description": "Dirección donde depositar. null mientras esté en `processing`.", "type": [ "string", "null" ] }, "chain": { "description": "Red de la dirección, en minúsculas.", "type": [ "string", "null" ] }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Token que acepta, en mayúsculas.", "type": [ "string", "null" ] }, "id": { "description": "Identificador de la dirección, con prefijo `dep_`.", "type": "string" }, "status": { "description": "Estado de la dirección. `processing`: El alta aún no se confirma y los demás campos llegan en null. `active`: Ya recibe depósitos.", "enum": [ "processing", "active" ], "type": "string" }, "warning": { "description": "Advertencia de uso. Muéstrala a quien vaya a depositar: dice también si en esa red un depósito rechazado no regresa automáticamente.", "type": [ "string", "null" ] } }, "required": [ "id", "status", "address", "chain", "currency", "warning", "created_at" ], "type": "object" }, "DepositAddressCreate": { "additionalProperties": false, "properties": { "chain": { "description": "Red de la dirección, por ejemplo `polygon`. No distingue mayúsculas.", "maxLength": 30, "minLength": 1, "type": "string" }, "currency": { "description": "Token que recibirá, por ejemplo `USDC`. No distingue mayúsculas.", "maxLength": 10, "minLength": 1, "type": "string" } }, "required": [ "chain", "currency" ], "type": "object" }, "EgressIps": { "additionalProperties": false, "properties": { "addresses": { "description": "Direcciones vigentes o anunciadas.", "items": { "additionalProperties": false, "properties": { "active_from": { "description": "Desde cuándo se usa.", "type": [ "string", "null" ] }, "ip": { "description": "Dirección IP de salida.", "type": "string" }, "retiring_at": { "description": "Cuándo deja de usarse. null si no tiene fecha de retiro.", "type": [ "string", "null" ] } }, "required": [ "ip", "active_from", "retiring_at" ], "type": "object" }, "type": "array" }, "note": { "description": "Recordatorio: autoriza por firma, no sólo por IP.", "type": "string" } }, "required": [ "addresses", "note" ], "type": "object" }, "Error": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "description": "Detalle del error.", "properties": { "code": { "description": "Código estable del catálogo de errores. Es lo que tu sistema debe comparar.", "type": "string" }, "details": { "additionalProperties": {}, "description": "Datos del error. En `invalid_request`, `fields` trae el problema por campo.", "type": "object" }, "docs_url": { "description": "Página de documentación de este código.", "type": "string" }, "message": { "description": "Explicación para personas. Puede cambiar: no decidas con este texto.", "type": "string" }, "request_id": { "description": "Identificador de la petición, para citarlo con soporte.", "type": [ "string", "null" ] }, "retryable": { "description": "true si repetir la misma petición más tarde puede funcionar. Un rechazo ya registrado da false aunque su código suela repetirse: la misma clave devolverá lo mismo.", "type": "boolean" } }, "required": [ "code", "message", "request_id", "details", "retryable", "docs_url" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "Event": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "anyOf": [ { "$ref": "#/components/schemas/EventDataPayment" }, { "$ref": "#/components/schemas/EventDataDeposit" }, { "$ref": "#/components/schemas/EventDataCollection" }, { "$ref": "#/components/schemas/EventDataIpAllowlist" }, { "$ref": "#/components/schemas/EventDataEgressIps" } ], "description": "Contenido del evento. Su forma depende de `type`." }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. Ignora los que no conozcas. `payment.processing`: El pago se aceptó y sigue en curso, o se reabrió. `payment.in_review`: El pago está en revisión. No lo repitas. `payment.completed`: El pago se confirmó. `payment.failed`: El pago no se hizo y no queda dinero en tránsito. `payment.returned`: El pago se devolvió. Puede llegar después de `payment.completed`. `payment.canceled`: El pago se canceló. `deposit.received`: El dinero ya está acreditado. `deposit.in_review`: El depósito está en revisión. `deposit.returned`: El depósito se devolvió. `collection.paid`: El cobro se pagó. En `efectivo`, la tienda ya confirmó el pago y el abono a tu cuenta llega después. `collection.expired`: El cobro venció sin pago. `security.ip_allowlist.changed`: Cambió la lista de IP de una llave de producción. `system.egress_ips.changing`: Cambiará una IP de salida de webhooks. Actualiza tu firewall antes de `effective_at`.", "enum": [ "payment.processing", "payment.in_review", "payment.completed", "payment.failed", "payment.returned", "payment.canceled", "deposit.received", "deposit.in_review", "deposit.returned", "collection.paid", "collection.expired", "security.ip_allowlist.changed", "system.egress_ips.changing" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" }, "EventDataCollection": { "additionalProperties": false, "description": "Contenido del evento.", "properties": { "amount": { "description": "Monto que paga tu cliente.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "currency": { "description": "Moneda del cobro.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "destination_amount": { "description": "Monto que recibes.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "external_ref": { "description": "Tu referencia.", "type": [ "string", "null" ] }, "id": { "description": "Identificador del cobro, con prefijo `col_`.", "type": "string" }, "method": { "description": "Método del cobro.", "type": [ "string", "null" ] }, "status": { "description": "Estado del cobro. `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.", "enum": [ "paid", "expired" ], "type": "string" } }, "required": [ "id", "status", "amount", "destination_amount", "currency", "method", "external_ref" ], "type": "object" }, "EventDataDeposit": { "additionalProperties": false, "description": "Contenido del evento.", "properties": { "amount": { "description": "Monto recibido.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "concept": { "description": "Concepto que escribió quien pagó.", "type": [ "string", "null" ] }, "credited_amount": { "description": "Monto acreditado a tu saldo.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "credited_currency": { "description": "Moneda acreditada.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "currency": { "description": "Moneda recibida.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "id": { "description": "Identificador del depósito, con prefijo `dpt_`.", "type": "string" }, "payer": { "$ref": "#/components/schemas/Payer", "description": "Quién pagó. null si no hay datos legibles: nunca se inventa." }, "receipt_url": { "description": "Enlace https al comprobante, si existe.", "type": [ "string", "null" ] }, "received_at": { "description": "Fecha del depósito.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "reference": { "description": "Referencia del depósito.", "type": [ "string", "null" ] }, "status": { "description": "Estado del depósito. `in_review`: El depósito está en revisión. Aún no es dinero disponible. `received`: El dinero ya está acreditado. `returned`: El depósito se devolvió.", "enum": [ "in_review", "received", "returned" ], "type": "string" }, "tracking_key": { "description": "Clave de rastreo del banco.", "type": [ "string", "null" ] } }, "required": [ "id", "status", "amount", "currency", "credited_amount", "credited_currency", "received_at", "reference", "concept", "tracking_key", "receipt_url", "payer" ], "type": "object" }, "EventDataEgressIps": { "additionalProperties": false, "description": "Contenido del evento.", "properties": { "change": { "description": "Qué va a cambiar. `added`: Empezará a usarse. `retiring`: Dejará de usarse.", "enum": [ "added", "retiring" ], "type": "string" }, "effective_at": { "description": "Cuándo cambia.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": "string" }, "ip": { "description": "Dirección IP de salida.", "type": "string" } }, "required": [ "ip", "change", "effective_at" ], "type": "object" }, "EventDataIpAllowlist": { "additionalProperties": false, "description": "Contenido del evento.", "properties": { "added": { "description": "Rangos agregados, en notación CIDR.", "items": { "type": "string" }, "type": "array" }, "key": { "description": "Identificador de la llave.", "type": "string" }, "removed": { "description": "Rangos quitados, en notación CIDR.", "items": { "type": "string" }, "type": "array" } }, "required": [ "key", "added", "removed" ], "type": "object" }, "EventDataPayment": { "additionalProperties": false, "description": "Contenido del evento.", "properties": { "amount": { "description": "Monto pedido.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "currency": { "description": "Moneda pedida.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "destination_currency": { "description": "Moneda de destino. null si aún no se conoce.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "external_ref": { "description": "Tu referencia.", "type": [ "string", "null" ] }, "failure_code": { "description": "Código del catálogo de errores en `payment.failed`, null en los demás. 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.", "type": [ "string", "null" ] }, "final_amount": { "description": "Monto final, cuando se conoce.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "final_currency": { "description": "Moneda del monto final.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "id": { "description": "Identificador del pago, con prefijo `pay_`.", "type": "string" }, "status": { "description": "Estado del pago. `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.", "enum": [ "processing", "in_review", "completed", "failed", "returned", "canceled" ], "type": "string" }, "updated_at": { "description": "Última actualización.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": "string" } }, "required": [ "id", "status", "amount", "currency", "destination_currency", "final_amount", "final_currency", "failure_code", "external_ref", "updated_at" ], "type": "object" }, "LatamCountry": { "additionalProperties": false, "properties": { "account": { "additionalProperties": false, "description": "Qué se pide de la cuenta.", "properties": { "account_type_required": { "description": "true si el alta exige `account_type`.", "type": "boolean" }, "account_types": { "description": "Valores admitidos en `account_type`.", "items": { "description": "Tipo de cuenta. `checking`: Cuenta de cheques o corriente. `savings`: Cuenta de ahorro.", "enum": [ "checking", "savings" ], "type": "string" }, "type": "array" }, "digits_only": { "description": "true si sólo admite dígitos.", "type": "boolean" }, "entity_required": { "description": "true si el alta exige `entity`.", "type": "boolean" }, "exact_length": { "description": "Largo exacto. null si no aplica.", "type": [ "integer", "null" ] }, "label": { "description": "Cómo se llama el número de cuenta en ese país.", "type": [ "string", "null" ] }, "max_length": { "description": "Largo máximo. null si no aplica.", "type": [ "integer", "null" ] }, "min_length": { "description": "Largo mínimo. null si no aplica.", "type": [ "integer", "null" ] } }, "required": [ "label", "digits_only", "exact_length", "min_length", "max_length", "entity_required", "account_type_required", "account_types" ], "type": "object" }, "available": { "description": "false mientras el país esté restringido: el alta y los pagos pueden fallar.", "type": "boolean" }, "country": { "description": "País, en código de 2 letras. Es el `country` del alta.", "type": "string" }, "currency": { "description": "Moneda de la cuenta. Es el `currency` del alta.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" }, "document_types": { "description": "Valores admitidos en `document_type`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "country", "currency", "available", "document_types", "account" ], "type": "object" }, "LatamEntity": { "additionalProperties": false, "properties": { "code": { "description": "Valor a enviar en `entity`.", "type": "string" }, "name": { "description": "Nombre del banco o entidad.", "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "Limits": { "additionalProperties": false, "properties": { "max_amount": { "description": "Monto máximo por operación. Hoy siempre null: no hay tope por pago. Los pagos sí tienen tope acumulado por empresa, en la guía de límites. Ese tope y los del riel se aplican al ejecutar y responden `limit_exceeded`.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "rails": { "description": "Rieles habilitados para la empresa.", "items": { "type": "string" }, "type": "array" } }, "required": [ "max_amount", "rails" ], "type": "object" }, "Movement": { "additionalProperties": false, "properties": { "amount": { "description": "Monto del movimiento.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "completed_at": { "description": "Fecha en que terminó.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Moneda del monto.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "destination_currency": { "description": "Moneda de destino.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "external_ref": { "description": "Tu `external_ref` del pago o cobro del que sale este movimiento. null si no tiene.", "type": [ "string", "null" ] }, "final_amount": { "description": "Monto final, cuando se conoce.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "final_currency": { "description": "Moneda del monto final.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "id": { "description": "Identificador del movimiento, con prefijo `mov_`.", "type": "string" }, "payment_id": { "description": "Pago de esta API del que sale este movimiento, con prefijo `pay_`. null si no salió de un pago creado por esta API.", "type": [ "string", "null" ] }, "read_status": { "description": "Cuánto se pudo leer. `complete`: Se leyó el detalle completo. `partial`: No se pudo leer el detalle completo. El estado no avanza con una lectura parcial.", "enum": [ "complete", "partial" ], "type": "string" }, "status": { "description": "Estado público. Sólo `completed`, `failed`, `returned` y `canceled` son terminales. `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.", "enum": [ "processing", "in_review", "completed", "failed", "returned", "canceled" ], "type": "string" }, "type": { "description": "Categoría del movimiento. `payment`: Salida por un riel de pago. `deposit`: Entrada de dinero. `crypto`: Envío o recepción de un token. `internal`: Movimiento interno de la cuenta. `card`: Operación con tarjeta. `other`: Cualquier otro movimiento.", "enum": [ "payment", "deposit", "crypto", "internal", "card", "other" ], "type": "string" }, "updated_at": { "description": "Última actualización.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "type", "status", "amount", "currency", "destination_currency", "final_amount", "final_currency", "created_at", "updated_at", "completed_at", "read_status", "payment_id", "external_ref" ], "type": "object" }, "Payer": { "additionalProperties": false, "description": "Quién pagó. null si no hay datos legibles: nunca se inventa.", "properties": { "address": { "description": "Dirección de origen. null si no se conoce.", "type": [ "string", "null" ] }, "bank": { "description": "Banco de origen. null si no se conoce.", "type": [ "string", "null" ] }, "clabe": { "description": "CLABE de origen. null si no se conoce.", "type": [ "string", "null" ] }, "name": { "description": "Nombre de quien pagó. null si no se conoce.", "type": [ "string", "null" ] }, "rfc": { "description": "RFC de quien pagó. null si no se conoce.", "type": [ "string", "null" ] } }, "required": [ "name", "address", "bank", "clabe", "rfc" ], "type": [ "object", "null" ] }, "Payment": { "additionalProperties": false, "properties": { "amount": { "description": "Monto pedido.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "beneficiary_id": { "description": "Beneficiario del pago.", "type": [ "string", "null" ] }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Moneda pedida.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "external_ref": { "description": "Tu referencia.", "type": [ "string", "null" ] }, "failure_code": { "description": "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.", "type": [ "string", "null" ] }, "final_amount": { "description": "Monto final, cuando se conoce.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "final_currency": { "description": "Moneda del monto final.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "freshness": { "$ref": "#/components/schemas/PaymentFreshness", "description": "De dónde sale `status`. Sólo en `GET /v1/payments/{id}`." }, "id": { "description": "Identificador del pago, con prefijo `pay_`.", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Los pares que enviaste al crear el pago.", "type": "object" }, "reference": { "description": "Concepto del pago.", "type": [ "string", "null" ] }, "status": { "description": "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.", "enum": [ "processing", "in_review", "completed", "failed", "returned", "canceled" ], "type": "string" } }, "required": [ "id", "status", "beneficiary_id", "amount", "currency", "final_amount", "final_currency", "reference", "external_ref", "metadata", "failure_code", "created_at" ], "type": "object" }, "PaymentCreate": { "additionalProperties": false, "properties": { "amount": { "description": "Monto a enviar, como decimal en texto.", "example": "1250.00", "pattern": "^([1-9]\\d{0,14}(\\.\\d{1,2})?|0\\.([1-9]\\d?|0[1-9]))$", "type": "string" }, "beneficiary_id": { "description": "Beneficiario aprobado que recibe el pago.", "example": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "pattern": "^ben_[A-Za-z0-9]{1,76}$", "type": "string" }, "currency": { "description": "Moneda del monto.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" }, "external_ref": { "description": "Tu referencia del pago, hasta 120 caracteres imprimibles. Vuelve en el pago y en sus eventos.", "maxLength": 120, "pattern": "^[^\\p{C}\\p{Zl}\\p{Zp}]*$", "type": "string" }, "max_source_amount": { "description": "Máximo a debitar. Con cotización, manda el menor de los dos.", "example": "1250.00", "pattern": "^([1-9]\\d{0,14}(\\.\\d{1,2})?|0\\.([1-9]\\d?|0[1-9]))$", "type": "string" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Hasta 20 pares clave y valor tuyos. Valores de hasta 500 caracteres.", "type": "object" }, "quote_id": { "description": "Cotización vigente de este mismo beneficiario, monto y moneda. Fija el tope de débito.", "pattern": "^quo_[A-Za-z0-9]{1,60}$", "type": "string" }, "reference": { "description": "Concepto del pago, hasta 140 caracteres imprimibles.", "maxLength": 140, "pattern": "^[^\\p{C}\\p{Zl}\\p{Zp}]*$", "type": "string" } }, "required": [ "beneficiary_id", "amount", "currency", "external_ref" ], "type": "object" }, "PaymentFreshness": { "additionalProperties": false, "description": "De dónde sale `status`. Sólo en `GET /v1/payments/{id}`.", "properties": { "as_of": { "description": "Hora de esa lectura, de la última que se aplicó o de la cancelación confirmada. Null si aún no hay ninguna.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "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.", "enum": [ "current", "delayed" ], "type": "string" } }, "required": [ "status", "as_of" ], "type": "object" }, "Quote": { "additionalProperties": false, "properties": { "amount": { "description": "Monto a enviar.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "beneficiary_id": { "description": "Beneficiario cotizado.", "type": "string" }, "currency": { "description": "Moneda del monto.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" }, "expires_at": { "description": "Vencimiento de la cotización.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": "string" }, "id": { "description": "Identificador de la cotización, con prefijo `quo_`.", "type": "string" }, "indicative": { "description": "Siempre true: no es un precio garantizado.", "type": "boolean" }, "source_amount": { "description": "Débito estimado.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": "string" }, "source_currency": { "description": "Moneda del débito.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" } }, "required": [ "id", "beneficiary_id", "amount", "currency", "source_amount", "source_currency", "indicative", "expires_at" ], "type": "object" }, "QuoteCreate": { "additionalProperties": false, "properties": { "amount": { "description": "Monto a enviar.", "example": "1250.00", "pattern": "^([1-9]\\d{0,14}(\\.\\d{1,2})?|0\\.([1-9]\\d?|0[1-9]))$", "type": "string" }, "beneficiary_id": { "description": "Beneficiario del pago que quieres cotizar.", "example": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "pattern": "^ben_[A-Za-z0-9]{1,76}$", "type": "string" }, "currency": { "description": "Moneda del monto.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" } }, "required": [ "beneficiary_id", "amount", "currency" ], "type": "object" }, "Receipt": { "additionalProperties": false, "properties": { "amount": { "description": "Monto del movimiento.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "bank": { "description": "Banco de destino.", "type": [ "string", "null" ] }, "beneficiary": { "description": "Quién recibió.", "type": [ "string", "null" ] }, "completed_at": { "description": "Fecha en que terminó.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "concept": { "description": "Concepto.", "type": [ "string", "null" ] }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "currency": { "description": "Moneda del monto.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "external_ref": { "description": "Tu `external_ref` del pago o cobro del que sale este recibo. null si no tiene.", "type": [ "string", "null" ] }, "final_amount": { "description": "Monto final.", "example": "1250.00", "pattern": "^-?\\d+(\\.\\d+)?$", "type": [ "string", "null" ] }, "final_currency": { "description": "Moneda del monto final.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "id": { "description": "Identificador del movimiento.", "type": "string" }, "payment_id": { "description": "Pago de esta API del que sale este recibo, con prefijo `pay_`. null si no salió de un pago creado por esta API.", "type": [ "string", "null" ] }, "status": { "description": "Estado público. Sólo `completed`, `failed`, `returned` y `canceled` son terminales. `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.", "enum": [ "processing", "in_review", "completed", "failed", "returned", "canceled" ], "type": "string" }, "type": { "description": "Categoría del movimiento. `payment`: Salida por un riel de pago. `deposit`: Entrada de dinero. `crypto`: Envío o recepción de un token. `internal`: Movimiento interno de la cuenta. `card`: Operación con tarjeta. `other`: Cualquier otro movimiento.", "enum": [ "payment", "deposit", "crypto", "internal", "card", "other" ], "type": "string" } }, "required": [ "id", "type", "status", "amount", "currency", "final_amount", "final_currency", "beneficiary", "bank", "concept", "created_at", "completed_at", "payment_id", "external_ref" ], "type": "object" }, "ReceivingAccount": { "additionalProperties": false, "properties": { "account_number": { "description": "Número de cuenta. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "bank": { "description": "Banco de la cuenta. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "bic": { "description": "Código BIC. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "br_code": { "description": "Código BR para pagar por PIX, en cuentas BRL. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "bre_b_key": { "description": "Llave Bre-B, en cuentas COP. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "clabe": { "description": "CLABE de 18 dígitos. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "currency": { "description": "Moneda que recibe la cuenta.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "holder": { "description": "Titular de la cuenta. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "iban": { "description": "IBAN. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "pix_key": { "description": "Llave PIX, en cuentas BRL. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "routing_number": { "description": "Número de ruta bancaria. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "sort_code": { "description": "Sort code, en cuentas GBP. null si no aplica a esta cuenta.", "type": [ "string", "null" ] } }, "required": [ "currency", "bank", "holder", "account_number", "routing_number", "iban", "bic", "clabe", "sort_code", "pix_key", "br_code", "bre_b_key" ], "type": "object" }, "ReceivingAccountCreate": { "additionalProperties": false, "properties": { "currency": { "description": "Moneda de la cuenta: `USD`, `EUR`, `BRL`, `GBP` o `COP`. No distingue mayúsculas. MXN no se abre aquí: tu CLABE ya aparece en `GET /v1/receiving-accounts`.", "pattern": "^[A-Za-z]{3}$", "type": "string" } }, "required": [ "currency" ], "type": "object" }, "ReceivingAccountResult": { "additionalProperties": false, "properties": { "account_number": { "description": "Número de cuenta. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "already_existed": { "description": "`true` si la empresa ya tenía una cuenta activa en esa moneda y esta es la misma: nunca se abre una segunda.", "type": "boolean" }, "bank": { "description": "Banco de la cuenta. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "bic": { "description": "Código BIC. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "br_code": { "description": "Código BR para pagar por PIX, en cuentas BRL. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "bre_b_key": { "description": "Llave Bre-B, en cuentas COP. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "clabe": { "description": "CLABE de 18 dígitos. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "currency": { "description": "Moneda que recibe la cuenta.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": [ "string", "null" ] }, "holder": { "description": "Titular de la cuenta. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "iban": { "description": "IBAN. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "pix_key": { "description": "Llave PIX, en cuentas BRL. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "routing_number": { "description": "Número de ruta bancaria. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "sort_code": { "description": "Sort code, en cuentas GBP. null si no aplica a esta cuenta.", "type": [ "string", "null" ] }, "status": { "description": "Estado de la cuenta. `processing`: El alta aún no se confirma: repite con la misma clave. Los datos llegan en null. `active`: Ya recibe fondos.", "enum": [ "processing", "active" ], "type": "string" } }, "required": [ "status", "already_existed", "currency", "bank", "holder", "account_number", "routing_number", "iban", "bic", "clabe", "sort_code", "pix_key", "br_code", "bre_b_key" ], "type": "object" }, "Status": { "additionalProperties": false, "properties": { "capabilities": { "description": "Una fila por capacidad.", "items": { "additionalProperties": false, "properties": { "id": { "description": "Identificador de la capacidad. `payments_mxn`: Pagos por SPEI. `payments_latam`: Pagos por el riel `latam`. `payments_pix`: Pagos por PIX. `collections`: Cobros. `webhooks`: Entrega de webhooks. `api`: La API.", "type": "string" }, "name": { "description": "Nombre legible.", "type": "string" }, "since": { "description": "Desde cuándo está en ese estado. null si no se sabe.", "type": [ "string", "null" ] }, "status": { "description": "Estado de la capacidad. `operational`: Funciona con normalidad. `degraded`: Funciona con problemas. `outage`: No funciona. `unknown`: Sin medición reciente. `not_enabled`: No está habilitada para tu empresa.", "enum": [ "operational", "degraded", "outage", "unknown", "not_enabled" ], "type": "string" } }, "required": [ "id", "name", "status", "since" ], "type": "object" }, "type": "array" }, "updated_at": { "description": "Momento en que se armó esta respuesta.", "type": "string" } }, "required": [ "updated_at", "capabilities" ], "type": "object" }, "Wallet": { "additionalProperties": false, "properties": { "balances": { "description": "Saldo disponible de esta wallet, una fila por moneda, en las mismas monedas de `GET /v1/balances`: USD y EUR. Lista vacía si no tiene saldo en ellas.", "items": { "$ref": "#/components/schemas/Balance" }, "type": "array" }, "chain": { "description": "Red de la wallet, en minúsculas, por ejemplo `base`.", "type": [ "string", "null" ] }, "id": { "description": "Identificador de la wallet. No cambia y sólo vale para tu empresa.", "type": "string" } }, "required": [ "id", "chain", "balances" ], "type": "object" }, "WebhookEndpoint": { "additionalProperties": false, "properties": { "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "events": { "description": "Tipos suscritos. Vacío: todos.", "items": { "type": "string" }, "type": "array" }, "id": { "description": "Identificador del destino.", "type": "string" }, "status": { "description": "Estado del destino. `active`: Recibe eventos. `disabled`: Dejó de recibir eventos tras 3 días seguidos de fallos. Se reactiva en el panel. `paused`: Valor reservado. Hoy ningún flujo lo asigna.", "enum": [ "active", "disabled", "paused" ], "type": "string" }, "url": { "description": "URL https que recibe los eventos.", "type": "string" } }, "required": [ "id", "url", "events", "status", "created_at" ], "type": "object" } }, "securitySchemes": { "llaveApi": { "description": "Llave de API. Las de Producción caducan a 180 días y las de Sandbox a 90: rótala antes en el panel, que avisa 30, 7 y 1 días antes. Vencida responde `401 invalid_api_key` y ya no se puede rotar.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Montos: texto decimal, nunca número. Salen sin ceros de relleno más allá de dos decimales (`1500000.555`, `10.00`), con toda su precisión, y siempre junto a su moneda: sin moneda segura, monto y moneda llegan en null. Fechas: ISO 8601 en UTC, con `Z`.", "title": "FITAL API", "version": "2026-11-01" }, "openapi": "3.1.0", "paths": { "/v1/balances": { "get": { "description": "Saldo disponible de la empresa dueña de la llave, una fila por moneda.", "operationId": "listBalances", "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "available": "125000.00", "currency": "MXN" }, { "available": "4200.00", "currency": "USD" } ] }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Un saldo por moneda.", "items": { "$ref": "#/components/schemas/Balance" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "balances:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Saldos disponibles", "tags": [ "Cuenta" ], "x-required-scope": "balances:read" } }, "/v1/beneficiaries": { "get": { "description": "Beneficiarios de la empresa, con su estado. Paginación por cursor.", "operationId": "listBeneficiaries", "parameters": [ { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "example": "25", "pattern": "^([1-9][0-9]?|100)$", "type": "string" } }, { "description": "Valor de `next_cursor` de la página anterior.", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Valor de `next_cursor` de la página anterior.", "maxLength": 1000, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "country": "MX", "created_at": "2026-11-04T18:00:00.000Z", "id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "rail": "mxn_spei", "status": "approved" } ], "has_more": false, "next_cursor": null }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Filas de esta página.", "items": { "$ref": "#/components/schemas/Beneficiary" }, "type": "array" }, "has_more": { "description": "true si hay más filas después de esta página.", "type": "boolean" }, "next_cursor": { "description": "Cursor de la página siguiente. null si no hay.", "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "limit": "Entre 1 y 100" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "beneficiaries:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Beneficiarios", "tags": [ "Beneficiarios" ], "x-required-scope": "beneficiaries:read" }, "post": { "description": "Da de alta una cuenta destino. Nace pendiente y se aprueba en el panel, nunca por API: una llave robada no paga a un destino nuevo. Exige `Idempotency-Key` y firma. 201 si el alta quedó registrada; 202 si aún no se confirma: repite con la misma clave.", "operationId": "createBeneficiary", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "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.", "example": "pedido-7731-intento-1", "maxLength": 200, "minLength": 8, "type": "string" } }, { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "type": "string" } }, { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryCreate" } } } }, "responses": { "201": { "content": { "application/json": { "example": { "country": "MX", "created_at": "2026-11-04T18:00:00.000Z", "id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "rail": "mxn_spei", "status": "pending_approval" }, "schema": { "$ref": "#/components/schemas/Beneficiary" } } }, "description": "Creado." }, "202": { "content": { "application/json": { "example": { "country": null, "created_at": null, "id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "rail": null, "status": "processing" }, "schema": { "$ref": "#/components/schemas/Beneficiary" } } }, "description": "Aceptado: el resultado final llega después." }, "400": { "content": { "application/json": { "examples": { "idempotency_key_invalid": { "summary": "Clave inválida", "value": { "error": { "code": "idempotency_key_invalid", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_invalid", "message": "Clave inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_required": { "summary": "Falta Idempotency-Key", "value": { "error": { "code": "idempotency_key_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_required", "message": "Falta Idempotency-Key", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "amount": "Monto decimal inválido" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_signature": { "summary": "Firma inválida", "value": { "error": { "code": "invalid_signature", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_signature", "message": "Firma inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "account_restricted": { "summary": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "value": { "error": { "code": "account_restricted", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted", "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "beneficiaries:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "not_enabled": { "summary": "Falta la activación de esta función", "value": { "error": { "code": "not_enabled", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_enabled", "message": "Falta la activación de esta función", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "rail_not_enabled": { "summary": "Ese riel no está habilitado para tu empresa", "value": { "error": { "code": "rail_not_enabled", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_not_enabled", "message": "Ese riel no está habilitado para tu empresa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "409": { "content": { "application/json": { "examples": { "beneficiary_ref_conflict": { "summary": "La referencia ya existe con otros datos", "value": { "error": { "code": "beneficiary_ref_conflict", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#beneficiary_ref_conflict", "message": "La referencia ya existe con otros datos", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_in_progress": { "summary": "Operación en curso", "value": { "error": { "code": "idempotency_in_progress", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_in_progress", "message": "Operación en curso", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicto con el estado actual.", "headers": { "Retry-After": { "description": "Llega con `idempotency_in_progress`: segundos a esperar antes de repetir con la misma clave.", "schema": { "example": "1", "type": "string" } } } }, "413": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Cuerpo demasiado grande", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Cuerpo demasiado grande", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "El cuerpo pasa de 64 KB." }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "summary": "La clave ya se usó con otro cuerpo", "value": { "error": { "code": "idempotency_key_reused", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_reused", "message": "La clave ya se usó con otro cuerpo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "in_review": { "summary": "La operación está en revisión", "value": { "error": { "code": "in_review", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review", "message": "La operación está en revisión", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "invalid_beneficiary": { "summary": "Cuenta destino inválida", "value": { "error": { "code": "invalid_beneficiary", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_beneficiary", "message": "Cuenta destino inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Alta de beneficiario, pendiente de aprobar en el panel", "tags": [ "Beneficiarios" ], "x-idempotent": true, "x-required-scope": "beneficiaries:write" } }, "/v1/beneficiaries/{id}": { "delete": { "description": "Da de baja un beneficiario. Exige `Idempotency-Key` y firma. 202 si la baja aún no se confirma: repite con la misma clave.", "operationId": "deleteBeneficiary", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "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.", "example": "pedido-7731-intento-1", "maxLength": 200, "minLength": 8, "type": "string" } }, { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "type": "string" } }, { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "status": "deleted" }, "schema": { "additionalProperties": false, "properties": { "id": { "description": "Identificador del beneficiario, con prefijo `ben_`.", "example": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "pattern": "^ben_[A-Za-z0-9]{1,76}$", "type": "string" }, "status": { "description": "Resultado de la baja. `deleted`: La baja quedó confirmada. `processing`: La baja aún no se confirma: repite con la misma clave.", "enum": [ "deleted", "processing" ], "type": "string" } }, "required": [ "id", "status" ], "type": "object" } } }, "description": "Correcto." }, "202": { "content": { "application/json": { "example": { "id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "status": "processing" }, "schema": { "additionalProperties": false, "properties": { "id": { "description": "Identificador del beneficiario, con prefijo `ben_`.", "example": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "pattern": "^ben_[A-Za-z0-9]{1,76}$", "type": "string" }, "status": { "description": "Resultado de la baja. `deleted`: La baja quedó confirmada. `processing`: La baja aún no se confirma: repite con la misma clave.", "enum": [ "deleted", "processing" ], "type": "string" } }, "required": [ "id", "status" ], "type": "object" } } }, "description": "Aceptado: el resultado final llega después." }, "400": { "content": { "application/json": { "examples": { "idempotency_key_invalid": { "summary": "Clave inválida", "value": { "error": { "code": "idempotency_key_invalid", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_invalid", "message": "Clave inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_required": { "summary": "Falta Idempotency-Key", "value": { "error": { "code": "idempotency_key_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_required", "message": "Falta Idempotency-Key", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_signature": { "summary": "Firma inválida", "value": { "error": { "code": "invalid_signature", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_signature", "message": "Firma inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "account_restricted": { "summary": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "value": { "error": { "code": "account_restricted", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted", "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "beneficiaries:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "409": { "content": { "application/json": { "examples": { "beneficiary_state_conflict": { "summary": "El estado actual no permite la baja", "value": { "error": { "code": "beneficiary_state_conflict", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#beneficiary_state_conflict", "message": "El estado actual no permite la baja", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_in_progress": { "summary": "Operación en curso", "value": { "error": { "code": "idempotency_in_progress", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_in_progress", "message": "Operación en curso", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicto con el estado actual.", "headers": { "Retry-After": { "description": "Llega con `idempotency_in_progress`: segundos a esperar antes de repetir con la misma clave.", "schema": { "example": "1", "type": "string" } } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "summary": "La clave ya se usó con otro cuerpo", "value": { "error": { "code": "idempotency_key_reused", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_reused", "message": "La clave ya se usó con otro cuerpo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "in_review": { "summary": "La operación está en revisión", "value": { "error": { "code": "in_review", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review", "message": "La operación está en revisión", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Baja de beneficiario", "tags": [ "Beneficiarios" ], "x-idempotent": true, "x-required-scope": "beneficiaries:write" }, "get": { "description": "Un beneficiario de tu empresa. Si el alta quedó sin confirmar responde `processing`. El id de otra empresa da 404.", "operationId": "getBeneficiary", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "country": "MX", "created_at": "2026-11-04T18:00:00.000Z", "id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "rail": "mxn_spei", "status": "approved" }, "schema": { "$ref": "#/components/schemas/Beneficiary" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "beneficiaries:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Un beneficiario", "tags": [ "Beneficiarios" ], "x-required-scope": "beneficiaries:read" } }, "/v1/collection-methods": { "get": { "description": "Métodos de cobro de la empresa, con país, moneda, mínimos y máximos.", "operationId": "listCollectionMethods", "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "available": true, "country": "MX", "currency": "MXN", "max_amount": "50000.00", "method": "spei", "min_amount": "10.00", "payer_fields": [ { "name": "firstName", "options": null, "phone_prefix": null, "required": true }, { "name": "email", "options": null, "phone_prefix": null, "required": true }, { "name": "documentType", "options": [ "RFC", "CURP" ], "phone_prefix": null, "required": false }, { "name": "phone", "options": null, "phone_prefix": "+52", "required": false } ] } ] }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Métodos de cobro disponibles para la empresa.", "items": { "$ref": "#/components/schemas/CollectionMethod" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "collections:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Métodos de cobro", "tags": [ "Cobros" ], "x-required-scope": "collections:read" } }, "/v1/collections": { "get": { "description": "Cobros creados por esta API, con el último estado conocido, del más nuevo al más viejo.", "operationId": "listCollections", "parameters": [ { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "example": "25", "pattern": "^([1-9][0-9]?|100)$", "type": "string" } }, { "description": "Valor de `next_cursor` de la página anterior.", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Valor de `next_cursor` de la página anterior.", "maxLength": 1000, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "clabe": { "summary": "Instrucción `clabe`: sólo en sandbox.", "value": { "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 } }, "efectivo": { "summary": "Instrucción `REFERENCE`: quien paga da `value` en la tienda.", "value": { "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 } }, "link": { "summary": "Instrucción `LINK`: `value` se abre para pagar.", "value": { "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 } }, "qr": { "summary": "Instrucción `QR`: `value` se muestra o se copia.", "value": { "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 } } }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Filas de esta página.", "items": { "$ref": "#/components/schemas/Collection" }, "type": "array" }, "has_more": { "description": "true si hay más filas después de esta página.", "type": "boolean" }, "next_cursor": { "description": "Cursor de la página siguiente. null si no hay.", "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "limit": "Entre 1 y 100" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "collections:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Cobros, con su último estado conocido", "tags": [ "Cobros" ], "x-required-scope": "collections:read" }, "post": { "description": "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.", "operationId": "createCollection", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "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.", "example": "pedido-7731-intento-1", "maxLength": 200, "minLength": 8, "type": "string" } }, { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "type": "string" } }, { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreate" } } } }, "responses": { "201": { "content": { "application/json": { "examples": { "clabe": { "summary": "Instrucción `clabe`: sólo en sandbox.", "value": { "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" } }, "efectivo": { "summary": "Instrucción `REFERENCE`: quien paga da `value` en la tienda.", "value": { "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" } }, "link": { "summary": "Instrucción `LINK`: `value` se abre para pagar.", "value": { "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" } }, "qr": { "summary": "Instrucción `QR`: `value` se muestra o se copia.", "value": { "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" } } }, "schema": { "$ref": "#/components/schemas/Collection" } } }, "description": "Creado." }, "202": { "content": { "application/json": { "example": { "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" }, "schema": { "$ref": "#/components/schemas/Collection" } } }, "description": "Aceptado: el resultado final llega después." }, "400": { "content": { "application/json": { "examples": { "idempotency_key_invalid": { "summary": "Clave inválida", "value": { "error": { "code": "idempotency_key_invalid", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_invalid", "message": "Clave inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_required": { "summary": "Falta Idempotency-Key", "value": { "error": { "code": "idempotency_key_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_required", "message": "Falta Idempotency-Key", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "amount": "Monto decimal inválido" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_signature": { "summary": "Firma inválida", "value": { "error": { "code": "invalid_signature", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_signature", "message": "Firma inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "account_restricted": { "summary": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "value": { "error": { "code": "account_restricted", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted", "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "collections:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "not_enabled": { "summary": "Falta la activación de esta función", "value": { "error": { "code": "not_enabled", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_enabled", "message": "Falta la activación de esta función", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "409": { "content": { "application/json": { "examples": { "collection_not_ready": { "summary": "El cobro todavía no se puede crear", "value": { "error": { "code": "collection_not_ready", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#collection_not_ready", "message": "El cobro todavía no se puede crear", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_in_progress": { "summary": "Operación en curso", "value": { "error": { "code": "idempotency_in_progress", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_in_progress", "message": "Operación en curso", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicto con el estado actual.", "headers": { "Retry-After": { "description": "Llega con `idempotency_in_progress`: segundos a esperar antes de repetir con la misma clave.", "schema": { "example": "1", "type": "string" } } } }, "413": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Cuerpo demasiado grande", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Cuerpo demasiado grande", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "El cuerpo pasa de 64 KB." }, "422": { "content": { "application/json": { "examples": { "amount_out_of_range": { "summary": "Monto fuera de rango", "value": { "error": { "code": "amount_out_of_range", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#amount_out_of_range", "message": "Monto fuera de rango", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "collection_rejected": { "summary": "Cobro rechazado", "value": { "error": { "code": "collection_rejected", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#collection_rejected", "message": "Cobro rechazado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_reused": { "summary": "La clave ya se usó con otro cuerpo", "value": { "error": { "code": "idempotency_key_reused", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_reused", "message": "La clave ya se usó con otro cuerpo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "in_review": { "summary": "La operación está en revisión", "value": { "error": { "code": "in_review", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review", "message": "La operación está en revisión", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "method_unavailable": { "summary": "Método no disponible", "value": { "error": { "code": "method_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#method_unavailable", "message": "Método no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "rail_unavailable": { "summary": "El riel no está disponible ahora", "value": { "error": { "code": "rail_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_unavailable", "message": "El riel no está disponible ahora", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Crear un cobro", "tags": [ "Cobros" ], "x-idempotent": true, "x-required-scope": "collections:write" } }, "/v1/collections/estimate": { "post": { "description": "Estima montos y comisiones de un cobro antes de crearlo. Es indicativa y no crea nada, por eso no pide `Idempotency-Key`. Va firmada como las demás escrituras de cobros.", "operationId": "estimateCollection", "parameters": [ { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "type": "string" } }, { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionEstimateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "example": { "amount": "1250.00", "currency": "MXN", "exchange_rate": null, "expires_at": "2026-11-04T18:05:00.000Z", "fee": "25.00", "fee_currency": "MXN", "indicative": true, "max_amount": "50000.00", "min_amount": "10.00", "plan_fee_pct": "2.00", "receive_amount": "1225.00", "receive_currency": "MXN", "total_cost_pct": "2.00" }, "schema": { "$ref": "#/components/schemas/CollectionEstimate" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "amount": "Monto decimal inválido" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_signature": { "summary": "Firma inválida", "value": { "error": { "code": "invalid_signature", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_signature", "message": "Firma inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "collections:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "413": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Cuerpo demasiado grande", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Cuerpo demasiado grande", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "El cuerpo pasa de 64 KB." }, "422": { "content": { "application/json": { "examples": { "amount_out_of_range": { "summary": "Monto fuera de rango", "value": { "error": { "code": "amount_out_of_range", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#amount_out_of_range", "message": "Monto fuera de rango", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "collection_rejected": { "summary": "Cobro rechazado", "value": { "error": { "code": "collection_rejected", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#collection_rejected", "message": "Cobro rechazado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "method_unavailable": { "summary": "Método no disponible", "value": { "error": { "code": "method_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#method_unavailable", "message": "Método no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Estimar un cobro", "tags": [ "Cobros" ], "x-required-scope": "collections:write" } }, "/v1/collections/{id}": { "get": { "description": "Un cobro de tu empresa, con su estado actual. `paid` y `expired` no vuelven atrás.", "operationId": "getCollection", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "clabe": { "summary": "Instrucción `clabe`: sólo en sandbox.", "value": { "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" } }, "efectivo": { "summary": "Instrucción `REFERENCE`: quien paga da `value` en la tienda.", "value": { "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" } }, "link": { "summary": "Instrucción `LINK`: `value` se abre para pagar.", "value": { "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" } }, "qr": { "summary": "Instrucción `QR`: `value` se muestra o se copia.", "value": { "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" } } }, "schema": { "$ref": "#/components/schemas/Collection" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "collections:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Un cobro", "tags": [ "Cobros" ], "x-required-scope": "collections:read" } }, "/v1/deposit-addresses": { "get": { "description": "Direcciones de depósito de la empresa. Paginación por cursor.", "operationId": "listDepositAddresses", "parameters": [ { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "example": "25", "pattern": "^([1-9][0-9]?|100)$", "type": "string" } }, { "description": "Valor de `next_cursor` de la página anterior.", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Valor de `next_cursor` de la página anterior.", "maxLength": 1000, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "address": "0x0000000000000000000000000000000000000000", "chain": "polygon", "created_at": "2026-11-04T18:00:00.000Z", "currency": "USDC", "id": "dep_9vLsK3mNc7QxB1tZ5hYdR2fP", "status": "active", "warning": "Envía sólo USDC por la red polygon. Otro token u otra red puede no acreditarse." } ], "has_more": false, "next_cursor": null }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Filas de esta página.", "items": { "$ref": "#/components/schemas/DepositAddress" }, "type": "array" }, "has_more": { "description": "true si hay más filas después de esta página.", "type": "boolean" }, "next_cursor": { "description": "Cursor de la página siguiente. null si no hay.", "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "limit": "Entre 1 y 100" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "deposit_addresses:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Direcciones de depósito", "tags": [ "Depósitos" ], "x-required-scope": "deposit_addresses:read" }, "post": { "description": "Crea una dirección de depósito para una red y un token. Exige `Idempotency-Key` y firma. 201 si quedó activa; 202 si aún no se confirma: repite con la misma clave.", "operationId": "createDepositAddress", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "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.", "example": "pedido-7731-intento-1", "maxLength": 200, "minLength": 8, "type": "string" } }, { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "type": "string" } }, { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddressCreate" } } } }, "responses": { "201": { "content": { "application/json": { "example": { "address": "0x0000000000000000000000000000000000000000", "chain": "polygon", "created_at": "2026-11-04T18:00:00.000Z", "currency": "USDC", "id": "dep_9vLsK3mNc7QxB1tZ5hYdR2fP", "status": "active", "warning": "Envía sólo USDC por la red polygon. Otro token u otra red puede no acreditarse." }, "schema": { "$ref": "#/components/schemas/DepositAddress" } } }, "description": "Creado." }, "202": { "content": { "application/json": { "example": { "address": null, "chain": null, "created_at": null, "currency": null, "id": "dep_9vLsK3mNc7QxB1tZ5hYdR2fP", "status": "processing", "warning": null }, "schema": { "$ref": "#/components/schemas/DepositAddress" } } }, "description": "Aceptado: el resultado final llega después." }, "400": { "content": { "application/json": { "examples": { "idempotency_key_invalid": { "summary": "Clave inválida", "value": { "error": { "code": "idempotency_key_invalid", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_invalid", "message": "Clave inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_required": { "summary": "Falta Idempotency-Key", "value": { "error": { "code": "idempotency_key_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_required", "message": "Falta Idempotency-Key", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "amount": "Monto decimal inválido" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_signature": { "summary": "Firma inválida", "value": { "error": { "code": "invalid_signature", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_signature", "message": "Firma inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "account_restricted": { "summary": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "value": { "error": { "code": "account_restricted", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted", "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "deposit_addresses:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "409": { "content": { "application/json": { "examples": { "idempotency_in_progress": { "summary": "Operación en curso", "value": { "error": { "code": "idempotency_in_progress", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_in_progress", "message": "Operación en curso", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicto con el estado actual.", "headers": { "Retry-After": { "description": "Llega con `idempotency_in_progress`: segundos a esperar antes de repetir con la misma clave.", "schema": { "example": "1", "type": "string" } } } }, "413": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Cuerpo demasiado grande", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Cuerpo demasiado grande", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "El cuerpo pasa de 64 KB." }, "422": { "content": { "application/json": { "examples": { "deposit_address_rejected": { "summary": "Dirección rechazada", "value": { "error": { "code": "deposit_address_rejected", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#deposit_address_rejected", "message": "Dirección rechazada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_reused": { "summary": "La clave ya se usó con otro cuerpo", "value": { "error": { "code": "idempotency_key_reused", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_reused", "message": "La clave ya se usó con otro cuerpo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "in_review": { "summary": "La operación está en revisión", "value": { "error": { "code": "in_review", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review", "message": "La operación está en revisión", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "pair_not_supported": { "summary": "Esa red no admite ese token", "value": { "error": { "code": "pair_not_supported", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#pair_not_supported", "message": "Esa red no admite ese token", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Crear una dirección de depósito", "tags": [ "Depósitos" ], "x-idempotent": true, "x-required-scope": "deposit_addresses:write" } }, "/v1/deposit-addresses/{id}": { "get": { "description": "Una dirección de depósito de tu empresa. Si el alta quedó sin confirmar responde `processing`, con los datos en null.", "operationId": "getDepositAddress", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "address": "0x0000000000000000000000000000000000000000", "chain": "polygon", "created_at": "2026-11-04T18:00:00.000Z", "currency": "USDC", "id": "dep_9vLsK3mNc7QxB1tZ5hYdR2fP", "status": "active", "warning": "Envía sólo USDC por la red polygon. Otro token u otra red puede no acreditarse." }, "schema": { "$ref": "#/components/schemas/DepositAddress" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "deposit_addresses:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Una dirección de depósito", "tags": [ "Depósitos" ], "x-required-scope": "deposit_addresses:read" } }, "/v1/deposits": { "get": { "description": "Depósitos recibidos y quién pagó, del más nuevo al más viejo. `payer` llega en null si no hay datos legibles.", "operationId": "listDeposits", "parameters": [ { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "example": "25", "pattern": "^([1-9][0-9]?|100)$", "type": "string" } }, { "description": "Valor de `next_cursor` de la página anterior.", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Valor de `next_cursor` de la página anterior.", "maxLength": 1000, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "amount": "1250.00", "concept": "Pedido 7731", "credited_amount": "1250.00", "credited_currency": "MXN", "currency": "MXN", "id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "payer": { "address": null, "bank": "Banco de ejemplo", "clabe": "999180000000000022", "name": "CLIENTE FICTICIO SA DE CV", "rfc": "XAXX010101000" }, "receipt_url": null, "received_at": "2026-11-04T18:00:00.000Z", "reference": "7731", "status": "received", "tracking_key": "CLAVE-DE-RASTREO-DEMO" } ], "has_more": false, "next_cursor": null }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Filas de esta página.", "items": { "$ref": "#/components/schemas/Deposit" }, "type": "array" }, "has_more": { "description": "true si hay más filas después de esta página.", "type": "boolean" }, "next_cursor": { "description": "Cursor de la página siguiente. null si no hay.", "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "limit": "Entre 1 y 100" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "deposits:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Depósitos recibidos y quién pagó", "tags": [ "Depósitos" ], "x-required-scope": "deposits:read" } }, "/v1/deposits/{id}": { "get": { "description": "Un depósito de tu empresa. El id va sellado por empresa: el de otra da 404.", "operationId": "getDeposit", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "amount": "1250.00", "concept": "Pedido 7731", "credited_amount": "1250.00", "credited_currency": "MXN", "currency": "MXN", "id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "payer": { "address": null, "bank": "Banco de ejemplo", "clabe": "999180000000000022", "name": "CLIENTE FICTICIO SA DE CV", "rfc": "XAXX010101000" }, "receipt_url": null, "received_at": "2026-11-04T18:00:00.000Z", "reference": "7731", "status": "received", "tracking_key": "CLAVE-DE-RASTREO-DEMO" }, "schema": { "$ref": "#/components/schemas/Deposit" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "deposits:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Un depósito", "tags": [ "Depósitos" ], "x-required-scope": "deposits:read" } }, "/v1/events": { "get": { "description": "Eventos de la empresa, del más nuevo al más viejo. Sirve para recuperar lo que un webhook no entregó: pide sin cursor y recorre hasta un evento que ya procesaste. `next_cursor` sólo camina hacia el pasado y termina en null, así que no lo guardes entre consultas. Filtra con `type`.", "operationId": "listEvents", "parameters": [ { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "example": "25", "pattern": "^([1-9][0-9]?|100)$", "type": "string" } }, { "description": "Valor de `next_cursor` de la página anterior.", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Valor de `next_cursor` de la página anterior.", "maxLength": 1000, "minLength": 1, "type": "string" } }, { "description": "Filtra por tipo de evento, por ejemplo `payment.completed`.", "in": "query", "name": "type", "required": false, "schema": { "description": "Filtra por tipo de evento, por ejemplo `payment.completed`.", "maxLength": 60, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1500.00", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "failure_code": null, "final_amount": "1500.00", "final_currency": "MXN", "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "completed", "updated_at": "2026-11-04T18:01:30.000Z" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "sequence": 2, "type": "payment.completed" } ], "has_more": false, "next_cursor": null }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Filas de esta página.", "items": { "$ref": "#/components/schemas/Event" }, "type": "array" }, "has_more": { "description": "true si hay más filas después de esta página.", "type": "boolean" }, "next_cursor": { "description": "Cursor de la página siguiente. null si no hay.", "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "limit": "Entre 1 y 100" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "events:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Eventos de la empresa", "tags": [ "Eventos" ], "x-required-scope": "events:read" } }, "/v1/events/{id}": { "get": { "description": "Un evento de tu empresa, con el mismo contenido que entrega el webhook.", "operationId": "getEvent", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1500.00", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "failure_code": null, "final_amount": "1500.00", "final_currency": "MXN", "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "completed", "updated_at": "2026-11-04T18:01:30.000Z" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "sequence": 2, "type": "payment.completed" }, "schema": { "$ref": "#/components/schemas/Event" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "events:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Un evento", "tags": [ "Eventos" ], "x-required-scope": "events:read" } }, "/v1/health": { "get": { "description": "Estado general del servicio, sin llave y sin gastar cuota. Sale de una medición en segundo plano: si tiene más de 15 s responde `degraded`, aunque dijera `ok`. Con `down` el código es 503.", "operationId": "getHealth", "responses": { "200": { "content": { "application/json": { "example": { "api_version": "v1", "status": "ok" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión de la API. `v1`: la única publicada.", "enum": [ "v1" ], "type": "string" }, "status": { "description": "Estado general del servicio. `ok`: El servicio funciona. `degraded`: La medición es vieja o hay problemas parciales. Responde `200`. `down`: El servicio no funciona. Responde `503`.", "enum": [ "ok", "degraded", "down" ], "type": "string" } }, "required": [ "status", "api_version" ], "type": "object" } } }, "description": "Correcto." }, "503": { "content": { "application/json": { "example": { "api_version": "v1", "status": "down" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión de la API. `v1`: la única publicada.", "enum": [ "v1" ], "type": "string" }, "status": { "description": "Estado general del servicio. `ok`: El servicio funciona. `degraded`: La medición es vieja o hay problemas parciales. Responde `200`. `down`: El servicio no funciona. Responde `503`.", "enum": [ "ok", "degraded", "down" ], "type": "string" } }, "required": [ "status", "api_version" ], "type": "object" } } }, "description": "Servicio no disponible." } }, "security": [], "summary": "Salud pública del servicio", "tags": [ "Sistema" ], "x-public": true } }, "/v1/latam/countries": { "get": { "description": "Países a los que tu empresa puede pagar por el riel `latam`, con su moneda y lo que cada uno pide para dar de alta una cuenta. Sale de la configuración vigente: consúltalo en vez de copiarlo.", "operationId": "listLatamCountries", "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "account": { "account_type_required": false, "account_types": [ "checking", "savings" ], "digits_only": true, "entity_required": true, "exact_length": null, "label": "Número de cuenta", "max_length": 20, "min_length": 5 }, "available": true, "country": "CL", "currency": "CLP", "document_types": [ "RUT", "PP" ] } ] }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Países del riel `latam` para tu empresa.", "items": { "$ref": "#/components/schemas/LatamCountry" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "beneficiaries:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "rail_not_enabled": { "summary": "Ese riel no está habilitado para tu empresa", "value": { "error": { "code": "rail_not_enabled", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_not_enabled", "message": "Ese riel no está habilitado para tu empresa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Países del riel `latam`", "tags": [ "Beneficiarios" ], "x-required-scope": "beneficiaries:read" } }, "/v1/latam/countries/{country}/entities": { "get": { "description": "Bancos y entidades de un país del riel `latam`, con el valor a enviar en `entity`. Un país fuera de `GET /v1/latam/countries` responde `404`.", "operationId": "listLatamEntities", "parameters": [ { "description": "País, en código de 2 letras.", "in": "path", "name": "country", "required": true, "schema": { "description": "País, en código de 2 letras.", "example": "CL", "pattern": "^[A-Za-z]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "code": "999", "name": "Banco de ejemplo" } ] }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Bancos y entidades del país.", "items": { "$ref": "#/components/schemas/LatamEntity" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "beneficiaries:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "rail_not_enabled": { "summary": "Ese riel no está habilitado para tu empresa", "value": { "error": { "code": "rail_not_enabled", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_not_enabled", "message": "Ese riel no está habilitado para tu empresa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Bancos de un país del riel `latam`", "tags": [ "Beneficiarios" ], "x-required-scope": "beneficiaries:read" } }, "/v1/limits": { "get": { "description": "Monto máximo por operación, si existe uno fijo para la empresa, y rieles habilitados. Un riel fuera de `rails` no se puede usar.", "operationId": "getLimits", "responses": { "200": { "content": { "application/json": { "example": { "max_amount": null, "rails": [ "mxn_spei" ] }, "schema": { "$ref": "#/components/schemas/Limits" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "balances:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Límites de la cuenta", "tags": [ "Cuenta" ], "x-required-scope": "balances:read" } }, "/v1/meta/egress-ips": { "get": { "description": "Direcciones desde las que FITAL envía webhooks, para tu firewall. Pública, con un minuto de caché. La firma HMAC sigue siendo la protección principal.", "operationId": "getEgressIps", "responses": { "200": { "content": { "application/json": { "example": { "addresses": [ { "active_from": "2026-11-01T00:00:00.000Z", "ip": "198.51.100.10", "retiring_at": null } ], "note": "La firma HMAC es la protección principal" }, "schema": { "$ref": "#/components/schemas/EgressIps" } } }, "description": "Correcto." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." } }, "security": [], "summary": "IP de salida de webhooks", "tags": [ "Sistema" ], "x-public": true } }, "/v1/movements": { "get": { "description": "Movimientos de la cuenta, de esta API y de otros orígenes, en el orden en que cambiaron. `payment_id` y `external_ref` dicen de qué pago sale cada uno. Al llegar al final `has_more` es `false` y `next_cursor` sigue presente: guárdalo y úsalo después para recibir sólo lo nuevo. Ese recorrido siguiente empieza en la hora en que abrió el anterior y repasa 2 minutos más, para no perder lo que confirmó tarde, y una fila que cambia mientras recorres vuelve a salir. Por eso un mismo id puede repetirse: quédate con la copia de `updated_at` más reciente. Con `from` y `to`, `from` debe ser anterior.", "operationId": "listMovements", "parameters": [ { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "example": "25", "pattern": "^([1-9][0-9]?|100)$", "type": "string" } }, { "description": "Valor de `next_cursor` de la página anterior.", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Valor de `next_cursor` de la página anterior.", "maxLength": 1000, "minLength": 1, "type": "string" } }, { "description": "Desde esta fecha de creación, incluida.", "in": "query", "name": "from", "required": false, "schema": { "description": "Desde esta fecha de creación, incluida.", "format": "date-time", "type": "string" } }, { "description": "Hasta esta fecha de creación, sin incluirla.", "in": "query", "name": "to", "required": false, "schema": { "description": "Hasta esta fecha de creación, sin incluirla.", "format": "date-time", "type": "string" } }, { "description": "Filtra por categoría. `payment`: Salida por un riel de pago. `deposit`: Entrada de dinero. `crypto`: Envío o recepción de un token. `internal`: Movimiento interno de la cuenta. `card`: Operación con tarjeta. `other`: Cualquier otro movimiento.", "in": "query", "name": "type", "required": false, "schema": { "description": "Filtra por categoría. `payment`: Salida por un riel de pago. `deposit`: Entrada de dinero. `crypto`: Envío o recepción de un token. `internal`: Movimiento interno de la cuenta. `card`: Operación con tarjeta. `other`: Cualquier otro movimiento.", "enum": [ "payment", "deposit", "crypto", "internal", "card", "other" ], "type": "string" } }, { "description": "Filtra por cualquiera de las monedas del movimiento.", "in": "query", "name": "currency", "required": false, "schema": { "description": "Filtra por cualquiera de las monedas del movimiento.", "example": "MXN", "pattern": "^[A-Z]{3,5}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "amount": "1500.00", "completed_at": "2026-11-04T18:01:30.000Z", "created_at": "2026-11-04T18:00:00.000Z", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "final_amount": "1500.00", "final_currency": "MXN", "id": "mov_2hKsV9tBq4XzM7nD1cYpL6rF", "payment_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "read_status": "complete", "status": "completed", "type": "payment", "updated_at": "2026-11-04T18:01:30.000Z" } ], "has_more": false, "next_cursor": null }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Filas de esta página.", "items": { "$ref": "#/components/schemas/Movement" }, "type": "array" }, "has_more": { "description": "true si hay más filas después de esta página.", "type": "boolean" }, "next_cursor": { "description": "Cursor de la página siguiente. null si no hay.", "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "limit": "Entre 1 y 100" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "movements:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Movimientos de la cuenta", "tags": [ "Movimientos" ], "x-required-scope": "movements:read" } }, "/v1/movements/{id}": { "get": { "description": "Un movimiento de tu empresa. El id va sellado por empresa: el de otra da 404.", "operationId": "getMovement", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "amount": "1500.00", "completed_at": "2026-11-04T18:01:30.000Z", "created_at": "2026-11-04T18:00:00.000Z", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "final_amount": "1500.00", "final_currency": "MXN", "id": "mov_2hKsV9tBq4XzM7nD1cYpL6rF", "payment_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "read_status": "complete", "status": "completed", "type": "payment", "updated_at": "2026-11-04T18:01:30.000Z" }, "schema": { "$ref": "#/components/schemas/Movement" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "movements:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Un movimiento", "tags": [ "Movimientos" ], "x-required-scope": "movements:read" } }, "/v1/movements/{id}/receipt": { "get": { "description": "Recibo de un movimiento terminal. Con `Accept: application/json` responde datos; si no, un PDF. Antes de terminar da `409 receipt_not_available`.", "operationId": "getMovementReceipt", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "amount": "1500.00", "bank": "Banco de ejemplo", "beneficiary": "PROVEEDOR FICTICIO SA DE CV", "completed_at": "2026-11-04T18:01:30.000Z", "concept": "Factura 1042", "created_at": "2026-11-04T18:00:00.000Z", "currency": "MXN", "external_ref": "pedido-7731", "final_amount": "1500.00", "final_currency": "MXN", "id": "mov_2hKsV9tBq4XzM7nD1cYpL6rF", "payment_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "completed", "type": "payment" }, "schema": { "$ref": "#/components/schemas/Receipt" } }, "application/pdf": { "schema": { "format": "binary", "type": "string" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "movements:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "409": { "content": { "application/json": { "examples": { "receipt_not_available": { "summary": "El movimiento aún no tiene recibo", "value": { "error": { "code": "receipt_not_available", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#receipt_not_available", "message": "El movimiento aún no tiene recibo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicto con el estado actual." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Recibo de un movimiento terminal", "tags": [ "Movimientos" ], "x-required-scope": "movements:read" } }, "/v1/payments": { "get": { "description": "Pagos creados por esta API, con el último estado conocido, del más nuevo al más viejo. Para el estado más fresco de uno, usa `GET /v1/payments/{id}`.", "operationId": "listPayments", "parameters": [ { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Filas por página, de 1 a 100. Por omisión, 25.", "example": "25", "pattern": "^([1-9][0-9]?|100)$", "type": "string" } }, { "description": "Valor de `next_cursor` de la página anterior.", "in": "query", "name": "cursor", "required": false, "schema": { "description": "Valor de `next_cursor` de la página anterior.", "maxLength": 1000, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "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 }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Filas de esta página.", "items": { "$ref": "#/components/schemas/Payment" }, "type": "array" }, "has_more": { "description": "true si hay más filas después de esta página.", "type": "boolean" }, "next_cursor": { "description": "Cursor de la página siguiente. null si no hay.", "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "limit": "Entre 1 y 100" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "payments:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Pagos, con su último estado conocido", "tags": [ "Pagos" ], "x-required-scope": "payments:read" }, "post": { "description": "Crea un pago a un beneficiario aprobado. Exige `Idempotency-Key` y firma. Responde 202: el resultado llega por webhook o en `GET /v1/payments/{id}`. Si la respuesta se corta, repite con la misma clave: nunca crea un segundo pago. `in_review` con `retryable: false` quedó registrado: esa clave repite el rechazo, y volver a intentarlo exige otra.", "operationId": "createPayment", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "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.", "example": "pedido-7731-intento-1", "maxLength": 200, "minLength": 8, "type": "string" } }, { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "type": "string" } }, { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCreate" } } } }, "responses": { "202": { "content": { "application/json": { "examples": { "payment_completed": { "summary": "Termina en `completed`.", "value": { "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": null, "final_currency": null, "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "metadata": {}, "reference": "Factura 1042", "status": "processing" } } }, "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Aceptado: el resultado final llega después." }, "400": { "content": { "application/json": { "examples": { "idempotency_key_invalid": { "summary": "Clave inválida", "value": { "error": { "code": "idempotency_key_invalid", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_invalid", "message": "Clave inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_required": { "summary": "Falta Idempotency-Key", "value": { "error": { "code": "idempotency_key_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_required", "message": "Falta Idempotency-Key", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "amount": "Monto decimal inválido" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_signature": { "summary": "Firma inválida", "value": { "error": { "code": "invalid_signature", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_signature", "message": "Firma inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "account_restricted": { "summary": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "value": { "error": { "code": "account_restricted", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted", "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "payments:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "not_enabled": { "summary": "Falta la activación de esta función", "value": { "error": { "code": "not_enabled", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_enabled", "message": "Falta la activación de esta función", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "rail_not_enabled": { "summary": "Ese riel no está habilitado para tu empresa", "value": { "error": { "code": "rail_not_enabled", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_not_enabled", "message": "Ese riel no está habilitado para tu empresa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "409": { "content": { "application/json": { "examples": { "idempotency_in_progress": { "summary": "Operación en curso", "value": { "error": { "code": "idempotency_in_progress", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_in_progress", "message": "Operación en curso", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "payment_in_flight": { "summary": "Otro pago de tu empresa sigue sin confirmarse", "value": { "error": { "code": "payment_in_flight", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#payment_in_flight", "message": "Otro pago de tu empresa sigue sin confirmarse", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "quote_changed": { "summary": "El débito superaría lo permitido", "value": { "error": { "code": "quote_changed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#quote_changed", "message": "El débito superaría lo permitido", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "quote_expired": { "summary": "La cotización venció", "value": { "error": { "code": "quote_expired", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#quote_expired", "message": "La cotización venció", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicto con el estado actual.", "headers": { "Retry-After": { "description": "Llega con `idempotency_in_progress`: segundos a esperar antes de repetir con la misma clave.", "schema": { "example": "1", "type": "string" } } } }, "413": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Cuerpo demasiado grande", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Cuerpo demasiado grande", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "El cuerpo pasa de 64 KB." }, "422": { "content": { "application/json": { "examples": { "amount_below_minimum": { "summary": "Monto por debajo del mínimo", "value": { "error": { "code": "amount_below_minimum", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#amount_below_minimum", "message": "Monto por debajo del mínimo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "beneficiary_not_approved": { "summary": "El beneficiario aún no está aprobado", "value": { "error": { "code": "beneficiary_not_approved", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#beneficiary_not_approved", "message": "El beneficiario aún no está aprobado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "currency_not_supported": { "summary": "Moneda no admitida", "value": { "error": { "code": "currency_not_supported", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#currency_not_supported", "message": "Moneda no admitida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_reused": { "summary": "La clave ya se usó con otro cuerpo", "value": { "error": { "code": "idempotency_key_reused", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_reused", "message": "La clave ya se usó con otro cuerpo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "in_review": { "summary": "La operación está en revisión", "value": { "error": { "code": "in_review", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review", "message": "La operación está en revisión", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "insufficient_funds": { "summary": "Saldo insuficiente.", "value": { "error": { "code": "insufficient_funds", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#insufficient_funds", "message": "Saldo insuficiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "limit_exceeded": { "summary": "Se superó el tope acumulado de la empresa o un límite del riel", "value": { "error": { "code": "limit_exceeded", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#limit_exceeded", "message": "Se superó el tope acumulado de la empresa o un límite del riel", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "payment_held": { "summary": "Sin `pay_`. Repite con la misma clave tras levantarse: crea un pago.", "value": { "error": { "code": "in_review", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review", "message": "La operación está en revisión. Repite con la misma clave cuando se levante.", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "payment_rejected": { "summary": "Pago rechazado", "value": { "error": { "code": "payment_rejected", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#payment_rejected", "message": "Pago rechazado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "rail_unavailable": { "summary": "El riel no está disponible ahora", "value": { "error": { "code": "rail_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rail_unavailable", "message": "El riel no está disponible ahora", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Crear un pago", "tags": [ "Pagos" ], "x-idempotent": true, "x-required-scope": "payments:write", "x-scenarios": [ "payment_completed", "insufficient_funds", "payment_held" ] } }, "/v1/payments/{id}": { "get": { "description": "Un pago de tu empresa. `completed` exige confirmación del riel. `freshness` dice de dónde sale el estado: con `current` es la lectura de ahora y `as_of` su hora; con `delayed` no hubo lectura concluyente y es lo último que se sabe, a la hora de `as_of`. Una cancelación confirmada responde `canceled` con `delayed` hasta que una lectura la confirme. Si un pago cancelado vuelve a `processing` con `current`, se reabrió de verdad.", "operationId": "getPayment", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "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", "freshness": { "as_of": "2026-11-04T18:01:30.000Z", "status": "current" }, "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "metadata": {}, "reference": "Factura 1042", "status": "completed" }, "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "payments:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Un pago", "tags": [ "Pagos" ], "x-required-scope": "payments:read" } }, "/v1/payments/{id}/cancel": { "post": { "description": "Cancela un pago que aún espera fondos. Exige `Idempotency-Key` y firma. Si ya no se puede cancelar da `409 not_cancellable`. 202 si la cancelación aún no se confirma: repite con la misma clave.", "operationId": "cancelPayment", "parameters": [ { "description": "Identificador del recurso.", "in": "path", "name": "id", "required": true, "schema": { "description": "Identificador del recurso.", "maxLength": 250, "minLength": 1, "type": "string" } }, { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "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.", "example": "pedido-7731-intento-1", "maxLength": 200, "minLength": 8, "type": "string" } }, { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "type": "string" } }, { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "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": null, "final_currency": null, "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "metadata": {}, "reference": "Factura 1042", "status": "canceled" }, "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Correcto." }, "202": { "content": { "application/json": { "example": { "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": null, "final_currency": null, "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "metadata": {}, "reference": "Factura 1042", "status": "processing" }, "schema": { "$ref": "#/components/schemas/Payment" } } }, "description": "Aceptado: el resultado final llega después." }, "400": { "content": { "application/json": { "examples": { "idempotency_key_invalid": { "summary": "Clave inválida", "value": { "error": { "code": "idempotency_key_invalid", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_invalid", "message": "Clave inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_required": { "summary": "Falta Idempotency-Key", "value": { "error": { "code": "idempotency_key_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_required", "message": "Falta Idempotency-Key", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_signature": { "summary": "Firma inválida", "value": { "error": { "code": "invalid_signature", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_signature", "message": "Firma inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "payments:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "409": { "content": { "application/json": { "examples": { "idempotency_in_progress": { "summary": "Operación en curso", "value": { "error": { "code": "idempotency_in_progress", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_in_progress", "message": "Operación en curso", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "not_cancellable": { "summary": "El pago no se puede cancelar", "value": { "error": { "code": "not_cancellable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_cancellable", "message": "El pago no se puede cancelar", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicto con el estado actual.", "headers": { "Retry-After": { "description": "Llega con `idempotency_in_progress`: segundos a esperar antes de repetir con la misma clave.", "schema": { "example": "1", "type": "string" } } } }, "422": { "content": { "application/json": { "examples": { "idempotency_key_reused": { "summary": "La clave ya se usó con otro cuerpo", "value": { "error": { "code": "idempotency_key_reused", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_reused", "message": "La clave ya se usó con otro cuerpo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Cancelar un pago que aún espera fondos", "tags": [ "Pagos" ], "x-idempotent": true, "x-required-scope": "payments:write" } }, "/v1/quotes": { "post": { "description": "Estima cuánto se debitaría por un pago a un beneficiario de tu empresa. Es indicativa y vence. No mueve dinero. Envía `quote_id` al crear el pago para fijar el tope de débito.", "operationId": "createQuote", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteCreate" } } } }, "responses": { "200": { "content": { "application/json": { "example": { "amount": "1500.00", "beneficiary_id": "ben_3kTMd9wQp2LxZ7vR1nYcA4bE", "currency": "MXN", "expires_at": "2026-11-04T18:05:00.000Z", "id": "quo_8dZxN3vTk6LqB2sW9mHrY4cP", "indicative": true, "source_amount": "82.50", "source_currency": "USD" }, "schema": { "$ref": "#/components/schemas/Quote" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "amount": "Monto decimal inválido" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "quotes:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "404": { "content": { "application/json": { "examples": { "not_found": { "summary": "No encontrado", "value": { "error": { "code": "not_found", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_found", "message": "No encontrado", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No existe o es de otra empresa." }, "413": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Cuerpo demasiado grande", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Cuerpo demasiado grande", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "El cuerpo pasa de 64 KB." }, "422": { "content": { "application/json": { "examples": { "currency_not_supported": { "summary": "Moneda no admitida", "value": { "error": { "code": "currency_not_supported", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#currency_not_supported", "message": "Moneda no admitida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Cotización indicativa con vencimiento", "tags": [ "Pagos" ], "x-required-scope": "quotes:write" } }, "/v1/receiving-accounts": { "get": { "description": "Cuentas de la empresa para recibir fondos. Los campos que no apliquen a un tipo de cuenta llegan en null.", "operationId": "listReceivingAccounts", "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "account_number": null, "bank": "Banco de ejemplo", "bic": null, "br_code": null, "bre_b_key": null, "clabe": "999180000000000022", "currency": "MXN", "holder": "EMPRESA FICTICIA SA DE CV", "iban": null, "pix_key": null, "routing_number": null, "sort_code": null } ] }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Cuentas de la empresa para recibir fondos.", "items": { "$ref": "#/components/schemas/ReceivingAccount" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "accounts:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Cuentas para recibir", "tags": [ "Cuenta" ], "x-required-scope": "accounts:read" }, "post": { "description": "Abre una cuenta de la empresa en una moneda, si tu empresa tiene esa moneda activada. Hay una por moneda: si ya existe, responde 200 con esa misma cuenta y `already_existed: true`, nunca abre otra. Exige `Idempotency-Key` y firma. 201 si se abrió; 202 si aún no se confirma: repite con la misma clave.", "operationId": "createReceivingAccount", "parameters": [ { "description": "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.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "description": "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.", "example": "pedido-7731-intento-1", "maxLength": 200, "minLength": 8, "type": "string" } }, { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos. Se acepta hasta 300 s de diferencia.", "type": "string" } }, { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` de la petición con el secreto de firma de la llave.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivingAccountCreate" } } } }, "responses": { "200": { "content": { "application/json": { "example": { "account_number": "900000000012", "already_existed": true, "bank": "Banco de ejemplo", "bic": null, "br_code": null, "bre_b_key": null, "clabe": null, "currency": "USD", "holder": "EMPRESA FICTICIA SA DE CV", "iban": null, "pix_key": null, "routing_number": "999999999", "sort_code": null, "status": "active" }, "schema": { "$ref": "#/components/schemas/ReceivingAccountResult" } } }, "description": "Correcto." }, "201": { "content": { "application/json": { "example": { "account_number": "900000000012", "already_existed": false, "bank": "Banco de ejemplo", "bic": null, "br_code": null, "bre_b_key": null, "clabe": null, "currency": "USD", "holder": "EMPRESA FICTICIA SA DE CV", "iban": null, "pix_key": null, "routing_number": "999999999", "sort_code": null, "status": "active" }, "schema": { "$ref": "#/components/schemas/ReceivingAccountResult" } } }, "description": "Creado." }, "202": { "content": { "application/json": { "example": { "account_number": null, "already_existed": false, "bank": null, "bic": null, "br_code": null, "bre_b_key": null, "clabe": null, "currency": "USD", "holder": null, "iban": null, "pix_key": null, "routing_number": null, "sort_code": null, "status": "processing" }, "schema": { "$ref": "#/components/schemas/ReceivingAccountResult" } } }, "description": "Aceptado: el resultado final llega después." }, "400": { "content": { "application/json": { "examples": { "idempotency_key_invalid": { "summary": "Clave inválida", "value": { "error": { "code": "idempotency_key_invalid", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_invalid", "message": "Clave inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_required": { "summary": "Falta Idempotency-Key", "value": { "error": { "code": "idempotency_key_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_required", "message": "Falta Idempotency-Key", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": { "fields": { "amount": "Monto decimal inválido" } }, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "invalid_signature": { "summary": "Firma inválida", "value": { "error": { "code": "invalid_signature", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_signature", "message": "Firma inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "account_restricted": { "summary": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "value": { "error": { "code": "account_restricted", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_restricted", "message": "Tu cuenta tiene una restricción. Contacta a tu ejecutivo FITAL.", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "accounts:write" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "not_enabled": { "summary": "Falta la activación de esta función", "value": { "error": { "code": "not_enabled", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#not_enabled", "message": "Falta la activación de esta función", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "409": { "content": { "application/json": { "examples": { "idempotency_in_progress": { "summary": "Operación en curso", "value": { "error": { "code": "idempotency_in_progress", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_in_progress", "message": "Operación en curso", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "receiving_account_in_progress": { "summary": "Otra alta de esa moneda sigue en curso", "value": { "error": { "code": "receiving_account_in_progress", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#receiving_account_in_progress", "message": "Otra alta de esa moneda sigue en curso", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicto con el estado actual.", "headers": { "Retry-After": { "description": "Llega con `idempotency_in_progress`: segundos a esperar antes de repetir con la misma clave.", "schema": { "example": "1", "type": "string" } } } }, "413": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Cuerpo demasiado grande", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Cuerpo demasiado grande", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "El cuerpo pasa de 64 KB." }, "422": { "content": { "application/json": { "examples": { "currency_not_supported": { "summary": "Moneda no admitida", "value": { "error": { "code": "currency_not_supported", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#currency_not_supported", "message": "Moneda no admitida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "idempotency_key_reused": { "summary": "La clave ya se usó con otro cuerpo", "value": { "error": { "code": "idempotency_key_reused", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#idempotency_key_reused", "message": "La clave ya se usó con otro cuerpo", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "in_review": { "summary": "La operación está en revisión", "value": { "error": { "code": "in_review", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#in_review", "message": "La operación está en revisión", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } }, "receiving_account_rejected": { "summary": "No se pudo abrir la cuenta", "value": { "error": { "code": "receiving_account_rejected", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#receiving_account_rejected", "message": "No se pudo abrir la cuenta", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rechazada por una regla de negocio." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Abrir una cuenta para recibir", "tags": [ "Cuenta" ], "x-idempotent": true, "x-required-scope": "accounts:write" } }, "/v1/status": { "get": { "description": "Estado de pagos, cobros, webhooks y API para tu empresa. Acepta cualquier llave válida. `not_enabled` indica que tu empresa no tiene esa capacidad y `unknown` que no hay medición reciente.", "operationId": "getStatus", "responses": { "200": { "content": { "application/json": { "example": { "capabilities": [ { "id": "payments_mxn", "name": "Pagos MXN", "since": "2026-11-04T10:00:00.000Z", "status": "operational" }, { "id": "payments_pix", "name": "Pagos PIX", "since": null, "status": "not_enabled" } ], "updated_at": "2026-11-04T18:00:00.000Z" }, "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Estado por capacidad", "tags": [ "Sistema" ], "x-any-key": true } }, "/v1/wallets": { "get": { "description": "Las wallets de la empresa dueña de la llave, con su red y su saldo disponible. Sólo consulta: las wallets no se crean ni se modifican por API. Una red puede tener más de una wallet. La suma por moneda es lo que da `GET /v1/balances`, salvo redondeo al centavo. Lo apartado por compras con tarjeta se descuenta primero de la wallet con más saldo. Para recibir fondos usa `GET /v1/deposit-addresses`.", "operationId": "listWallets", "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "balances": [ { "available": "4200.00", "currency": "USD" } ], "chain": "base", "id": "wal_5f2c8e1ab37d4c60918e2d7f4a6b0c13" }, { "balances": [ { "available": "0.00", "currency": "USD" } ], "chain": "solana", "id": "wal_a94d03be6c1f47d2b8e05c7e12fd6a38" } ] }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Todas las wallets de la empresa, ordenadas por red.", "items": { "$ref": "#/components/schemas/Wallet" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "wallets:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Wallets de la empresa", "tags": [ "Cuenta" ], "x-required-scope": "wallets:read" } }, "/v1/webhook-endpoints": { "get": { "description": "Destinos de webhooks de la empresa, sólo para consultarlos. El alta, la edición, la baja, la rotación del secreto y la reactivación se hacen en el panel: v1 no tiene API para eso.", "operationId": "listWebhookEndpoints", "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "created_at": "2026-11-04T18:00:00.000Z", "events": [ "payment.completed", "payment.failed" ], "id": "3f0c2d1e-7a54-4b1f-9c0e-1a2b3c4d5e6f", "status": "active", "url": "https://empresa-ejemplo.com/webhooks/fital" } ] }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Destinos de webhooks de la empresa.", "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Correcto." }, "400": { "content": { "application/json": { "examples": { "invalid_request": { "summary": "Petición inválida", "value": { "error": { "code": "invalid_request", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_request", "message": "Petición inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Petición inválida." }, "401": { "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Credencial inválida", "value": { "error": { "code": "invalid_api_key", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#invalid_api_key", "message": "Credencial inválida", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "wrong_environment": { "summary": "La llave es de otro ambiente", "value": { "error": { "code": "wrong_environment", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#wrong_environment", "message": "La llave es de otro ambiente", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Credencial o firma inválida." }, "403": { "content": { "application/json": { "examples": { "account_not_active": { "summary": "La cuenta no está activa", "value": { "error": { "code": "account_not_active", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#account_not_active", "message": "La cuenta no está activa", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "forbidden_scope": { "summary": "La llave no tiene permiso para esta operación", "value": { "error": { "code": "forbidden_scope", "details": { "required_scope": "webhooks:read" }, "docs_url": "https://merchants.fital.xyz/docs/errores/#forbidden_scope", "message": "La llave no tiene permiso para esta operación", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "ip_not_allowed": { "summary": "IP no permitida para esta llave", "value": { "error": { "code": "ip_not_allowed", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#ip_not_allowed", "message": "IP no permitida para esta llave", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } }, "kyb_required": { "summary": "Tu empresa aún no está aprobada", "value": { "error": { "code": "kyb_required", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#kyb_required", "message": "Tu empresa aún no está aprobada", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": false } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Sin permiso para esta operación." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "summary": "Demasiadas peticiones", "value": { "error": { "code": "rate_limited", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#rate_limited", "message": "Demasiadas peticiones", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Demasiadas peticiones.", "headers": { "Retry-After": { "description": "Segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "summary": "Error interno", "value": { "error": { "code": "internal_error", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#internal_error", "message": "Error interno", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Error interno." }, "503": { "content": { "application/json": { "examples": { "service_unavailable": { "summary": "Servicio no disponible", "value": { "error": { "code": "service_unavailable", "details": {}, "docs_url": "https://merchants.fital.xyz/docs/errores/#service_unavailable", "message": "Servicio no disponible", "request_id": "0d482417a7134092bdf1278c9518bcbc", "retryable": true } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Servicio no disponible.", "headers": { "Retry-After": { "description": "Si viene, segundos a esperar antes de repetir.", "schema": { "example": "1", "type": "string" } } } } }, "security": [ { "llaveApi": [] } ], "summary": "Destinos de webhooks", "tags": [ "Webhooks" ], "x-required-scope": "webhooks:read" } } }, "servers": [ { "url": "https://widget.fital.xyz" } ], "webhooks": { "collection.expired": { "post": { "description": "El cobro venció sin pago. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_collection_expired", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1250.00", "currency": "MXN", "destination_amount": null, "external_ref": "pedido-7731", "id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW", "method": "spei", "status": "expired" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW", "sequence": 2, "type": "collection.expired" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataCollection" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `collection.expired`: El cobro venció sin pago.", "enum": [ "collection.expired" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "collection.expired", "tags": [ "Webhooks" ] } }, "collection.paid": { "post": { "description": "El cobro se pagó. En `efectivo`, la tienda ya confirmó el pago y el abono a tu cuenta llega después. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_collection_paid", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1250.00", "currency": "MXN", "destination_amount": null, "external_ref": "pedido-7731", "id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW", "method": "spei", "status": "paid" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "col_4hQvN8sLd1ZxK6tB2mYpR7cW", "sequence": 2, "type": "collection.paid" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataCollection" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `collection.paid`: El cobro se pagó. En `efectivo`, la tienda ya confirmó el pago y el abono a tu cuenta llega después.", "enum": [ "collection.paid" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "collection.paid", "tags": [ "Webhooks" ] } }, "deposit.in_review": { "post": { "description": "El depósito está en revisión. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_deposit_in_review", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1250.00", "concept": "Pedido 7731", "credited_amount": null, "credited_currency": null, "currency": "MXN", "id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "payer": { "address": null, "bank": "Banco de ejemplo", "clabe": "999180000000000022", "name": "CLIENTE FICTICIO SA DE CV", "rfc": "XAXX010101000" }, "receipt_url": null, "received_at": "2026-11-04T18:00:00.000Z", "reference": "7731", "status": "in_review", "tracking_key": "CLAVE-DE-RASTREO-DEMO" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "sequence": 2, "type": "deposit.in_review" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataDeposit" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `deposit.in_review`: El depósito está en revisión.", "enum": [ "deposit.in_review" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "deposit.in_review", "tags": [ "Webhooks" ] } }, "deposit.received": { "post": { "description": "El dinero ya está acreditado. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_deposit_received", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1250.00", "concept": "Pedido 7731", "credited_amount": "1250.00", "credited_currency": "MXN", "currency": "MXN", "id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "payer": { "address": null, "bank": "Banco de ejemplo", "clabe": "999180000000000022", "name": "CLIENTE FICTICIO SA DE CV", "rfc": "XAXX010101000" }, "receipt_url": null, "received_at": "2026-11-04T18:00:00.000Z", "reference": "7731", "status": "received", "tracking_key": "CLAVE-DE-RASTREO-DEMO" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "sequence": 2, "type": "deposit.received" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataDeposit" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `deposit.received`: El dinero ya está acreditado.", "enum": [ "deposit.received" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "deposit.received", "tags": [ "Webhooks" ] } }, "deposit.returned": { "post": { "description": "El depósito se devolvió. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_deposit_returned", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1250.00", "concept": "Pedido 7731", "credited_amount": null, "credited_currency": null, "currency": "MXN", "id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "payer": { "address": null, "bank": "Banco de ejemplo", "clabe": "999180000000000022", "name": "CLIENTE FICTICIO SA DE CV", "rfc": "XAXX010101000" }, "receipt_url": null, "received_at": "2026-11-04T18:00:00.000Z", "reference": "7731", "status": "returned", "tracking_key": "CLAVE-DE-RASTREO-DEMO" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "dpt_7bTcF2qXe9WmL4sD1nHrY6vK", "sequence": 2, "type": "deposit.returned" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataDeposit" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `deposit.returned`: El depósito se devolvió.", "enum": [ "deposit.returned" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "deposit.returned", "tags": [ "Webhooks" ] } }, "payment.canceled": { "post": { "description": "El pago se canceló. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_payment_canceled", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1500.00", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "failure_code": null, "final_amount": null, "final_currency": null, "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "canceled", "updated_at": "2026-11-04T18:01:30.000Z" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "sequence": 2, "type": "payment.canceled" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataPayment" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `payment.canceled`: El pago se canceló.", "enum": [ "payment.canceled" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "payment.canceled", "tags": [ "Webhooks" ] } }, "payment.completed": { "post": { "description": "El pago se confirmó. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_payment_completed", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1500.00", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "failure_code": null, "final_amount": "1500.00", "final_currency": "MXN", "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "completed", "updated_at": "2026-11-04T18:01:30.000Z" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "sequence": 2, "type": "payment.completed" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataPayment" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `payment.completed`: El pago se confirmó.", "enum": [ "payment.completed" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "payment.completed", "tags": [ "Webhooks" ] } }, "payment.failed": { "post": { "description": "El pago no se hizo y no queda dinero en tránsito. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_payment_failed", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1500.00", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "failure_code": "insufficient_funds", "final_amount": null, "final_currency": null, "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "failed", "updated_at": "2026-11-04T18:01:30.000Z" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "sequence": 2, "type": "payment.failed" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataPayment" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `payment.failed`: El pago no se hizo y no queda dinero en tránsito.", "enum": [ "payment.failed" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "payment.failed", "tags": [ "Webhooks" ] } }, "payment.in_review": { "post": { "description": "El pago está en revisión. No lo repitas. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_payment_in_review", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1500.00", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "failure_code": null, "final_amount": null, "final_currency": null, "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "in_review", "updated_at": "2026-11-04T18:01:30.000Z" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "sequence": 2, "type": "payment.in_review" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataPayment" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `payment.in_review`: El pago está en revisión. No lo repitas.", "enum": [ "payment.in_review" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "payment.in_review", "tags": [ "Webhooks" ] } }, "payment.processing": { "post": { "description": "El pago se aceptó y sigue en curso, o se reabrió. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_payment_processing", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1500.00", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "failure_code": null, "final_amount": null, "final_currency": null, "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "processing", "updated_at": "2026-11-04T18:01:30.000Z" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "sequence": 2, "type": "payment.processing" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataPayment" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `payment.processing`: El pago se aceptó y sigue en curso, o se reabrió.", "enum": [ "payment.processing" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "payment.processing", "tags": [ "Webhooks" ] } }, "payment.returned": { "post": { "description": "El pago se devolvió. Puede llegar después de `payment.completed`. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_payment_returned", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "amount": "1500.00", "currency": "MXN", "destination_currency": "MXN", "external_ref": "pedido-7731", "failure_code": null, "final_amount": "1500.00", "final_currency": "MXN", "id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "status": "returned", "updated_at": "2026-11-04T18:01:30.000Z" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "pay_6nRtY1wKs3QzD8cL5mVhF2gB", "sequence": 2, "type": "payment.returned" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataPayment" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `payment.returned`: El pago se devolvió. Puede llegar después de `payment.completed`.", "enum": [ "payment.returned" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "payment.returned", "tags": [ "Webhooks" ] } }, "security.ip_allowlist.changed": { "post": { "description": "Cambió la lista de IP de una llave de producción. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_security_ip_allowlist_changed", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "added": [ "198.51.100.10/32" ], "key": "3f0c2d1e-7a54-4b1f-9c0e-1a2b3c4d5e6f", "removed": [] }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "3f0c2d1e-7a54-4b1f-9c0e-1a2b3c4d5e6f", "sequence": 2, "type": "security.ip_allowlist.changed" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataIpAllowlist" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `security.ip_allowlist.changed`: Cambió la lista de IP de una llave de producción.", "enum": [ "security.ip_allowlist.changed" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "security.ip_allowlist.changed", "tags": [ "Webhooks" ] } }, "system.egress_ips.changing": { "post": { "description": "Cambiará una IP de salida de webhooks. Actualiza tu firewall antes de `effective_at`. Verifica la firma antes de usar el cuerpo.", "operationId": "webhook_system_egress_ips_changing", "parameters": [ { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "in": "header", "name": "X-Fital-Signature", "required": true, "schema": { "description": "Firma `v1=` del cuerpo. Durante una rotación trae dos, separadas por coma: basta con que coincida una.", "type": "string" } }, { "description": "Hora Unix en segundos con la que se firmó este intento.", "in": "header", "name": "X-Fital-Timestamp", "required": true, "schema": { "description": "Hora Unix en segundos con la que se firmó este intento.", "type": "string" } }, { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "in": "header", "name": "X-Fital-Event-Id", "required": true, "schema": { "description": "Identificador del evento. No va firmado: para ignorar repetidos usa el `id` del cuerpo, ya con la firma verificada.", "type": "string" } }, { "description": "Identificador de esta entrega.", "in": "header", "name": "X-Fital-Delivery-Id", "required": true, "schema": { "description": "Identificador de esta entrega.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "api_version": "2026-11-01", "created_at": "2026-11-04T18:01:30.000Z", "data": { "change": "added", "effective_at": "2026-11-20T00:00:00.000Z", "ip": "198.51.100.10" }, "id": "evt_5mPqW2xZr8TnC1vH7kLdS4bJ", "resource_id": "egr_0d482417a7134092", "sequence": 2, "type": "system.egress_ips.changing" }, "schema": { "additionalProperties": false, "properties": { "api_version": { "description": "Versión con que se generó el evento.", "type": "string" }, "created_at": { "description": "Fecha de creación.", "example": "2026-11-04T18:00:00.000Z", "format": "date-time", "type": [ "string", "null" ] }, "data": { "$ref": "#/components/schemas/EventDataEgressIps" }, "id": { "description": "Identificador del evento, con prefijo `evt_`. Va firmado: úsalo para ignorar repetidos.", "type": "string" }, "resource_id": { "description": "Recurso al que se refiere.", "type": "string" }, "sequence": { "description": "Orden dentro del recurso: un valor mayor es más reciente.", "type": "integer" }, "type": { "description": "Tipo de evento. `system.egress_ips.changing`: Cambiará una IP de salida de webhooks. Actualiza tu firewall antes de `effective_at`.", "enum": [ "system.egress_ips.changing" ], "type": "string" } }, "required": [ "id", "resource_id", "sequence", "api_version", "created_at", "type", "data" ], "type": "object" } } } }, "responses": { "200": { "description": "Cualquier `2xx` confirma la entrega. Otro código o un corte se reintenta." } }, "summary": "system.egress_ips.changing", "tags": [ "Webhooks" ] } } } }