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