Create a Withdrawal

This guide explains how to create a withdrawal request using the Tonder Withdrawals API endpoint POST /withdrawals/.

Authentication RequiredEvery request to this endpoint requires authentication. You must include the Authorization header with your API token. This applies to all API requests, Postman requests, and testing. See Authentication requirements for details.

Endpoint

POST /withdrawals/

Required Parameters

The following table lists all mandatory parameters for creating a new withdrawal request:

Parameter	Type	Required	Description	Constraints & Values
`user_id`	integer	Yes	User ID in the Tonder system	Get from Get User ID endpoint
`amount`	decimal	Yes	Amount to withdraw	-
`currency`	string	Yes	Currency code	`"MXN"` for SPEI transfers
`transfer_method`	string	Yes	Transfer method	Values: `"SPEI"` or `"DEBIT_CARD"`
`beneficiary_account`	string	Yes	Account number of the beneficiary	18-digit CLABE for SPEI, 16-digit card for DEBIT_CARD
`beneficiary_name`	string	Yes	Name of the beneficiary	-
`beneficiary_rfc`	string	Conditional	RFC identification	Required for SPEI. For DEBIT_CARD, use `beneficiary_rfc`, `beneficiary_curp`, or `"ND"`
`beneficiary_curp`	string	Conditional	CURP identification	Alternative to `beneficiary_rfc` for DEBIT_CARD only
`beneficiary_institution`	string	Yes	Institution code	CRITICAL: Use `97846` for testing. See Institution Codes for production
`interbank_code`	string	Yes	Originator account (CLABE)	Required for SPEI transfers
`fee_model`	string	Yes	Fee model code	Values: `00` (User pays fees) or `01` (Merchant pays fees)
`metadata`	object	Yes	Additional required information	Must include `latitude` and `longitude`

Critical: Latitude and Longitude Required for MexicoThe metadata.latitude and metadata.longitude fields are mandatory for processing withdrawals in Mexico. Omitting these fields or providing erroneous coordinates will result in a failed transaction. Ensure you collect and validate accurate geolocation data from your customers.

Optional Parameters

Parameter	Type	Required	Description
`email`	string	No	Contact email for notifications
`description`	string	No	Transaction description

Testing Institution CodeWhen testing in the Stage environment, you must use institution code 97846 for the beneficiary_institution field. This is a special test code that simulates bank responses.

Request Examples

SPEI Transfer

{
  "user_id": 27055,
  "amount": 15,
  "currency": "MXN",
  "transfer_method": "SPEI",
  "beneficiary_account": "846180000400000001",
  "beneficiary_name": "Jhon Doe",
  "beneficiary_rfc": "ND",
  "beneficiary_institution": "97846",
  "interbank_code": "646180567300000006",
  "email": "fabio@tonder.io",
  "description": "test",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "operation_date": "2024-01-15",
    "customer_email": "fabio@tonder.io",
    "business_user": "admin_user_001",
    "customer_id": "CUST_12345",
    "order_id": "ORDER_ABC_789"
  },
  "fee_model": "01"
}

Debit Card Transfer with RFC

{
  "user_id": 1,
  "amount": 100,
  "currency": "MXN",
  "transfer_method": "DEBIT_CARD",
  "beneficiary_account": "4111111111111111",
  "beneficiary_name": "Fabio",
  "beneficiary_rfc": "FABC800101ABC",
  "beneficiary_institution": "97846",
  "interbank_code": "646180567300000006",
  "email": "fabio@tonder.io",
  "description": "test",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "operation_date": "2024-01-15",
    "customer_email": "fabio@tonder.io",
    "business_user": "admin_user_001",
    "customer_id": "CUST_12345",
    "order_id": "ORDER_ABC_789"
  },
  "fee_model": "01"
}

Debit Card Transfer with CURP

