FITALAPI

Ambientes

Simulador público, cuenta de prueba y producción, y cómo pasar de uno a otro.

Hay tres ambientes con el mismo contrato. Cambiar de ambiente es cambiar la base y la llave, sin tocar tu código.

Simulador públicoCuenta de pruebaProducción
Basehttps://widget.fital.xyz/explorar/v1https://widget.fital.xyz/sandbox/v1https://widget.fital.xyz/v1
CuentaNo hace faltaPanel y KYB aprobado, automáticoPanel, KYB aprobado e inscripción de FITAL
LlavePública de pruebask_test_fital_…, por empresask_live_fital_…, con login reciente
DineroNuncaNunca; saldos ficticiosReal
Estado entre llamadasNo guardaSí, por empresaReal
IdempotenciaNo realRealReal
WebhooksScript localSimulados y firmadosReales
IP permitidasNo aplicaOpcionalObligatoria
Firma de webhookVector públicoObligatoriaObligatoria
X-Fital-ScenarioSíSíNo aplica
Reinicio de datosNo hace faltaSí, desde el panelNo existe
RielesTodos, sólo la formaSPEI con CLABE 999; otro riel da 403 rail_not_enabledLos habilitados a tu empresa
Límite de peticiones10 por segundo por IP5 por segundo por llaveVer Límites
TiemposInmediatosAcortadosReales de cada banco
Comisiones y tipos de cambioEjemploFicticiosReales
Revisiones y cumplimientoNoSimulados por escenario, con tiempos ficticiosReales; su duración no es predecible

La cuenta de prueba es automática con KYB aprobado. Producción requiere además la inscripción de FITAL: sin ella, el panel responde 403 live_not_enabled al crear una llave sk_live_fital_…. Las respuestas de ambos simuladores llevan X-Fital-Environment: sandbox, y las de la cuenta de prueba, livemode: false en su JSON.

Qué no simula el simulador público

Estado entre llamadas, idempotencia real, saldos, tiempos, límites reales, comisiones, tipos de cambio, firmas ni KYB. Prueba la forma de tu integración, no su conducta. Para eso existe la cuenta de prueba.

Tres diferencias concretas. Una petición que no cumple el esquema, también si falta Idempotency-Key o es muy corta, responde 422 con invalid_request y sin señalar un campo, cuando la API real responde 400 con el detalle. Un escenario que no aplica a la operación responde 404 en formato application/problem+json. Y request_id del cuerpo de un error es fijo: el valor de cada petición viene en el encabezado X-Request-Id. Tu código de producción debe esperar siempre la forma de Errores.

Escenarios

Envía X-Fital-Scenario: <nombre> para elegir la respuesta.

EscenarioRespuestaTermina enEnseña a manejar
payment_completed202 processingPago completedTermina en completed.
payment_failed202 processingPago failedEl pago no se hizo y no queda dinero en tránsito. Si no ves failed, no repitas.
payment_returned202 processingPago returnedDevolución después de completed.
insufficient_funds422 insufficient_fundsNo aplicaSaldo insuficiente.
invalid_beneficiary422 invalid_beneficiaryNo aplicaCuenta destino inválida.
idempotency_key_reused422 idempotency_key_reusedNo aplicaMisma clave con otro cuerpo.
pix_not_enabled403 not_enabledNo aplicaPIX sin activación vigente para tu empresa.
invalid_request400 invalid_requestNo aplicaErrores por campo en details.fields.
invalid_api_key401 invalid_api_keyNo aplicaLlave mala o revocada.
forbidden_scope403 forbidden_scopeNo aplicaFalta un scope.
kyb_required403 kyb_requiredNo aplicaEmpresa sin aprobación.
ip_not_allowed403 ip_not_allowedNo aplicaIP fuera de la lista de la llave.
not_found404 not_foundNo aplicaRecurso ajeno o inexistente.
rate_limited429 rate_limitedNo aplicaEsperar lo que indique Retry-After.
service_unavailable503 service_unavailableNo aplicaReintento con espera.
status_degraded200No aplicaPausar sólo lo afectado.

Respuesta es lo que devuelve la petición, y Termina en es el estado final del recurso. No aplica significa que la respuesta ya es el resultado. Un pago siempre nace en 202 processing: el final no llega en esa respuesta. En el simulador público lo ves al consultar GET /v1/payments/{id} con el mismo escenario. En la cuenta de prueba, el pago avanza solo hasta ahí y te llega por webhook.

Sin encabezado obtienes el camino feliz: 2xx, y en un pago, processing.

Estos escenarios existen sólo en la cuenta de prueba:

EscenarioRespuestaTermina enEnseña a manejar
payment_in_review202 processingPago completedRevisión que termina en completed.
payment_in_review_failed202 processingPago failedRevisión que termina en failed. El tiempo real de una revisión no es predecible.
payment_held422 in_reviewNo aplicaSin pay_. Repite con la misma clave tras levantarse: crea un pago.
payment_uncertain202 processingPago completedResultado sin confirmar: la misma clave repite la respuesta y otra clave recibe 409 payment_in_flight.
account_restricted403 account_restrictedNo aplicaCuenta restringida, sin pay_.
collection_paid201 pendingCobro paidCobro que se paga, con su evento firmado.
collection_expired201 pendingCobro expiredCobro que vence, con su evento firmado.
receiving_account_not_enabled403 not_enabledNo aplicaMoneda sin activación para tu empresa. No abre nada.
receiving_account_processing202 processingundefined activeAlta sin confirmar: no devuelve datos. Repite sin el escenario con la misma clave y se abre.
deposit_received201 activeDepósito receivedDepósito con pagador ficticio, con su evento firmado.

collection_paid y collection_expired se envían al crear el cobro, y deposit_received al crear la dirección de depósito. Lee el cobro con GET /sandbox/v1/collections/{id} y el depósito con GET /sandbox/v1/deposits; también llegan por webhook.

Errores comunes

  • 401 wrong_environment: la llave no es de esa base. En el simulador público, sk_test_fital_… también recibe este error; su base es https://widget.fital.xyz/sandbox/v1.
  • Confiar en un 200 del simulador público como prueba de que tu flujo funciona. Sólo prueba la forma.

Qué sigue

Cuenta de prueba y Lista para producción.

Ver esta página en Markdown

Cobertura

Países, monedas y rieles disponibles, y lo que puedes hacer en cada uno.

Cuenta de prueba

Tu ambiente propio con datos ficticios, escenarios y webhooks simulados.

En esta página

Qué no simula el simulador públicoEscenariosErrores comunesQué sigue