Payouts

Un payout es el riel inverso del cobro: en vez de que el dinero entre a la cuenta del comercio, POST /v1/payouts ordena que salga de ella hacia una CLABE por SPEI — pagar a un proveedor, dispersar una nómina, o liquidar a un sub-comercio de Winal Connect. Mismo principio sin custodia que el resto de la API (ADR-0001): el dinero sale de la cuenta STP del propio comercio, firmado con su propia llave; Winal solo orquesta la orden y lleva el ledger.

Ordena un payout

curl -s https://api.winal.com.mx/v1/payouts \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "clabe": "646180157000000004",
    "beneficiary_name": "Proveedor Docs SA de CV",
    "amount_minor": 250000,
    "currency": "MXN",
    "concepto": "pago de prueba docs"
  }'

{
  "id": "b4e5115a-e401-48b6-9b4d-e80b7a915748",
  "object": "payout",
  "clabe": "646180157000000004",
  "beneficiary_name": "Proveedor Docs SA de CV",
  "amount_minor": 250000,
  "currency": "MXN",
  "concepto": "pago de prueba docs",
  "reference": "2441786",
  "status": "processing",
  "connector_key": "sim",
  "livemode": false,
  "created_at": "2026-07-08T06:46:43.157657+00:00"
}

Idempotency-Key es obligatorio (regla 8: un reintento sin la llave, tras un timeout de red, dispersaría el dinero DOS veces). reference es opcional — si lo omites, Winal genera un folio numérico corto. beneficiary_rfc es opcional. connector_key también es opcional: por defecto stp (el riel de producción); usa "connector_key": "sim" mientras pruebas sin cuenta STP. provider_ref, tracking_key y failure_reason no aparecen todavía en esta respuesta — Winal omite los campos en null — y se llenan cuando el Worker ejecuta la orden contra el conector, segundos después.

Estados de un payout

processing se resuelve solo con evidencia del proveedor (regla 5): una confirmación en línea al ordenar, o la consulta de estado del poller — nunca por timeout local. En Sim, una CLABE cualquiera queda processing indefinidamente (esperando evidencia real); dos CLABEs reservadas existen para ejercitar los desenlaces sin esperar:

Errores de payouts

Idempotencia: mismos códigos y comportamiento que el resto de la API — ver Errores.

STP real vs. Sim

El conector STP (el riel de producción — Sistema de Transferencias y Pagos, participante directo de SPEI) está construido contra la forma documentada de su API: registro de orden firmado con RSA-SHA256, consulta de estado, y reporte de conciliación. Está gated por trámite del dueño: contrato con STP, alta de la cuenta empresa del comercio y su llave privada. Sin esas credenciales, cualquier payout con connector_key: "stp" (el default) falla de inmediato con failure_reason: "STP_MISSING_CREDENTIALS: Faltan credenciales STP del comercio...". Usa "connector_key": "sim" para probar el ciclo completo hoy, sin cuenta STP.

Endpoints