Retiros

Los retiros (payouts) envían dinero de tu saldo a la CLABE de 18 dígitos de un beneficiario por SPEI, o a una tarjeta de débito de 16 dígitos. Están disponibles para beneficiarios en México, en MXN. Para pagos en Argentina (ARS) a una CBU, CVU o alias, consulta Argentina; para pagos en Chile (CLP) a una cuenta corriente o vista, consulta Retiros en Chile.

Esta guía está dirigida a quien va a integrar. Cubre la creación de un retiro y el resto del ciclo: aprobación, consulta, estados y webhooks.

Ambientes y autenticación

Los retiros viven en el host de API Direct:

Cada petición lleva la API key pública de tu comercio. La privada no sirve para este flujo.

Authorization: Token <API_KEY>
Content-Type: application/json

Crear un retiro

Créalo con POST /api/v1/process/, el mismo endpoint que usan los pagos. Lo que distingue a un retiro es operation_type.

curl -X POST "https://stage.tonder.io/api/v1/process/" \
  -H "Authorization: Token YOUR_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_type": "withdrawal",
    "amount": 20.00,
    "currency": "MXN",
    "client_reference": "payout-001",
    "transfer_method": "SPEI",
    "description": "Pago de comisiones",
    "beneficiary": {
      "account": "012969100000000110",
      "name": "Ana Maria Gonzalez",
      "rfc": "GOAN850315AB2",
      "institution": "40012",
      "email": "ana.gonzalez@email.com"
    },
    "metadata": {
      "latitude": "22.8870221",
      "longitude": "-109.911775",
      "order_reference": "ORD-001"
    },
    "fee_model": "01"
  }'

curl -X POST "https://app.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": "Pago de comisiones",
    "beneficiary": {
      "account": "012969100000000110",
      "name": "Ana Maria Gonzalez",
      "rfc": "GOAN850315AB2",
      "institution": "40012",
      "email": "ana.gonzalez@email.com"
    },
    "metadata": {
      "latitude": "22.8870221",
      "longitude": "-109.911775",
      "order_reference": "ORD-001"
    },
    "fee_model": "01"
  }'

Tarjeta de débito. Respecto a SPEI cambian dos cosas y nada más: transfer_method pasa a "DEBIT_CARD" y beneficiary.account lleva el número de 16 dígitos.

Geolocalización. metadata.latitude y metadata.longitude se recomiendan para operaciones en México. Si tu integración ya las envía, mantenlas.

HTTP 201:

{
  "id": "a1e2f918-1851-4988-b9de-36d57f41ed56",
  "withdrawal_id": "ad3069ed-598e-4a1b-82e0-2279d5af292d",
  "operation_type": "withdrawal",
  "status": "Pending",
  "amount": 20.0,
  "currency": "MXN",
  "client_reference": "payout-001",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "order_reference": "ORD-001"
  },
  "transfer_method": "SPEI",
  "created_at": "2026-10-01T17:33:41.364685Z",
  "status_code": 201
}

Aprobar

Un retiro recién creado queda en estado pendiente y no avanza solo, salvo que tu comercio tenga activada una regla de aprobación automática. Si tus retiros se quedan ahí, este es el paso que falta.

Desde el Dashboard. Abre el retiro en Retiros y presiona Approve.

Por API:

curl -X POST "https://stage.tonder.io/api/v1/withdrawals/perform_action/" \
  -H "Authorization: Token YOUR_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "ad3069ed-598e-4a1b-82e0-2279d5af292d", "action": "approve" }'

curl -X POST "https://app.tonder.io/api/v1/withdrawals/perform_action/" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "ad3069ed-598e-4a1b-82e0-2279d5af292d", "action": "approve" }'

Acciones: approve, reject, cancel, fail, refund.

Idempotencia. Un segundo approve sobre un retiro ya liquidado responde 409 con Invalid transition from PAID_FULL to PROCESSING. Sobre uno en estado terminal, 409 con Cannot modify withdrawal in terminal state. Reintentar no duplica el pago.

Una acción inexistente responde 400 con Invalid action.

Consultar

Estado de la transacción

GET /api/v1/transactions/<id>/

Toma el id de transacción, el campo id de la respuesta de /process/.

Detalle del retiro

curl "https://stage.tonder.io/api/v1/withdrawals/ad3069ed-598e-4a1b-82e0-2279d5af292d" \
  -H "Authorization: Token YOUR_TEST_API_KEY"

curl "https://app.tonder.io/api/v1/withdrawals/ad3069ed-598e-4a1b-82e0-2279d5af292d" \
  -H "Authorization: Token YOUR_API_KEY"

