Retiros

Envía dinero a un beneficiario por SPEI o tarjeta de débito, y sigue el estado hasta su liquidación.

Los retiros (payouts) a beneficiarios se procesan por el mismo endpoint unificado /process/ que los pagos, usando operation_type: "withdrawal".

Disponibilidad. Los retiros vía API Direct actualmente solo están disponibles para beneficiarios en México.

Métodos de transferencia disponibles

Aspecto	SPEI	Tarjeta de débito
Tiempo de procesamiento	Instantáneo (segundos)	Instantáneo (segundos)
Disponibilidad	Horario bancario	24/7
Tipo de cuenta	CLABE de 18 dígitos	Tarjeta de 16 dígitos
Ideal para	Beneficiarios con CLABE, montos mayores	Beneficiarios que solo tienen tarjeta

Geolocalización obligatoria para México. Los campos metadata.latitude y metadata.longitude son obligatorios para procesar retiros en México. Omitirlos o enviar coordenadas erróneas resulta en una transacción fallida.

Paso 1: haz la petición de retiro

Envía tu petición al endpoint /process/ con operation_type en "withdrawal":

Campo	Descripción
`operation_type`	Siempre `"withdrawal"` para operaciones de payout.
`amount`	Monto del retiro en la moneda especificada.
`currency`	Código de moneda (actualmente solo se soporta `"MXN"`).
`client_reference`	Tu identificador de referencia interno para este retiro.
`transfer_method`	`"SPEI"` o `"DEBIT_CARD"`.
`beneficiary`	Objeto con la información completa del beneficiario.
`metadata`	Información adicional requerida (debe incluir `latitude` y `longitude`).

El objeto beneficiary especifica quién recibe los fondos y cómo:

Campo	Descripción
`account`	Cuenta destino (CLABE de 18 dígitos para SPEI, o tarjeta de 16 dígitos para tarjeta de débito).
`name`	Nombre legal completo del beneficiario, tal como aparece en su cuenta o tarjeta.
`rfc`	RFC del beneficiario.
`curp`	CURP del beneficiario (18 caracteres alfanuméricos).
`institution`	Código de institución bancaria. Ver Referencia bancaria.
`email`	Correo del beneficiario para notificaciones y registro.

Requisito de RFC/CURP. Debes proporcionar rfc o curp en cada petición de retiro. Si no tienes disponible alguno de los dos, envía "ND" (No Disponible) como valor en ese campo.

Códigos de institución para pruebas en Stage. Usa 97846 como institution para simular tanto retiros SPEI como retiros por tarjeta de débito en Stage. Para producción, usa los códigos reales de la Referencia bancaria (por ejemplo, 40012 ya es un código real de producción, no debe usarse para pruebas).

Ejemplo confirmado y funcional, transferencia SPEI:

{
  "operation_type": "withdrawal",
  "amount": 20.00,
  "currency": "MXN",
  "client_reference": "payout-001",
  "transfer_method": "SPEI",
  "description": "Commission payment",
  "beneficiary": {
    "account": "846180000400000001",
    "name": "Ana María González",
    "rfc": "GOAN850315AB2",
    "institution": "97846",
    "email": "ana.gonzalez@email.com"
  },
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775"
  }
}

curl -X POST https://stage.tonder.io/api/v1/process/ \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "withdrawal",
    "amount": 20.00,
    "currency": "MXN",
    "client_reference": "payout-001",
    "transfer_method": "SPEI",
    "description": "Commission payment",
    "beneficiary": {
      "account": "846180000400000001",
      "name": "Ana María González",
      "rfc": "GOAN850315AB2",
      "institution": "97846",
      "email": "ana.gonzalez@email.com"
    },
    "metadata": {
      "latitude": "22.8870221",
      "longitude": "-109.911775"
    }
  }'

Paso 2: maneja la respuesta

Ante una petición exitosa, la API devuelve un acuse de recibo inmediato:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "operation_type": "withdrawal",
  "status": "Pending",
  "amount": 20.00,
  "currency": "MXN",
  "client_reference": "payout-001",
  "created_at": "2024-07-26T10:30:00Z",
  "status_code": 201
}

Campo	Descripción
`id`	Identificador único de la transacción, guárdalo para monitorear el progreso.
`operation_type`	Confirma que es una operación de retiro.
`status`	Estado actual de la transacción (inicialmente `Pending`).
`amount`	Monto del retiro, tal como se envió.
`currency`	Código de moneda.
`client_reference`	Tu identificador de referencia interno.
`created_at`	Timestamp ISO 8601 de creación del retiro.
`status_code`	Código HTTP (201 para creación exitosa).

