Cuenta de prueba

La cuenta de prueba es un ambiente por empresa con el mismo contrato que producción: guarda estado, aplica idempotencia real y entrega webhooks firmados. El dinero y los bancos no existen ahí. Toda respuesta JSON lleva livemode: false. Para empezar, sigue el inicio rápido.

Crear la llave de pruebaCopiar enlace

El panel está en merchants.fital.xyz: entran las empresas con KYB aprobado en empresa.fital.xyz. Si tu empresa aún no tiene cuenta, regístrala ahí y completa el KYB. Con KYB aprobado, entras y creas tu llave sk_test_fital_…. Es automático. Sin KYB aprobado la respuesta es 403 kyb_required, sin vía manual. La llave y su secreto de firma se muestran una sola vez, y la llave caduca a los 90 días.

Al revocar una llave de prueba, las escrituras se rechazan al instante; una lectura puede seguir pasando hasta 30 segundos.

Hacer un pago ficticioCopiar enlace

No hay botón de pago en el panel. Usa las muestras del inicio rápido, o el script para Node 22 de la pantalla Sandbox, que ya trae el beneficiario de prueba. Así pruebas también la firma de la petición.

En unos 30 segundos el pago termina y llega payment.completed a tu destino. Lo ves en las pantallas Webhooks y Registros de API.

Qué se simulaCopiar enlace

Sólo SPEI en MXN:

• Beneficiarios: rail debe ser mxn_spei, la CLABE debe empezar con 999 y el titular debe incluir la palabra FICTICIO. Otro riel responde 403 rail_not_enabled. Una CLABE o un titular reales responden 422 sandbox_real_account_rejected.
• Cobros: con el método spei, que pide firstName, lastName y email en payer, igual que dice payer_fields, y con efectivo, que no pide nada de quien paga y responde una referencia ficticia. Sin esos campos, spei responde 400 invalid_request. Otro método responde 422 method_unavailable. La cuenta de prueba simula efectivo aunque tu empresa aún no lo haya pedido a FITAL para producción.
• Catálogo latam: GET /sandbox/v1/latam/countries responde países ficticios con available: false, y GET /sandbox/v1/latam/countries/{country}/entities un banco ficticio. Sirven para leer la forma de la respuesta: el alta latam no procede aquí.
• Saldos: ficticios, en MXN y USD. El saldo USD sólo se ve: un pago o una cotización en otra moneda que no sea MXN responde 422 currency_not_supported.
• Wallets: dos ficticias, en base y solana. Salen del mismo saldo ficticio: MXN no vive en una wallet.
• Cuentas para recibir: POST /sandbox/v1/receiving-accounts abre cuentas ficticias que no reciben dinero. Abre en USD, EUR, BRL, GBP y COP sin pedir activación.
• Direcciones de depósito: son ficticias y no reciben dinero.
• Cotizaciones: con tipo de cambio ficticio. Si el débito supera max_source_amount, el pago responde 409 quote_changed, sin efecto, igual que en producción.

Datos ficticios incluidosCopiar enlace

La cuenta nace con saldo ficticio y beneficiarios ficticios, cada uno con un escenario asignado; los ves en la pantalla Sandbox. Ningún dato se copia de producción.

EscenariosCopiar enlace

X-Fital-Scenario manda sobre el escenario del beneficiario. Sin ninguno de los dos, el pago sigue el camino feliz. Ver la lista en Ambientes.

Estos tiempos no anticipan los de producción.

Avanzar un pagoCopiar enlace

POST /sandbox/v1/payments/{id}/advance lleva un pago a completed, failed, returned o in_review sin esperar, y emite su evento firmado. Exige Idempotency-Key y firma. Sigue las reglas de un pago real: una transición imposible responde 409 sandbox_invalid_transition. Esta ruta no existe en producción.

Webhooks simuladosCopiar enlace

POST /sandbox/v1/webhooks/trigger emite un evento firmado a tus destinos de prueba, con los mismos encabezados y el mismo calendario de reintentos que producción. data tiene la forma real de su tipo, con datos ficticios, más simulated: true y livemode: false. Los destinos se dan de alta en el panel y sólo aceptan HTTPS público. Esta ruta tampoco existe en producción. El contrato de este ambiente, con estas dos rutas, está en openapi.sandbox.json. Para probar en tu máquina usa el inicio rápido de webhooks.

Un pago de prueba no se reabre. Para practicar ese retroceso, emite payment.canceled y después payment.processing con el mismo resource_id: sequence crece por recurso.

Cada destino recibe hasta 2 entregas simultáneas, y la cola guarda hasta 500 pendientes por destino y 1,500 por empresa. Lo que no cabe queda skipped, sin entrega: el evento sigue en GET /sandbox/v1/events.

GET /sandbox/v1/meta/egress-ips responde una lista vacía: este ambiente no publica IP de salida. La lista de producción no aplica aquí.

Reinicio de datosCopiar enlace

Desde el panel. Borra los datos de tu empresa y restaura la semilla; conserva llaves y destinos. Hasta 5 veces al día.

LímitesCopiar enlace

SaludCopiar enlace

GET /sandbox/v1/health mide sólo este ambiente, no producción. Ver Salud y estado.

Qué no prueba este ambienteCopiar enlace

Tiempos reales de cada banco, comisiones y tipos de cambio reales, otros rieles, ni la duración de una revisión de cumplimiento.

Aquí una Idempotency-Key vencida se borra: pasados 7 días, otro cuerpo con esa clave ya no responde 422 idempotency_key_reused, como sí en producción.

Tampoco prueba una lectura de producción: un pago en curso siempre responde freshness.status en current.

Errores comunesCopiar enlace

• 401 wrong_environment: usar aquí una llave de otro ambiente, como sk_live_fital_… o la llave pública del simulador.
• sandbox_real_account_rejected, sandbox_limit y sandbox_invalid_transition: ver Errores.
• 401 invalid_signature: firmar la ruta con el prefijo /sandbox. Se firma siempre /v1/.... Ver Autenticación.

Qué sigueCopiar enlace

Lista para producción.

Ver esta página en Markdown