Sin barra final. Con barra responde 404. Un identificador inexistente responde 200 con {"detail": "Withdrawal not found"} y sin registro: comprueba detail antes de leer los campos.

Es el único endpoint que trae el motivo de un fallo, en status_changes[].reason y action.reason:

{
  "id": "7b57edd2-6594-4ef6-813b-df0d3d091a5c",
  "business_id": "69",
  "status": "FAILED",
  "amount": 1.7,
  "currency": "MXN",
  "transfer_method": "SPEI",
  "tracking_key": "a61c4f05b1de4645a1d2",
  "provider_reference": null,
  "account_data": { "...": "..." },
  "status_changes": [
    { "from_status": "PENDING", "to_status": "PROCESSING",
      "timestamp": "2026-10-13T18:40:23.497368", "reason": null },
    { "from_status": "PROCESSING", "to_status": "FAILED",
      "timestamp": "2026-10-13T18:40:23.497375",
      "reason": "Provider rejected: invalid_institution_id" }
  ],
  "action": { "action": "FAIL", "reason": "Provider rejected: invalid_institution_id" },
  "url_cep": "",
  "created_at": "2026-10-13T02:06:17.772297Z",
  "paid_at": null
}

Listado

curl "https://stage.tonder.io/api/v1/withdrawals/query/?page=1&page_size=50&start_date=2026-10-01&end_date=2026-10-07" \
  -H "Authorization: Token YOUR_TEST_API_KEY"

curl "https://app.tonder.io/api/v1/withdrawals/query/?page=1&page_size=50&start_date=2026-10-01&end_date=2026-10-07" \
  -H "Authorization: Token YOUR_API_KEY"

La respuesta es { "count", "results", "search_mode" }, donde cada elemento de results es el registro completo del retiro, el mismo del detalle.

Saldo disponible

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

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

{
  "available": "32894.55",
  "current_balance": "32894.55"
}

Solo GET. Con POST responde 405.

Movimientos de cuenta

curl "https://stage.tonder.io/api/v1/withdrawals/account_activity/query/?page=1&page_size=50&tz=America/Mexico_City&start_date=2026-10-01&end_date=2026-10-02" \
  -H "Authorization: Token YOUR_TEST_API_KEY"

curl "https://app.tonder.io/api/v1/withdrawals/account_activity/query/?page=1&page_size=50&tz=America/Mexico_City&start_date=2026-10-01&end_date=2026-10-02" \
  -H "Authorization: Token YOUR_API_KEY"

Devuelve los movimientos de la cuenta, retiros y depósitos, como { "results", "next_token" }.

Estados

El ciclo completo, en el orden en que ocurren:

Dos vocabularios

La respuesta de creación y los webhooks usan nombres en formato legible, mientras que las consultas devuelven los nombres internos. Son el mismo estado:

Al conciliar

Webhooks

Se emiten dos por retiro: uno al crearse, con estado pendiente, y otro al llegar a estado terminal. Si los fondos se devuelven después de haberse pagado, llega un tercero.

Formato plano

{
  "id": "a1e2f918-1851-4988-b9de-36d57f41ed56",
  "operation_type": "withdrawal",
  "amount": "20",
  "currency": "MXN",
  "client_reference": "payout-001",
  "status": "Pending",
  "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"
}

La carga puede traer otros campos que identifican a la institución que ejecutó la transferencia y su referencia. No construyas lógica sobre ellos: dependen de la configuración de tu cuenta y pueden cambiar.

Formato extendido

Anida todo bajo withdrawal y agrega el historial de estados, las comisiones y el detalle del envío. El estado viaja en los nombres internos de la sección Estados.

{
  "withdrawal": {
    "id": "ad3069ed-598e-4a1b-82e0-2279d5af292d",
    "business_id": "69",
    "status": "PAID_FULL",
    "business_id_status": "69#PAID_FULL",
    "monetary_amount": { "amount": "20.00", "currency": "MXN" },
    "transfer_method": "SPEI",
    "tracking_key": "2da0310418da4be18419",
    "provider_reference": "ref_2da0310418da4be1",
    "account_data": {
      "nombre_beneficiario": "Ana Maria Gonzalez",
      "cuenta_beneficiario": "012969100000000110",
      "institucion_contraparte": "40012",
      "tipo_cuenta_beneficiario": "40",
      "rfc_curp_beneficiario": "GOAN850315AB2",
      "concepto_pago": "Pago de comisiones",
      "email": "ana.gonzalez@email.com"
    },
    "status_changes": [
      { "from_status": "PENDING", "to_status": "PROCESSING",
        "timestamp": "2026-09-15T19:33:20.112", "reason": null },
      { "from_status": "PROCESSING", "to_status": "PAID_FULL",
        "timestamp": "2026-09-15T19:35:52.912", "reason": "succeeded" }
    ],
    "metadata": { "order_reference": "ORD-001" },
    "fee_model": "01",
    "created_at": "2026-09-15T19:33:14.262113+00:00",
    "modified_at": "2026-09-15T19:35:52.989243+00:00",
    "paid_at": "2026-09-15T19:35:52.989260+00:00"
  }
}

