Withdrawals

Overview

Tonder’s withdrawal functionality enables businesses to send payouts to beneficiaries through the same unified /process/ endpoint. Withdrawals support SPEI bank transfers and direct debit card deposits, providing flexible payout options across Mexico. These are the withdrawal methods supported by Tonder:

Method	ID	Description	Processing Time
SPEI	`SPEI`	Bank account transfers	Same day
Debit Card	`DEBIT_CARD`	Direct card deposits	Instant

Withdrawal Request Structure

All withdrawal requests use operation_type: "withdrawal" and must include beneficiary information. The following fields are required for withdrawal requests:

Field	Type	Required	Description
`operation_type`	string	Yes	Must be `"withdrawal"`
`amount`	decimal	Yes	Withdrawal amount
`currency`	string	No	Currency code (default: `"MXN"`)
`transfer_method`	string	Yes	Transfer method (`"SPEI"` or `"DEBIT_CARD"`)
`beneficiary`	object	Yes	Beneficiary information
`reference`	string	No	Your withdrawal reference
`description`	string	No	Withdrawal description

The beneficiary object includes the following fields:

Field	Type	Required	Description
`beneficiary.account`	string	Yes	Account number or CLABE
`beneficiary.name`	string	Yes	Beneficiary full name
`beneficiary.rfc`	string	Yes	Mexican tax ID (RFC)
`beneficiary.institution`	string	Yes	Bank institution code
`beneficiary.email`	string	Yes	Beneficiary email

SPEI Withdrawals

SPEI withdrawals transfer funds directly to Mexican bank accounts using the SPEI interbank system. Processing typically completes on the same business day.

SPEI withdrawal request example

{
  "operation_type": "withdrawal",
  "amount": 750.00,
  "currency": "MXN",
  "reference": "payout-001",
  "transfer_method": "SPEI",
  "description": "Commission payment",
  "beneficiary": {
    "account": "012345678901234567",
    "name": "Roberto Martínez García",
    "rfc": "MAGR850920XY1",
    "institution": "40012",
    "email": "roberto.martinez@email.com"
  }
}

SPEI response example

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "operation_type": "withdrawal",
  "status": "processing",
  "amount": 750.00,
  "currency": "MXN",
  "merchant_reference": "payout-001",
  "transfer_method": "SPEI",
  "beneficiary": {
    "account": "***************4567",
    "name": "Roberto Martínez García",
    "institution": "40012"
  },
  "created_at": "2024-07-26T10:30:00Z",
  "status_code": 201
}

SPEI Account Validation

SPEI validates accounts using the CLABE format, which is a 18-digit bank account number format used in Mexico. It consists of the following components:

Total length: 18 digits
Bank code: 3 digits (positions 1-3)
Branch code: 3 digits (positions 4-6)
Account number: 11 digits (positions 7-17)
Check digit: 1 digit (position 18)

Example CLABE Breakdown:

CLABE: 012345678901234567
│││└─────────────────── Account number (11 digits)
││└─────────────────────── Branch code (3 digits)
│└──────────────────────── Bank code (3 digits)
└───────────────────────── Check digit (1 digit)

Institution Codes

Major Mexican financial institutions and their corresponding codes for SPEI transactions:

Code	Bank Name	CLABE Prefix
40012	BBVA México	012
40014	Santander	014
40021	HSBC	021
40072	Banorte	072
40646	STP	646
40137	Banregio	137
40058	Banco Azteca	058

Debit Card Withdrawals

Debit card withdrawals enable instant deposits directly to debit cards, providing immediate fund availability to beneficiaries.

Debit card withdrawal request example

{
  "operation_type": "withdrawal",
  "amount": 500.00,
  "currency": "MXN",
  "reference": "card-payout-002",
  "transfer_method": "DEBIT_CARD",
  "description": "Instant payout to debit card",
  "beneficiary": {
    "account": "4111111111111111",
    "name": "Ana María González",
    "rfc": "GOAN850315AB2",
    "institution": "40012",
    "email": "ana.gonzalez@email.com"
  }
}

Debit card response example

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "operation_type": "withdrawal",
  "status": "processing",
  "amount": 500.00,
  "currency": "MXN",
  "merchant_reference": "card-payout-002",
  "transfer_method": "DEBIT_CARD",
  "beneficiary": {
    "account": "****1111",
    "name": "Ana María González",
    "institution": "40012"
  },
  "created_at": "2024-07-26T11:15:00Z",
  "status_code": 201
}

Withdrawal Status Flow

Withdrawals have their own status flow, which is different from payments.

Status	Description	Next Steps
`pending`	Withdrawal request received	Monitor for processing
`processing`	Transfer being processed	Wait for completion
`success`	Transfer completed successfully	Transaction complete
`failed`	Transfer failed	Check error details
`declined`	Transfer declined by bank	Try different account

Status Check

Use the transaction status endpoint to monitor withdrawal progress:

GET /transactions/{withdrawal_id}/

Status check response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "operation_type": "withdrawal",
  "status": "success",
  "amount": 750.00,
  "currency": "MXN",
  "merchant_reference": "payout-001",
  "created_at": "2024-07-26T10:30:00Z",
  "updated_at": "2024-07-26T14:45:22Z",
  "completion_details": {
    "completed_at": "2024-07-26T14:45:22Z",
    "reference_number": "SPEI123456789"
  }
}

Implementation Examples

Below you’ll find examples of how to implement withdrawals in different programming languages.