{
  "user_id": 1,
  "amount": 100,
  "currency": "MXN",
  "transfer_method": "DEBIT_CARD",
  "beneficiary_account": "4111111111111111",
  "beneficiary_name": "Fabio",
  "beneficiary_curp": "FABC800101HDFBRD09",
  "beneficiary_institution": "97846",
  "interbank_code": "646180567300000006",
  "email": "fabio@tonder.io",
  "description": "test",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "operation_date": "2024-01-15",
    "customer_email": "fabio@tonder.io",
    "business_user": "admin_user_001",
    "customer_id": "CUST_12345",
    "order_id": "ORDER_ABC_789"
  },
  "fee_model": "01"
}

Debit Card Transfer without Document (ND)

{
  "user_id": 1,
  "amount": 100,
  "currency": "MXN",
  "transfer_method": "DEBIT_CARD",
  "beneficiary_account": "4111111111111111",
  "beneficiary_name": "Fabio",
  "beneficiary_rfc": "ND",
  "beneficiary_institution": "97846",
  "interbank_code": "646180567300000006",
  "email": "fabio@tonder.io",
  "description": "test",
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "operation_date": "2024-01-15",
    "customer_email": "fabio@tonder.io",
    "business_user": "admin_user_001",
    "customer_id": "CUST_12345",
    "order_id": "ORDER_ABC_789"
  },
  "fee_model": "01"
}

DEBIT_CARD Identification OptionsFor DEBIT_CARD transfers, you can use:

beneficiary_rfc with a valid RFC
beneficiary_curp with a valid CURP
beneficiary_rfc with value "ND" (No Disponible) if no document is available

For SPEI transfers, beneficiary_rfc is required (can be "ND").

cURL Example

curl -X POST https://stage.tonder.io/api/v1/withdrawals/ \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 27055,
    "amount": 15,
    "currency": "MXN",
    "transfer_method": "SPEI",
    "beneficiary_account": "846180000400000001",
    "beneficiary_name": "Jhon Doe",
    "beneficiary_rfc": "ND",
    "beneficiary_institution": "97846",
    "interbank_code": "646180567300000006",
    "email": "fabio@tonder.io",
    "description": "test",
    "metadata": {
      "latitude": "22.8870221",
      "longitude": "-109.911775",
      "operation_date": "2024-01-15",
      "customer_email": "fabio@tonder.io",
      "business_user": "admin_user_001",
      "customer_id": "CUST_12345",
      "order_id": "ORDER_ABC_789"
    },
    "fee_model": "01"
  }'

Postman ConfigurationWhen testing in Postman, ensure you include the Authorization header:

Method: POST
URL: https://stage.tonder.io/api/v1/withdrawals/
Headers Tab:
- Authorization: Token YOUR_API_KEY (replace with your actual token)
- Content-Type: application/json
Body Tab: Select raw and JSON, then paste your request JSON

Important: Replace YOUR_API_KEY with the token provided in the Developers section of the Tonder platform. Every request requires this authentication header.

Response

Upon successful creation, the API returns a withdrawal object with a PENDING status and a unique withdrawal ID:

SPEI Response Example

{
  "id": "40f19a6b-4ce4-424e-92fe-1b564c07dbd7",
  "user_id": "1",
  "business_id": "21",
  "currency": "MXN",
  "amount": 100.0,
  "status": "PENDING",
  "account_data": {
    "cuenta_ordenante": "646180567300000006",
    "nombre_ordenante": "TRES_COMAS",
    "rfc_curp_ordenante": "ND",
    "cuenta_beneficiario": "846180000400000001",
    "nombre_beneficiario": "Fabio",
    "rfc_curp_beneficiario": "ND",
    "institucion_contraparte": "97846",
    "tipo_cuenta_beneficiario": 40,
    "email": "fabio@tonder.io",
    "concepto_pago": "test"
  },
  "status_changes": [],
  "action": null,
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "operation_date": "2024-01-15",
    "customer_email": "fabio@tonder.io",
    "business_user": "admin_user_001",
    "customer_id": "CUST_12345",
    "order_id": "ORDER_ABC_789"
  },
  "created_at": "2025-10-02T01:09:37.371365Z",
  "modified_at": "2025-10-02T01:09:37.371365Z",
  "provider_reference": "PENDING",
  "transfer_method": "SPEI",
  "fixed_fee": "3.5",
  "tax": "16.0",
  "fee_amount": null
}