Paso 3: consulta el estado de la transacción

Los retiros son operaciones asíncronas. Usa el id de la respuesta para consultar el estado en el endpoint GET /api/v1/transactions/{id}/, o monitorea vía webhooks.

A medida que el retiro avanza, pasa por distintos estados:

Estado	Tipo	Descripción	Antes
`Pending`	Inicial	La solicitud se recibió y está en cola o en espera.	`PENDING`, `ON_HOLD`
`Processing`	Intermedio	La solicitud fue enviada al banco o proveedor de pago.	`SENT_TO_PROVIDER`
`Success`	Éxito	La transferencia se completó con éxito.	`PAID_FULL`
`Declined`	Terminal	El retiro fue rechazado (por ejemplo, cuenta inválida).	`REJECTED`
`Cancelled`	Terminal	El retiro fue cancelado.	`CANCELED`
`Failed`	Terminal	El retiro falló.	`FAILED`

Estados renombrados. Los retiros ahora usan el mismo vocabulario de estados que los pagos. Si tu integración esperaba los nombres anteriores (PENDING, SENT_TO_PROVIDER, PAID_FULL, REJECTED, CANCELED, FAILED), actualízala con la columna "Antes" de la tabla.

Webhooks

Los webhooks de retiros por API Direct siguen el mismo payload plano que los webhooks de pagos, con estas diferencias:

Campo	Diferencia
`operation_type`	`"withdrawal"`.
`transfer_method_type`	Se usa en lugar de `payment_method_type` (`SPEI` o `DEBIT_CARD`).
`event_type`	Usa el prefijo `withdrawal_` (por ejemplo, `withdrawal_Pending`, `withdrawal_Success`).
`provider`	`"STP"`, el riel bancario que liquida el retiro.

Se generan exactamente dos webhooks por retiro: primero una notificación Pending, luego una notificación terminal (Success, Declined o Failed).

Pending

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "operation_type": "withdrawal",
  "amount": "20",
  "currency": "MXN",
  "client_reference": "payout-001",
  "status": "Pending",
  "provider": "STP",
  "transfer_method_type": "SPEI",
  "created": "2026-05-21T19:15:32.029134Z",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "external_id": "payout-001"
  },
  "event_type": "withdrawal_Pending",
  "action": "MODIFY"
}

Success

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "operation_type": "withdrawal",
  "amount": "20",
  "currency": "MXN",
  "client_reference": "payout-001",
  "status": "Success",
  "provider": "STP",
  "transfer_method_type": "SPEI",
  "created": "2026-05-21T19:20:47.029134Z",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "external_id": "payout-001"
  },
  "event_type": "withdrawal_Success",
  "action": "MODIFY"
}

Declined

{
  "id": "c7b14546-84bd-4a81-89fb-3dc660f47011",
  "operation_type": "withdrawal",
  "amount": "60",
  "currency": "MXN",
  "client_reference": "card-payout-002",
  "status": "Declined",
  "provider": "STP",
  "transfer_method_type": "SPEI",
  "created": "2026-05-21T19:20:47.029134Z",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "external_id": "card-payout-002"
  },
  "event_type": "withdrawal_Declined",
  "action": "MODIFY"
}

Failed

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "operation_type": "withdrawal",
  "amount": "75",
  "currency": "MXN",
  "client_reference": "card-payout-003",
  "status": "Failed",
  "provider": "STP",
  "transfer_method_type": "SPEI",
  "created": "2026-05-21T19:20:47.029134Z",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "external_id": "card-payout-003"
  },
  "event_type": "withdrawal_Failed",
  "action": "MODIFY"
}

Monitoreo recomendado: usa webhooks para recibir actualizaciones de estado en tiempo real. Como alternativa, puedes hacer polling con el endpoint de estado de transacción.

Consulta tu saldo

Antes de dispersar, verifica el saldo disponible:

curl https://stage.tonder.io/api/v1/withdrawals/balance \
  -H "Authorization: Token YOUR_API_KEY"

curl https://app.tonder.io/api/v1/withdrawals/balance \
  -H "Authorization: Token YOUR_API_KEY"

{
  "message": "Data retrieved successfully",
  "current_balance": "32894.55"
}

Un retiro por más del saldo disponible se rechaza. El esquema del endpoint está en la Referencia API.

Retiros

Paso 1: haz la petición de retiro

Paso 2: maneja la respuesta

Paso 3: consulta el estado de la transacción

Webhooks

Consulta tu saldo

Siguientes pasos

Resumen de API Direct

Webhooks

En esta página