Quick Start Guide

Your First Transaction

This guide will walk you through making your first payment using Tonder’s Direct API in the sandbox (also referred as stage) environment.

Prerequisites

Before you begin, make sure you have the following:

Tonder account credentials to sign in at app.tonder.io
API key and secret from your developer dashboard
Basic understanding of REST APIs and HTTP requests

Step 1: Set Up Your Environment

Use the sandbox environment for testing all features without processing real transactions. Use the base URL below when making requests.

Base URL

https://stage.tonder.io/api/v1/

Required Headers

When making requests, you must include these headers:

Authorization: Token <YOUR_SANDBOX_API_KEY>
X-Signature-Transaction: <CALCULATED_HMAC_SIGNATURE>
Content-Type: application/json

Step 2: Implement HMAC Signature

For secure API access, you must generate an HMAC signature for each request. The signature is a hash of the request payload, calculated using your secret key.

Python Implementation

Here is a full example of a Python implementation for generating the signature.

import json
import hmac
import hashlib
import base64

def create_signature(secret_key, filtered_data):
    """Create HMAC signature for API request using filtered data"""
    # Serialize filtered data to JSON with sorted keys and no whitespace
    json_payload = json.dumps(filtered_data, separators=(',', ':'), sort_keys=True)
    
    # Calculate HMAC-SHA256
    signature_bytes = hmac.new(
        secret_key.encode('utf-8'),
        json_payload.encode('utf-8'),
        hashlib.sha256
    ).digest()
    
    # Convert to Base64 string (not hexadecimal)
    return base64.b64encode(signature_bytes).decode('utf-8')

def build_filtered_data(request_data, field_mappings):
    """Build structured data based on business configuration"""
    structured_data = {
        "customer": {
            "firstName": request_data.get("name", ""),
            "lastName": request_data.get("last_name", ""),
            "email": request_data.get("email", ""),
            "phone": request_data.get("phone", ""),
        },
        "currency": request_data.get("currency", "mxn"),
        "metadata": request_data.get("metadata", None),
        "amount": request_data.get("amount", 0),
        "client_reference": request_data.get("client_reference", "")
    }
    
    # Filter data based on field mappings configuration
    return filter_by_mappings(structured_data, field_mappings)

# Example signature creation
request_data = {
    "amount": 1000, 
    "currency": "MXN",
    "customer": {
        "name": "John Doe",
        "email": "john@example.com"
    }
}

field_mappings = ["customer.email", "currency", "amount"]
filtered_data = build_filtered_data(request_data, field_mappings)
signature = create_signature("your_secret_key", filtered_data)

headers = {
    'Content-Type': 'application/json',
    'X-Signature-Transaction': signature
}

Step 3: Make Your First Payment

Make your first payment by sending a POST request to the process endpoint. You can use the following request body to test a card payment.

Basic Card Payment Request

This is an example request to the process endpoint.

{
  "operation_type": "payment",
  "amount": 100.00,
  "currency": "MXN",
  "customer": {
    "name": "Test Customer",
    "email": "test@example.com"
  },
  "payment_method": {
    "type": "CARD",
    "card_number": "9230-0892-4469-1474",
    "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b",
    "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",
    "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e",
    "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063"
  },
  "client_reference": "test-payment-001"
}

Expected Response

A successful request returns a 201 Created status code and a transaction object.

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

Status Check Request

After a payment is initiated, you can check its status by making a GET request.

GET /transactions/{transaction_id}/

The expected response is as follows:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "success",
  "amount": 150.00,
  "currency": "MXN",
  "merchant_reference": "test-payment-001",
  "created_at": "2024-07-26T10:30:00Z",
  "updated_at": "2024-07-26T10:32:15Z",
  "completion_details": {
    "completed_at": "2024-07-26T10:32:15Z",
    "authorization_code": "AUTH123456"
  }
}

Test Different Payment Methods

After successfully completing the card payment, you can experiment with other payment methods. Below are the example request bodies for SPEI and OXXO cash payments.

{
  "operation_type": "payment",
  "amount": 500.00,
  "currency": "MXN",
  "customer": {
    "name": "Carlos Eduardo López",
    "email": "carlos.lopez@empresa.mx"
  },
  "payment_method": {
    "type": "SPEI"
  },
  "client_reference": "spei-test-001"
}

Test Data for Different Scenarios

The following tables provide test data for various scenarios and expected outcomes.