Trae además un bloque con la notificación cruda de la institución que ejecutó el envío.

Los cinco eventos

withdrawal_Pending — el retiro se creó y espera aprobación.

{ "status": "Pending", "event_type": "withdrawal_Pending", "...": "..." }

withdrawal_Success — liquidado. El dinero salió.

{ "status": "Success", "event_type": "withdrawal_Success", "...": "..." }

withdrawal_Declined — rechazado, normalmente por datos del beneficiario.

{ "status": "Declined", "event_type": "withdrawal_Declined", "...": "..." }

withdrawal_Failed — falló al enviarse.

{ "status": "Failed", "event_type": "withdrawal_Failed", "...": "..." }

withdrawal_Returned — el banco receptor devolvió los fondos después de un pago exitoso. Es el tercer webhook de ese retiro, y llega minutos u horas después del Success.

{ "status": "Returned", "event_type": "withdrawal_Returned", "...": "..." }

Con Webhooks 2.0, un retiro cancelado también envía withdrawal_Canceled —con una sola L.

Recomendaciones

Códigos de institución

beneficiary.institution es el código de la institución del beneficiario según el catálogo de Banxico, de cuatro o cinco dígitos. También funcionan los participantes no bancarios del catálogo. La lista completa está en la Referencia bancaria.

Datos de prueba

Válidos únicamente en Sandbox, y siempre con la institución 40012: dos CLABEs que pagan, una que falla, una cuyos fondos vuelven entre minutos y una hora después de pagarse —la forma de ejercitar el tercer webhook, withdrawal_Returned— y una tarjeta de débito que paga. Las cuentas y cómo forzar cada estado terminal están en Casos de prueba — Retiros.

Comprobante de pago (CEP)

Los retiros liquidados entregan un comprobante en el campo url_cep, que apunta al portal de Banxico con los datos del pago.

Un retiro REFUNDED conserva su comprobante: el envío ocurrió y después se devolvió.

Errores

Los códigos HTTP genéricos están en Códigos.

Antes de salir a producción

El monto no se valida contra tu saldo al crear. Un retiro por encima de lo disponible se acepta y queda pendiente. La validación ocurre al liquidarlo, y ahí falla.

El saldo no se reserva mientras el retiro está pendiente. Se descuenta al pagarse. Si acumulas muchos pendientes, el saldo disponible no refleja ese compromiso.

El nombre del beneficiario tiene un límite práctico de 40 caracteres. Nombres más largos pueden ser rechazados al enviar, no al crear. Conviene validarlo de tu lado antes. Un caso frecuente es el apellido duplicado por el usuario final.

Un retiro pendiente se despacha con la configuración vigente al aprobarlo, no con la que tenía al crearse.

El límite de monto lo define la institución que ejecuta la transferencia, no Tonder.

Dudas

Si algo de esta guía no coincide con lo que observas, escríbenos a soporte con el withdrawal_id, el id de transacción y la hora aproximada. Con eso podemos rastrear el caso completo.

Referencia de la API

Un retiro se crea con Procesar transacción. El resto del ciclo:

curl -X POST "https://example.com/withdrawals/perform_action/" \  -H "Content-Type: application/json" \  -d '{    "id": "ad3069ed-598e-4a1b-82e0-2279d5af292d",    "action": "approve"  }'

{
  "id": "ad3069ed-598e-4a1b-82e0-2279d5af292d",
  "business_id": "69",
  "status": "PROCESSING",
  "amount": 20,
  "currency": "MXN",
  "transfer_method": "SPEI",
  "status_changes": [
    {
      "from_status": "PENDING",
      "to_status": "PROCESSING",
      "timestamp": "2026-10-01T17:35:02.118402",
      "reason": null
    }
  ],
  "created_at": "2026-10-01T17:33:41.364685Z",
  "modified_at": "2026-10-01T17:35:02.201173Z",
  "paid_at": null
}

{
  "error": "Invalid action"
}

{
  "detail": "Invalid token."
}

{
  "error": "Withdrawal not found: 'Item'"
}

