> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tonder.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

1. Sign in at the [Tonder Dashboard](https://app.tonder.io) with your credentials.
2. Retrieve your API Key and Secret from the [developer section](/dashboard/dev-api-keys) 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:

```bash theme={null}
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:

```http theme={null}
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.

<Accordion title="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.

  ```python theme={null}
  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}")

  ```
</Accordion>

<Note>
  HMAC validation is configurable for your business. The Direct API [Process Transaction](/reference/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.
</Note>

## Step 3: Make Your First Payment

Now you're ready to make your first payment. Send a `POST` request to the [Process Transaction](/reference/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:

<CodeGroup>
  ```bash cURL Example theme={null}
  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"
  }'
  ```

  ```python Python Example theme={null}
  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)
  ```
</CodeGroup>

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

```json theme={null}
{
  "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](/reference/get-transaction-status) later, set up [webhooks](/direct-integration/webhooks/how-webhooks-works) to receive real-time updates, or view transaction details in your [dashboard](/dashboard/transactions).

## Next Steps

* Check out [environments](/direct-integration/environment) to understand sandbox vs production setup.
* Set up proper [authentication](/direct-integration/authentication) for secure API access.
* Get to know the [full process for going live](/direct-integration/process-overview) with your integration.