SupportLog in
DocsAPI ReferenceSDK ReferenceResourcesChangelog
Direct API (S2S)

Overview

The unified `/process/` endpoint: one contract for payments, APMs and withdrawals.

API Direct (Tonder Direct) is a unified payment-processing API that lets you accept payments and send withdrawals across Latin America. Instead of managing complex integrations for each method or country, you handle everything with a single call to the /process/ endpoint.

Key features

  • Single endpoint. All payments and withdrawals go through the unified /process/ endpoint. You specify the operation type and Tonder routes it automatically.
  • Instant response. Real-time processing with immediate status updates.
  • Regional methods. Native support for SPEI, OXXO Pay, Cash vouchers, MercadoPago, and cards across MX · CO · CL.
  • Secure by design. The tokenization service handles sensitive card data. Two flows: tokenized (lower PCI scope) and raw card data (requires PCI L1).

How it works

The API is built around simplicity: a single /process/ endpoint that covers all your transaction needs. When you send a request, you specify what type of operation you want to perform and the system routes it to the right processor. The same structure processes card, SPEI, OXXO, and other payments, as well as withdrawals.

Source of truth: GET /api/v1/transactions/{id}/. Never rely solely on the initial response; always verify the status here.

Endpoints and authentication

ServiceSandboxProduction
API Direct (S2S)https://stage.tonder.io/api/v1/https://app.tonder.io/api/v1/
Hosted Checkouthttps://api-stage.tonder.io/checkout/v1/https://api.tonder.io/checkout/v1/
Card tokenizationhttps://token-sandbox.tonder.io/https://token.tonder.io/
Raw card data (PCI L1)https://process-sandbox.tonder.io/https://process.tonder.io/
Dashboardhttps://dashboard-stage.tonder.io/https://dashboard.tonder.io/
VerbOperationEndpointNotes
POSTNon-card payments (APMs)/api/v1/process/No tokenization or PCI L1 required — just your API key
GETGet access token (tokenization)/api/v1/tokenization/auth/Required before tokenizing a card · uses your API key
POSTTokenize card dataSandbox: https://token-sandbox.tonder.io/v1/gateway/inboundRoutes/{route_id}/token · Production: https://token.tonder.io/v1/gateway/inboundRoutes/{route_id}/tokenRequires the access_token from tokenization/auth first · the endpoint lives on a different domain, not under Tonder's /api/v1/ · the route_id differs per environment — don't mix stage with production
POSTTokenized card payment/api/v1/process/Send the tokens in payment_method · reduced PCI scope (SAQ A / SAQ A-EP)
POSTRaw card dataprocess[-sandbox].tonder.io/raw-dataRequires PCI DSS Level 1
GETTransaction status/api/v1/transactions/{id}/Source of truth — always verify here
POSTWithdrawal/api/v1/process/Server-side only — API key required

Headers for POST /process/ requests:

Authorization: Token YOUR_API_KEY
X-Request-Id: <uuid-v4>
Content-Type: application/json

X-Request-Id is not an authentication header — it's the idempotency key used to deduplicate retries (see Idempotency). Full details on both in Authentication.

PCI scope

Integration modePCI certification required
Hosted CheckoutNone — Tonder hosts card capture
SDK (Full or Lite)None — card data is tokenized on the client
HybridNone — cards flow through the SDK/Hosted leg
API Direct (S2S) — tokenized flowSAQ A or SAQ A-EP — the card is tokenized before it reaches you
API Direct (S2S) — raw card dataPCI DSS Level 1 — the card passes through your servers

Webhooks

API Direct receives webhooks in Short format. Reconcile on metadata.external_id. See the Webhooks model.

API reference

The unified payments and withdrawals endpoint, and the status lookup (source of truth):

POST
/process/

Authorization

Authorization
Authorization<token>

