Response Format

All Tonder API responses follow a consistent structure, providing standardized information regardless of the operation type (payment or withdrawal). This consistency simplifies integration and error handling across different transaction types.

Standard Response Structure

All successful requests return a consistent response format:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "authorized",
  "amount": 150.00,
  "currency": "MXN",
  "client_reference": "order-789",
  "payment_id": 12345,
  "transaction_id": "txn_abc123",
  "provider": "stripe",
  "created_at": "2024-07-26T10:30:00Z",
  "status_code": 201
}

Where:

Field	Type	Description
`id`	string	Unique transaction identifier (UUID)
`operation_type`	string	`"payment"` or `"withdrawal"`
`status`	string	Current transaction status
`amount`	decimal	Transaction amount
`currency`	string	Currency code (e.g., `"MXN"`, `"USD"`)
`client_reference`	string	Your reference identifier
`created_at`	string	ISO 8601 timestamp of creation
`status_code`	integer	HTTP status code

Transaction Status Values

The status field can have the following values:

Status	Label	Description	Next Steps
`pending`	Pending	Transaction awaiting completion	Check status or wait for webhook
`on_hold`	On hold	Transaction temporarily held	Wait for review completion
`processing`	Processing	Transaction being processed	Monitor for completion
`sent_to_provider`	Sent to provider	Sent to payment provider	Monitor for completion
`success`	Success	Transaction successfully completed	Transaction complete
`paid_full`	Paid in full	Payment completed in full	Transaction complete
`in_transit`	In transit	Payment in transit to destination	Monitor for completion
`canceled`	Canceled	Transaction was cancelled	No further action required
`declined`	Declined	Payment declined by provider or issuer	Try different payment method
`rejected`	Rejected	Transaction was rejected	Try different payment method
`failed`	Failed	Transaction processing failed	Check error details and retry
`Unknown`	Unknown	Status cannot be determined	Contact support for clarification
`expired`	Expired	Transaction or authorization expired	Create new transaction if needed
`authorized`	Authorized	Payment authorized (cards only)	Transaction complete

Payment Response Examples

Here are some examples of payment responses.

Card Payment Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "authorized",
  "amount": 150.00,
  "currency": "MXN",
  "client_reference": "order-789",
  "payment_id": 12345,
  "transaction_id": "txn_abc123",
  "provider": "stripe",
  "created_at": "2024-07-26T10:30:00Z",
  "status_code": 201
}

SPEI Payment Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "operation_type": "payment",
  "status": "processing",
  "amount": 500.00,
  "currency": "MXN",
  "client_reference": "invoice-456",
  "payment_id": 12346,
  "transaction_id": "txn_def456",
  "provider": "stp",
  "created_at": "2024-07-26T10:35:00Z",
  "status_code": 201
}

SPEI Withdrawal Response

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

Debit Card Withdrawal Response

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "operation_type": "withdrawal",
  "status": "processing",
  "amount": 500.00,
  "currency": "MXN",
  "client_reference": "card-payout-002",
  "created_at": "2024-07-26T11:15:00Z",
  "status_code": 201
}

Next Action Handling

Some transactions require additional steps (3D Secure, redirects, iframe interactions). The next_action object will contain specific instructions for handling these scenarios. Here are some examples of responses that require additional action.

Redirect to URL (3DS Authentication)

For card payments requiring 3D Secure authentication:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "pending",
  "amount": 150.00,
  "currency": "MXN",
  "next_action": {
    "redirect_to_url": {
      "url": "https://secure.payment-provider.com/3ds/abc123",
      "return_url": "https://yoursite.com/payment/return",
      "verify_transaction_status_url": "/api/v1/stripe/business/123/payments/456/transactions/789"
    }
  },
  "created_at": "2024-07-26T10:30:00Z",
  "status_code": 202
}

Implementation Steps:

Redirect customer to the provided url
Customer completes 3DS authentication
Customer is redirected back to your return_url
Check transaction status using the verify_transaction_status_url

Iframe Resources (MercadoPago)

For providers requiring iframe-based authentication:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "pending",
  "amount": 150.00,
  "currency": "MXN",
  "next_action": {
    "iframe_resources": {
      "return_url": "https://yoursite.com/payment/return",
      "verify_transaction_status_url": "/api/v1/mercadopago/business/123/payments/456/transactions/789",
      "external_resource_url": "https://mercadopago.com/3ds/challenge",
      "creq": "challenge_request_data"
    }
  },
  "created_at": "2024-07-26T10:30:00Z",
  "status_code": 202
}

Payment Instructions Response

For cash payment methods (OXXO, SafetyPay), the response includes detailed payment instructions:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "pending",
  "amount": 250.00,
  "currency": "MXN",
  "payment_instructions": {
    "reference_code": "99900012345678",
    "barcode": "||99900012345678||",
    "store_name": "OXXO",
    "expiration_date": "2024-07-29T23:59:59Z",
    "instructions": [
      "Acude a cualquier tienda OXXO",
      "Presenta este código de barras en caja",
      "Paga exactamente $250.00 MXN en efectivo"
    ]
  },
  "voucher_pdf": "https://api.tonder.io/vouchers/abc123.pdf",
  "created_at": "2024-07-26T10:30:00Z",
  "status_code": 201
}