def process_spei_withdrawal():
    """Process SPEI withdrawal to bank account"""
    
    withdrawal_data = {
        "operation_type": "withdrawal",
        "amount": 750.00,
        "currency": "MXN",
        "reference": "payout-001",
        "transfer_method": "SPEI",
        "description": "Commission payment",
        "beneficiary": {
            "account": "012345678901234567",
            "name": "Roberto Martínez García",
            "rfc": "MAGR850920XY1",
            "institution": "40012",
            "email": "roberto.martinez@email.com"
        }
    }
    
    try:
        response = tonder_api.process_withdrawal(withdrawal_data)
        print(f"Withdrawal initiated: {response['id']}")
        return response
        
    except Exception as e:
        print(f"Withdrawal failed: {e}")
        return None

def process_card_withdrawal():
    """Process withdrawal to debit card"""
    
    withdrawal_data = {
        "operation_type": "withdrawal",
        "amount": 500.00,
        "currency": "MXN",
        "reference": "card-payout-002",
        "transfer_method": "DEBIT_CARD",
        "description": "Instant payout to debit card",
        "beneficiary": {
            "account": "4111111111111111",
            "name": "Ana María González",
            "rfc": "GOAN850315AB2",
            "institution": "40012",
            "email": "ana.gonzalez@email.com"
        }
    }
    
    try:
        response = tonder_api.process_withdrawal(withdrawal_data)
        print(f"Card withdrawal initiated: {response['id']}")
        return response
        
    except Exception as e:
        print(f"Card withdrawal failed: {e}")
        return None

Validation Requirements

Withdrawals can go through a validation process to ensure the data is correct.

RFC Validation

RFC is used to validate the beneficiary’s tax identification number. This is a 12-13 alphanumeric characters format and can be either an individual or business RFC.

Type	Structure	Example
Individual	4 letters from the name 6 digits for date of birth (YYMMDD) 3 alphanumeric characters	`MAGR850920XY1`
Business	3 letters from the business name 6 digits for registration date (YYMMDD) 3 alphanumeric characters	`ABC9901011A2`

For individuals, the RFC is generated from the person’s name and date of birth. For businesses, it’s based on the business name and registration date.

Account Number Validation

Account number is used to validate the beneficiary’s bank account number. This is a 18 digits number and can be either a SPEI/CLABE or a debit card number.

Type	Validation Criteria
SPEI/CLABE	- Exactly 18 digits - Valid checksum digit - Recognised bank code
Debit Card	- 13–19 digits - Valid card number format - Must be a debit card (not a credit card)

Error Handling

Here you’ll find the common errors that can happen when processing withdrawals.

Error Code	Description	Solution
`invalid_clabe`	CLABE number invalid	Verify CLABE format
`institution_not_found`	Bank code not found	Use valid institution code
`insufficient_balance`	Not enough balance	Check account balance
`beneficiary_blocked`	Beneficiary account blocked	Contact bank
`invalid_rfc`	RFC format invalid	Use valid RFC format
`amount_too_high`	Exceeds withdrawal limits	Reduce amount

Error response example

{
  "error": {
    "code": "invalid_clabe",
    "message": "CLABE number format is invalid",
    "type": "validation_error",
    "details": {
      "field": "beneficiary.account",
      "received_value": "12345678901234567"
    }
  },
  "request_id": "req_abc123"
}

SPEI Operating Schedule

Here are some information about the operating hours for SPEI transactions.

Day/Period	Processing Hours	Notes
Monday to Friday	6:00 AM – 6:00 PM (CDMX time)	Same-day processing if before 5:00 PM
Saturday	9:00 AM – 2:00 PM	Limited processing
Sunday	No processing
Bank holidays	No processing

Processing Times for WithdrawalsWithdrawals are processed according to the method and the time you submit your request:

Same business day: Requests before 5:00 PM (CDMX) on business days are processed the same day.
Next business day: Requests after 5:00 PM or on weekends are processed the next business day.
Instant: Debit card withdrawals are instant, 24/7.

Best Practices

Here you’ll find some best practices to follow when processing withdrawals.

Beneficiary Data

Transaction Management

Security

Error Recovery

Testing

Here you’ll find some information about the test bank accounts and cards that you can use to test your withdrawals.

Test Bank Accounts

CLABE	Scenario	Expected Result
646180157000000004	Successful transfer	`processing` status
012345678901234567	Invalid checksum	Validation error
999999999999999999	Non-existent bank	`institution_not_found` error

Test Cards

Card Number	Scenario	Expected Result
4111111111111111	Successful withdrawal	`processing` status
4000000000000002	Declined card	`declined` status
5555555555554444	Processing error	`failed` status

Next Steps

Review Response Format for handling withdrawal responses
Set up Webhooks for real-time withdrawal notifications
Check Error Handling for withdrawal error management
Explore Mexican Banking Reference for additional bank information

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

Overview

Withdrawal Request Structure

SPEI Withdrawals

SPEI Account Validation

Institution Codes

Debit Card Withdrawals

Withdrawal Status Flow

Status Check

Implementation Examples

Validation Requirements

RFC Validation

Account Number Validation

Error Handling

SPEI Operating Schedule

Best Practices

Testing

Test Bank Accounts

Test Cards

Next Steps

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

​Overview

​Withdrawal Request Structure

​SPEI Withdrawals

​SPEI Account Validation

​Institution Codes

​Debit Card Withdrawals

​Withdrawal Status Flow

​Status Check

​Implementation Examples

​Validation Requirements

​RFC Validation

​Account Number Validation

​Error Handling

​SPEI Operating Schedule

​Best Practices

​Testing

​Test Bank Accounts

​Test Cards

​Next Steps

Overview

Withdrawal Request Structure

SPEI Withdrawals

SPEI Account Validation

Institution Codes

Debit Card Withdrawals

Withdrawal Status Flow

Status Check

Implementation Examples

Validation Requirements

RFC Validation

Account Number Validation

Error Handling

SPEI Operating Schedule

Best Practices

Testing

Test Bank Accounts

Test Cards

Next Steps