Test Cards

Card Number	Scenario	Expected Result
4242424242424242	Successful payment	`authorized` status
4000000000000002	Card declined	`declined` status
4000000000009995	Insufficient funds	`declined` status
4000000000000119	3D Secure required	`pending` with redirect
4000000000000341	Processing error	`failed` status

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

Complete Test Flow Example

This is a complete test flow example of an implementation in Python.

import requests
import json

# Sandbox configuration
SANDBOX_URL = "https://stage.tonder.io/api/v1/"
API_KEY = "your_sandbox_api_key"

def test_successful_payment():
    """Test a successful card payment"""
    
    # Payment request
    payment_data = {
        "operation_type": "payment",
        "amount": 100.00,
        "currency": "MXN",
        "customer": {
            "name": "Test Customer",
            "email": "test@example.com"
        },
        "payment_method": {
            "type": "CARD",
            "card_number": "9230-0892-4469-1474",
            "cardholder_name": "c05d89b2-299c-4f93-b49a-42be00d3b64b",
            "cvv": "d31f0da3-0ed3-4ad8-8b68-14c2669a99a7",
            "expiration_month": "e401a32e-4174-424f-9688-727005f6a80e",
            "expiration_year": "bd9ccc23-3d00-4109-9626-fc6581389063"
        },
        "client_reference": "test-payment-001"
    }
    
    headers = {
        'Authorization': f'Token {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    # Make payment request
    response = requests.post(
        f"{SANDBOX_URL}process/",
        headers=headers,
        json=payment_data
    )
    
    if response.status_code == 201:
        result = response.json()
        print(f"Payment successful! Transaction ID: {result['id']}")
        return result['id']
    else:
        print(f"Payment failed: {response.status_code}")
        return None

def check_transaction_status(transaction_id):
    """Check the status of a transaction"""
    
    headers = {
        'Authorization': f'Token {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(
        f"{SANDBOX_URL}transactions/{transaction_id}/",
        headers=headers
    )
    
    if response.status_code == 200:
        result = response.json()
        print(f"Transaction status: {result['status']}")
        return result
    else:
        print(f"Status check failed: {response.status_code}")
        return None

# Run the test
if __name__ == "__main__":
    # Test payment
    transaction_id = test_successful_payment()
    
    if transaction_id:
        # Check status
        check_transaction_status(transaction_id)

Common Testing Scenarios

Before going live, it’s a good idea to run through these typical test cases to make sure your integration is working as expected:

Successful Payment

Declined Payment

3D Secure Challenge

OXXO Cash Payment

Troubleshooting

If you run into issues during testing, here are some common problems and how to resolve them:

Issue	What to Do
401 Authentication Error	Double-check your API key – is it correct and in the right format?
422 Validation Error	Make sure all required fields are present and data formats are valid
500 Server Error	Try again, and if it keeps happening, contact support
Rate limit exceeded	Add a delay and implement exponential backoff before retrying

What’s Next?

Review Payment Methods – Explore all the payment options you can offer
Set Up Webhooks – Get real-time updates on transaction events
Implement Error Handling – Make sure your app handles failures smoothly
Go Live – Follow the Production Readiness checklist to launch safely

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

Quick Start Guide

Your First Transaction

Prerequisites

Step 1: Set Up Your Environment

Required Headers

Step 2: Implement HMAC Signature

Step 3: Make Your First Payment

Test Different Payment Methods

Test Data for Different Scenarios

Test Cards

Test Bank Accounts

Complete Test Flow Example

Common Testing Scenarios

Troubleshooting

What’s Next?

Getting Started

API Reference

Payment Processing

Integration

Regional Reference

Resources

​Your First Transaction

​Prerequisites

​Step 1: Set Up Your Environment

​Required Headers

​Step 2: Implement HMAC Signature

​Step 3: Make Your First Payment

​Test Different Payment Methods

​Test Data for Different Scenarios

​Test Cards

​Test Bank Accounts

​Complete Test Flow Example

​Common Testing Scenarios

​Troubleshooting

​What’s Next?

Your First Transaction

Prerequisites

Step 1: Set Up Your Environment

Required Headers

Step 2: Implement HMAC Signature

Step 3: Make Your First Payment

Test Different Payment Methods

Test Data for Different Scenarios

Test Cards

Test Bank Accounts

Complete Test Flow Example

Common Testing Scenarios

Troubleshooting

What’s Next?