Start using Tonder Direct Integration

This guide will walk you through making your first test payment using Tonder’s Direct API in the sandbox environment.

Prerequisites

Before you begin, make sure you have the following:

Sign in at the Tonder Dashboard with your credentials.
Retrieve your API Key and Secret from the developer section of the dashboard.

Step 1: Set Up Your Environment

You’ll use the sandbox environment for all testing. This allows you to validate your integration end-to-end without processing real money. Use the following base URL for all your test requests:

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

Required Headers

Every request to the Tonder API must include the following headers:

Header	Description
Authorization	Contains your unique API key.
X-Signature-Transaction	Includes the HMAC signature to verify the integrity of the request. Authentication will fail if this is missing or incorrect.
Content-Type	Specifies that the request body is in JSON format.

Here’s an example of how to include these headers in your request:

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

Step 2: Implement the HMAC Signature

To secure your API requests, Tonder uses HMAC-SHA256 signatures to verify that requests are authentic and haven’t been tampered with. For every request that includes a body (like POST or PUT requests), you must generate a unique signature by creating a hash of the request payload using your secret key. This signature proves that the request comes from you and that the data hasn’t been modified in transit.

Python Example: HMAC Signature Generation

This example shows how to create an HMAC-SHA256 signature for a payment request and generate the authentication header needed for API calls. The code follows three key steps: serialize the JSON payload with sorted keys for consistency, calculate the HMAC-SHA256 digest using your secret key, and encode the resulting signature in Base64 format.

import json
import hmac
import hashlib
import base64

def create_signature(secret_key, request_body):
"""Create an HMAC-SHA256 signature for an API request."""

# Serialize the JSON payload with sorted keys and no whitespace.

# This ensures a consistent string for hashing.

json_payload = json.dumps(request_body, separators=(',', ':'), sort_keys=True)

# Calculate the HMAC-SHA256 digest.

signature_bytes = hmac.new(
secret_key.encode('utf-8'),
json_payload.encode('utf-8'),
hashlib.sha256
).digest()

# Encode the resulting signature in Base64.

return base64.b64encode(signature_bytes).decode('utf-8')

secret_key = "your_secret_key"
request_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"
}

# Generate the signature

signature = create_signature(secret_key, request_data)

print(f"Calculated Signature: {signature}")

HMAC validation is configurable for your business. The Direct API Process Transaction endpoint uses HMAC authentication by default. The specific fields used to generate the signature can also be configured. This example assumes the entire request body is used.

Step 3: Make Your First Payment

Now you’re ready to make your first payment. Send a POST request to the Process Transaction endpoint with a request body including the required parameters below:

Parameter	Type	Description
operation_type	string	Must be `"payment"` to process a payment
amount	number	Payment amount (e.g., `100.00`)
currency	string	Currency code (e.g., `"MXN"` for Mexican Peso)
customer	object	Customer information containing `name` and `email`
payment_method	object	Payment method details including `type` and card information
client_reference	string	Your unique reference for this transaction

The following example demonstrates a complete payment request using test card data:

curl -X POST https://stage.tonder.io/api/v1/process/ \
-H "Authorization: Token <YOUR_SANDBOX_API_KEY>" \
-H "X-Signature-Transaction: <CALCULATED_HMAC_SIGNATURE>" \
-H "Content-Type: application/json" \
-d '{
  "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"
}'

import requests
import json
# Assuming the create_signature function from Step 2 is defined

# Configuration
SANDBOX_URL = "https://stage.tonder.io/api/v1/process/"
API_KEY = "your_sandbox_api_key"
SECRET_KEY = "your_secret_key"

# Payment request body
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"
}

# Generate signature
signature = create_signature(SECRET_KEY, payment_data)

# Set headers
headers = {
    'Authorization': f'Token {API_KEY}',
    'X-Signature-Transaction': signature,
    'Content-Type': 'application/json'
}

# Make the request
response = requests.post(
    SANDBOX_URL,
    headers=headers,
    json=payment_data
)

# Print the result
if response.status_code == 201:
    result = response.json()
    print(f"Payment successful! Transaction ID: {result['id']}")
else:
    print(f"Payment failed: {response.status_code}")
    print(response.text)

If your request is successful, you’ll receive a 201 Created status code and a transaction object in the response body.

{
  "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
}

The response contains key information for managing your payment:

Field	Description
transaction_id	Unique identifier for this payment in Tonder’s system
status	Current payment status (e.g., “approved”, “pending”, “declined”)
payment_id	Internal payment ID for tracking and reference
merchant_reference	Your original client reference for this transaction
provider	Payment processor used (e.g., “stripe”, “conekta”)

Use the transaction_id to check payment status later, set up webhooks to receive real-time updates, or view transaction details in your dashboard.

Next Steps

Check out environments to understand sandbox vs production setup.
Set up proper authentication for secure API access.
Get to know the full process for going live with your integration.

Introduction

Direct Integration Guides

Webhooks

Reference Pages

Payment Methods

Resources

Start using Tonder Direct Integration

Prerequisites

Step 1: Set Up Your Environment

Required Headers

Step 2: Implement the HMAC Signature

Step 3: Make Your First Payment

Next Steps

​Prerequisites

​Step 1: Set Up Your Environment

​Required Headers

​Step 2: Implement the HMAC Signature

​Step 3: Make Your First Payment

​Next Steps

Prerequisites

Step 1: Set Up Your Environment

Required Headers

Step 2: Implement the HMAC Signature

Step 3: Make Your First Payment

Next Steps