DEBIT_CARD Response Example

{
  "id": "d4b294ba-638e-408b-bc80-c9c7b7023e8c",
  "user_id": "1",
  "business_id": "21",
  "currency": "MXN",
  "amount": 100.0,
  "status": "PENDING",
  "account_data": {
    "cuenta_ordenante": "646180567300000006",
    "nombre_ordenante": "TRES_COMAS",
    "rfc_curp_ordenante": "ND",
    "cuenta_beneficiario": "4111111111111111",
    "nombre_beneficiario": "Fabio",
    "rfc_curp_beneficiario": "ND",
    "institucion_contraparte": "97846",
    "tipo_cuenta_beneficiario": 3,
    "email": "fabio@tonder.io",
    "concepto_pago": "test"
  },
  "status_changes": [],
  "action": null,
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "operation_date": "2024-01-15",
    "customer_email": "fabio@tonder.io",
    "business_user": "admin_user_001",
    "customer_id": "CUST_12345",
    "order_id": "ORDER_ABC_789"
  },
  "created_at": "2025-10-02T01:32:14.089682Z",
  "modified_at": "2025-10-02T01:32:14.089682Z",
  "provider_reference": "PENDING",
  "transfer_method": "DEBIT_CARD",
  "fixed_fee": "3.5",
  "tax": "16.0",
  "fee_amount": null
}

Save the Withdrawal IDAlways save the id field from the response. You’ll need it to track the withdrawal status and receive webhook notifications.

Parameter Details

Transfer Methods

SPEI: Bank transfers processed same business day during banking hours. Requires 18-digit CLABE.
DEBIT_CARD: Instant deposits available within 5-15 minutes, 24/7. Requires 16-digit card number.

Fee Models

00: User pays fees - fees are deducted from the withdrawal amount
01: Merchant pays fees - fees are charged separately to the merchant

Metadata Requirements

The metadata object must include:

latitude: Geographic latitude (string or decimal)
longitude: Geographic longitude (string or decimal)

Optional metadata fields you can include:

operation_date: Date of the operation (format: “YYYY-MM-DD”)
customer_email: Customer email address
business_user: Business user identifier
customer_id: Your internal customer ID
order_id: Your internal order ID

These fields are useful for tracking and reporting purposes.

Institution Codes

For production withdrawals, you need to use valid institution codes. See the Institution Codes Reference for the complete list of Mexican financial institutions.

Testing vs Production

Testing: Always use institution code 97846 in the Stage environment
Production: Use real institution codes from the Institution Codes Reference

Next Steps

Learn about withdrawal workflows and statuses to understand what happens after creation
Set up webhook listeners to receive real-time status updates
Review HTTP response codes to handle errors properly
Check institution codes for production use

Introduction

Core Concepts

Create a Withdrawal

Endpoint

Required Parameters

Optional Parameters

Request Examples

SPEI Transfer

Debit Card Transfer with RFC

Debit Card Transfer with CURP

Debit Card Transfer without Document (ND)

cURL Example

Response

SPEI Response Example

DEBIT_CARD Response Example

Parameter Details

Transfer Methods

Fee Models

Metadata Requirements

Institution Codes

Next Steps

​Endpoint

​Required Parameters

​Optional Parameters

​Request Examples

​SPEI Transfer

​Debit Card Transfer with RFC

​Debit Card Transfer with CURP

​Debit Card Transfer without Document (ND)

​cURL Example

​Response

​SPEI Response Example

​DEBIT_CARD Response Example

​Parameter Details

​Transfer Methods

​Fee Models

​Metadata Requirements

​Institution Codes

​Next Steps

Endpoint

Required Parameters

Optional Parameters

Request Examples

SPEI Transfer

Debit Card Transfer with RFC

Debit Card Transfer with CURP

Debit Card Transfer without Document (ND)

cURL Example

Response

SPEI Response Example

DEBIT_CARD Response Example

Parameter Details

Transfer Methods

Fee Models

Metadata Requirements

Institution Codes

Next Steps