Modo de pruebas

MODO PRUEBA

Con una clave sk_test_… y el conector Sim activo puedes probar el flujo completo — tarjeta, SPEI, CoDi y OXXO — sin dar de alta ninguna cuenta real. Nada de esto mueve dinero de verdad.

Tokens de tarjeta (tok_sim_*)

Tabla completa de SimConnector — el token va en paymentToken al confirmar con paymentMethod: "card":

TokenResultado
tok_sim_okÉxito; captura inmediata.
tok_sim_authAutoriza sin capturar (flujo auth/capture separado; requiere POST /v1/payment_intents/{id}/capture después).
tok_sim_3dsPide acción: requires_action con next_action.type = "redirect".
tok_sim_insufficientFondos insuficientes — decline duro.
tok_sim_fraudSospecha de fraude — decline duro.
tok_sim_issuer_downEmisor caído — decline suave (reintentable con otro intento).
tok_sim_provider_500Error genérico del proveedor.
tok_sim_badcredsError de configuración (credenciales inválidas del conector).
tok_sim_slowÉxito (como tok_sim_ok) tras ~2 s de retraso — útil para observar el estado processing en vivo.
cualquier otro valorSe trata como tok_sim_ok.
Regla adicional, sin importar el token
Un monto cuyos dos últimos dígitos (los centavos) sean 99 siempre rechaza con decline duro (código do_not_retry) — útil para probar tu manejo de errores sin memorizar un token específico. Ej.: 84999 centavos falla siempre.

Simular pagos entrantes (SPEI, CoDi, OXXO)

Estos métodos son "push": el pagador paga fuera de tu app (transferencia, escaneo de QR, caja OXXO) y Winal se entera por el proveedor. En modo prueba, tú simulas ese aviso:

  1. Confirma el intent con el método push (spei, codi u oxxo) — queda en requires_action.
  2. Obtén el provider_ref del intento: GET /v1/payment_intents/{id}?expand=attempts → attempts[0].provider_ref.
  3. Simula el pago: desde el portal (Probar un cobro → Simular pago entrante) o directo contra el endpoint de administración.
bash · endpoint admin (X-Admin-Key, no Bearer)
curl -s https://api.winal.com.mx/admin/tenants/$TENANT_ID/simulate-inbound \
  -H "X-Admin-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider_ref": "sim_rtp_4af1c02e9b3d4f4e8f0a1b2c3d4e5f60" }'

Este endpoint vive bajo /admin/* (protegido con X-Admin-Key, la clave de tu portal — no tu clave sk_test_): es una herramienta de operador, no parte de la API pública que integra el POS. Tras simular, el Worker recibe el aviso igual que uno real y transiciona el intent con evidencia; espera el webhook o vuelve a consultar el intent.

DiMo
No lo pruebes esperando que confirme: hoy siempre falla en confirm (ver Métodos de pago → DiMo) — limitación conocida de fase 0, no un problema de tu integración.

Demo: Antech POS

/demo/pos.html es una demo navegable que usa winal.js de verdad contra tu backend local: pega tu clave sk_test_…, crea el intent, confirma con el kit público, y simula el pago entrante para los métodos push — todo desde el navegador, sin escribir código.

Checklist antes de producción

  • Credenciales live del proveedor guardadas en el portal, y clave sk_live_… generada.
  • Webhook registrado en HTTPS, con verificación de firma (Gateway-Signature) y dedupe por event_id.
  • Idempotency-Key persistido junto a la venta en tu sistema, para reintentos seguros ante timeouts.
  • Tu UI maneja requires_action para los métodos que uses (QR CoDi, CLABE SPEI, referencia OXXO).
  • Una prueba con dinero real de bajo monto — los sandbox de los proveedores mexicanos divergen del comportamiento real.
  • Hoy solo MXN está soportado end-to-end (el conector Sim rechaza cualquier otra moneda); no asumas multi-moneda todavía.
  • Las recargas de tiempo aire (POST /v1/recharges) solo operan hoy en modo prueba: con una llave sk_live_ el endpoint se rechaza con recharge.livemode_unsupported hasta que se conecte un agregador real.