Payment Instructions Fields

The following table lists the fields that are included in the payment_instructions object.

Field	Type	Description
`reference_code`	string	Payment reference for cash payment
`barcode`	string	Barcode representation
`store_name`	string	Store chain name (e.g., “OXXO”)
`expiration_date`	string	Payment expiration timestamp
`instructions`	array	Step-by-step payment instructions
`voucher_pdf`	string	URL to downloadable payment voucher

HTTP Status Codes

The following tables lists the HTTP status codes that are returned by the API.

Success Codes

Code	Description	When Used
200	OK	Status check successful
201	Created	Transaction created successfully
202	Accepted	Transaction accepted, requires additional action

Client Error Codes

Code	Description	Action Required
400	Bad Request	Fix request format
401	Unauthorized	Check authentication
402	Payment Required	Payment declined
404	Not Found	Check transaction ID
422	Validation Error	Fix request data
429	Rate Limited	Retry with backoff

Server Error Codes

Code	Description	Action Required
500	Internal Server Error	Retry request
502	Bad Gateway	Retry request
503	Service Unavailable	Retry later

Response Headers

All responses include standard headers for debugging and rate limiting:

HTTP/1.1 201 Created
Content-Type: application/json
X-Request-ID: req_abc123
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

The following table provides a description of the headers that are included in the response.

Header	Description
`X-Request-ID`	Unique request identifier for debugging
`X-RateLimit-Limit`	Request limit per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when limit resets

Error Response Format

When requests fail, errors follow a consistent format:

{
  "error": {
    "code": "validation_error",
    "message": "Amount must be greater than 0",
    "type": "request_error",
    "details": {
      "field": "amount",
      "received_value": -10.00
    }
  },
  "request_id": "req_abc123"
}

Where:

Field	Type	Description
`error.code`	string	Specific error code
`error.message`	string	Human-readable error message
`error.type`	string	Error category
`error.details`	object	Additional error context
`request_id`	string	Request identifier for support

Implementation Examples

Here are some examples of how to handle responses in different programming languages.

def handle_transaction_response(response):
    """Handle Tonder API response"""
    
    if response.status_code in [200, 201, 202]:
        data = response.json()
        
        # Check if additional action is required
        if 'next_action' in data:
            return handle_next_action(data)
        
        # Check for payment instructions
        if 'payment_instructions' in data:
            return handle_payment_instructions(data)
        
        # Standard successful response
        return {
            'success': True,
            'transaction_id': data['id'],
            'status': data['status'],
            'amount': data['amount']
        }
    
    else:
        # Handle error response
        error_data = response.json()
        return {
            'success': False,
            'error_code': error_data['error']['code'],
            'error_message': error_data['error']['message'],
            'request_id': error_data.get('request_id')
        }

def handle_next_action(response_data):
    """Handle responses requiring additional action"""
    
    next_action = response_data['next_action']
    
    if 'redirect_to_url' in next_action:
        # 3DS redirect required
        return {
            'success': True,
            'requires_action': True,
            'action_type': 'redirect',
            'redirect_url': next_action['redirect_to_url']['url'],
            'return_url': next_action['redirect_to_url']['return_url']
        }
    
    elif 'iframe_resources' in next_action:
        # Iframe authentication required
        return {
            'success': True,
            'requires_action': True,
            'action_type': 'iframe',
            'iframe_url': next_action['iframe_resources']['external_resource_url']
        }
    
    return {'success': False, 'error': 'Unknown next action'}

def handle_payment_instructions(response_data):
    """Handle cash payment instructions"""
    
    instructions = response_data['payment_instructions']
    
    return {
        'success': True,
        'requires_cash_payment': True,
        'reference_code': instructions['reference_code'],
        'store_name': instructions['store_name'],
        'expiration_date': instructions['expiration_date'],
        'voucher_pdf': response_data.get('voucher_pdf'),
        'instructions': instructions['instructions']
    }

Best Practices

Make sure to follow these best practices to handle responses properly.

Response Processing

Error Handling

Status Management

Next Steps

Learn about Status Checking for monitoring transactions
Set up Webhooks for real-time status updates
Review Error Handling for comprehensive error management
Check Payment Methods for method-specific responses

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

Response Format

Standard Response Structure

Transaction Status Values

Payment Response Examples

Next Action Handling

Payment Instructions Response

Payment Instructions Fields

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Response Headers

Error Response Format

Implementation Examples

Best Practices

Next Steps

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

​Standard Response Structure

​Transaction Status Values

​Payment Response Examples

​Next Action Handling

​Payment Instructions Response

​Payment Instructions Fields

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Response Headers

​Error Response Format

​Implementation Examples

​Best Practices

​Next Steps

Standard Response Structure

Transaction Status Values

Payment Response Examples

Next Action Handling

Payment Instructions Response

Payment Instructions Fields

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Response Headers

Error Response Format

Implementation Examples

Best Practices

Next Steps