Quickstart

Your first server-to-server payment in the sandbox, with the full headers and body.

API Direct gives you full control over the payment flow by calling Tonder's API straight from your server. This quickstart walks you through making your first test payment in the sandbox — no real money moves.

What you'll build: a POST request to the Process Transaction endpoint that charges a test card and returns a transaction you can track.

Before you begin

Retrieve it from Developers → API Keys. You authenticate every request with it.

Step 1: Set up your environment

Use the sandbox for all testing — it validates your integration end to end without processing real money. The base URL for every test request is https://stage.tonder.io/api/v1/. Every request must include these headers:

Header	Description
`Authorization`	Your API key, as `Token <YOUR_SANDBOX_API_KEY>`.
`X-Request-Id`	A UUID v4 generated per request. It's the idempotency key, not an authentication header (see Idempotency).
`Content-Type`	`application/json`.

Step 2: Make your first payment

Send a POST to the Process Transaction endpoint with these parameters. This first test payment sends raw card data (only valid for PCI Level 1 certified merchants); most merchants instead use the tokenized flow described in Card payments, where these same fields are replaced with tokens you get from the tokenization service.

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"`).
`customer`	object	Customer info with `name` and `email`.
`payment_method`	object	Method details including `type` and card information.
`client_reference`	string	Your unique reference for this transaction.
`return_url`	string	Where the customer returns after finishing (for example, after a 3DS challenge).

Test cards only work in sandbox (stage.tonder.io). In production use a real card — the same request with a test card will be declined. See Test cards.

curl -X POST https://stage.tonder.io/api/v1/process/ \
  -H "Authorization: Token <YOUR_SANDBOX_API_KEY>" \
  -H "X-Request-Id: <uuid-v4>" \
  -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": "4000000000000077",
      "cardholder_name": "Ozzy Osbourne",
      "cvv": "123",
      "expiration_month": "07",
      "expiration_year": "26"
    },
    "client_reference": "ORD-001",
    "return_url": "https://tonder.io"
  }'

curl -X POST https://app.tonder.io/api/v1/process/ \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "X-Request-Id: <uuid-v4>" \
  -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": "<REAL_CARD_NUMBER>",
      "cardholder_name": "Ozzy Osbourne",
      "cvv": "<CVV>",
      "expiration_month": "07",
      "expiration_year": "30"
    },
    "client_reference": "ORD-001",
    "return_url": "https://tonder.io"
  }'

A successful request returns 201 Created with a transaction object:

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

Field	Description
`transaction_id`	Unique identifier for this payment in Tonder's system.
`status`	Current payment status (e.g. `authorized`, `pending`, `declined`).
`payment_id`	Internal payment ID for tracking and reference.
`client_reference`	Your original reference for this transaction.

Use the transaction_id to check status, set up webhooks, or view the transaction in your dashboard.

Quickstart

Before you begin

Step 1: Set up your environment

Step 2: Make your first payment

Next steps

Authentication

Card payments

APM payments

Payment methods

On this page