Tu API key con prefijo Token , p. ej. Token <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/process/" \  -H "Content-Type: application/json" \  -d '{    "operation_type": "payment",    "amount": 150,    "currency": "MXN",    "customer": {      "name": "Ana María Rodríguez",      "email": "ana.rodriguez@email.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": "order-789",    "return_url": "https://mystore.com/payment/return"  }'
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "operation_type": "payment",
  "status": "Pending",
  "amount": 0,
  "currency": "string",
  "client_reference": "string",
  "payment_id": 0,
  "transaction_id": "string",
  "provider": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "status_code": 0,
  "next_action": {
    "redirect_to_url": {
      "url": "http://example.com",
      "return_url": "http://example.com",
      "verify_transaction_status_url": "string"
    }
  },
  "payment_instructions": {
    "reference": "string",
    "account_number": "string",
    "bank_name": "string",
    "amount": 0,
    "expires_at": "2019-08-24T14:15:22Z",
    "reference_code": "string",
    "barcode": "string",
    "store_name": "string",
    "expiration_date": "2019-08-24T14:15:22Z",
    "instructions": [
      "string"
    ],
    "voucher_pdf": "http://example.com"
  }
}
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "operation_type": "payment",
  "status": "Pending",
  "amount": 0,
  "currency": "string",
  "client_reference": "string",
  "payment_id": 0,
  "transaction_id": "string",
  "provider": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "status_code": 0,
  "next_action": {
    "redirect_to_url": {
      "url": "http://example.com",
      "return_url": "http://example.com",
      "verify_transaction_status_url": "string"
    }
  },
  "payment_instructions": {
    "reference": "string",
    "account_number": "string",
    "bank_name": "string",
    "amount": 0,
    "expires_at": "2019-08-24T14:15:22Z",
    "reference_code": "string",
    "barcode": "string",
    "store_name": "string",
    "expiration_date": "2019-08-24T14:15:22Z",
    "instructions": [
      "string"
    ],
    "voucher_pdf": "http://example.com"
  }
}
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "operation_type": "payment",
  "status": "Pending",
  "amount": 0,
  "currency": "string",
  "client_reference": "string",
  "payment_id": 0,
  "transaction_id": "string",
  "provider": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "status_code": 0,
  "next_action": {
    "redirect_to_url": {
      "url": "http://example.com",
      "return_url": "http://example.com",
      "verify_transaction_status_url": "string"
    }
  },
  "payment_instructions": {
    "reference": "string",
    "account_number": "string",
    "bank_name": "string",
    "amount": 0,
    "expires_at": "2019-08-24T14:15:22Z",
    "reference_code": "string",
    "barcode": "string",
    "store_name": "string",
    "expiration_date": "2019-08-24T14:15:22Z",
    "instructions": [
      "string"
    ],
    "voucher_pdf": "http://example.com"
  }
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
GET
/transactions/{transaction_id}/

Authorization

Authorization
Authorization<token>

Tu API key con prefijo Token , p. ej. Token <API_KEY>

In: header

Path Parameters

transaction_id*string

The unique transaction identifier returned from the /process/ endpoint

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/transactions/550e8400-e29b-41d4-a716-446655440000/"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "operation_type": "payment",
  "status": "Success",
  "amount": 150,
  "currency": "MXN",
  "client_reference": "ORD-001",
  "created_at": "2024-07-26T10:30:00Z",
  "updated_at": "2024-07-26T10:32:15Z",
  "completion_details": {
    "completed_at": "2024-07-26T10:32:15Z"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}
{
  "error": {
    "code": "string",
    "message": "string",
    "type": "request_error",
    "details": {}
  },
  "request_id": "string"
}

Next steps

Quickstart

Your first test payment in the sandbox.

Migrate to the Web SDK

Move your checkout to the browser without changing your backend.

Authentication

API key, headers, and tokenization in depth.

Card payments

Tokenized flow and raw card data.

APM payments

SPEI, OXXO, and other methods.

Withdrawals

Payouts to beneficiaries with operation_type: "withdrawal".

Was this page helpful?

Mobile (Flutter · Ionic · React Native)

The iOS, Android, React Native, Flutter and Ionic SDKs, and which flow each one covers.

Quickstart

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

On this page

Key featuresHow it worksEndpoints and authenticationPCI scopeWebhooksAPI referenceNext steps