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:
  1. Sign in at the Tonder Dashboard with your credentials.
  2. 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:
HeaderDescription
AuthorizationContains your unique API key.
X-Signature-TransactionIncludes the HMAC signature to verify the integrity of the request. Authentication will fail if this is missing or incorrect.
Content-TypeSpecifies 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.
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:
ParameterTypeDescription
operation_typestringMust be "payment" to process a payment
amountnumberPayment amount (e.g., 100.00)
currencystringCurrency code (e.g., "MXN" for Mexican Peso)
customerobjectCustomer information containing name and email
payment_methodobjectPayment method details including type and card information
client_referencestringYour 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"
}'
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:
FieldDescription
transaction_idUnique identifier for this payment in Tonder’s system
statusCurrent payment status (e.g., “approved”, “pending”, “declined”)
payment_idInternal payment ID for tracking and reference
merchant_referenceYour original client reference for this transaction
providerPayment 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