{
  "detail": "Cannot modify withdrawal in terminal state"
}

curl -X GET "https://example.com/withdrawals/7b57edd2-6594-4ef6-813b-df0d3d091a5c"

{
  "id": "7b57edd2-6594-4ef6-813b-df0d3d091a5c",
  "business_id": "69",
  "status": "FAILED",
  "amount": 1.7,
  "currency": "MXN",
  "transfer_method": "SPEI",
  "tracking_key": "a61c4f05b1de4645a1d2",
  "provider_reference": null,
  "account_data": {
    "nombre_beneficiario": "Ana Maria Gonzalez",
    "cuenta_beneficiario": "012969100000000013",
    "institucion_contraparte": "40012",
    "tipo_cuenta_beneficiario": 40,
    "rfc_curp_beneficiario": "GOAN850315AB2",
    "concepto_pago": "Pago de comisiones",
    "email": "ana.gonzalez@email.com"
  },
  "metadata": {
    "order_reference": "ORD-001"
  },
  "status_changes": [
    {
      "from_status": "PENDING",
      "to_status": "PROCESSING",
      "timestamp": "2026-10-13T18:40:23.497368",
      "reason": null
    },
    {
      "from_status": "PROCESSING",
      "to_status": "FAILED",
      "timestamp": "2026-10-13T18:40:23.497375",
      "reason": "Provider rejected: invalid_institution_id"
    }
  ],
  "action": {
    "action": "FAIL",
    "reason": "Provider rejected: invalid_institution_id"
  },
  "url_cep": "",
  "created_at": "2026-10-13T02:06:17.772297Z",
  "modified_at": "2026-10-13T18:40:23.512117Z",
  "paid_at": null
}

{
  "detail": "Invalid token."
}

curl -X GET "https://example.com/withdrawals/query/"

{
  "count": 1,
  "results": [
    {
      "id": "ea6ac67d-b577-481a-9b99-3c3c275ae527",
      "business_id": "69",
      "status": "PAID_FULL",
      "amount": 20,
      "currency": "MXN",
      "transfer_method": "SPEI",
      "tracking_key": "2da0310418da4be18419",
      "account_data": {
        "nombre_beneficiario": "Ana Maria Gonzalez",
        "cuenta_beneficiario": "012969100000000110",
        "institucion_contraparte": "40012",
        "tipo_cuenta_beneficiario": 40,
        "rfc_curp_beneficiario": "GOAN850315AB2",
        "concepto_pago": "Pago de comisiones",
        "email": "ana.gonzalez@email.com"
      },
      "metadata": {
        "order_reference": "ORD-001"
      },
      "status_changes": [
        {
          "from_status": "PENDING",
          "to_status": "PROCESSING",
          "timestamp": "2026-10-01T17:35:02.118402",
          "reason": null
        },
        {
          "from_status": "PROCESSING",
          "to_status": "PAID_FULL",
          "timestamp": "2026-10-01T17:37:41.902188",
          "reason": "succeeded"
        }
      ],
      "url_cep": "https://www.banxico.org.mx/cep/",
      "created_at": "2026-10-01T17:33:41.364685Z",
      "modified_at": "2026-10-01T17:37:41.998211Z",
      "paid_at": "2026-10-01T17:37:41.998227Z"
    }
  ],
  "search_mode": "date_range"
}

{
  "detail": "Invalid token."
}

{
  "error": "Failed to fetch withdrawals"
}

curl -X GET "https://example.com/withdrawals/balance"

{
  "available": "32894.55",
  "current_balance": "32894.55"
}

{
  "detail": "Invalid token."
}

{
  "detail": "Method \"POST\" not allowed."
}

curl -X GET "https://example.com/withdrawals/account_activity/query/"

{
  "results": [
    {
      "id": "9c1d7f32-5b0e-4a7d-9f2e-1c8a4b6d2e10",
      "type": "withdrawal",
      "amount": "20.00",
      "business_id": "69",
      "status": "succeeded",
      "operation_date": "2026-10-01T17:37:41Z",
      "created_at": "2026-10-01T17:37:48.668244Z",
      "metadata": {
        "tonder_withdrawal_id": "ea6ac67d-b577-481a-9b99-3c3c275ae527",
        "beneficiary_account": "012969******0110",
        "tracking_key": "2da0310418da4be18419",
        "currency": "MXN"
      },
      "raw_json": {
        "amount": 2000,
        "currency": "MXN",
        "status": "succeeded",
        "tracking_key": "2da0310418da4be18419"
      }
    }
  ],
  "next_token": null
}

{
  "detail": "Invalid token."
}

Siguientes pasos