Resumen

API Direct (Tonder Direct) es una API de procesamiento de pagos unificada que te permite aceptar pagos y enviar retiros en América Latina. En lugar de manejar integraciones complejas por cada método o país, gestionas todo con una sola llamada al endpoint /process/.

Características clave

Un solo endpoint. Todos los pagos y retiros pasan por el endpoint unificado /process/. Tú indicas el tipo de operación y Tonder lo enruta automáticamente.
Respuesta instantánea. Procesamiento en tiempo real con actualizaciones de estado inmediatas.
Métodos regionales. Soporte nativo para SPEI, OXXO Pay, Cash vouchers, MercadoPago y tarjetas en MX · CO · CL.
Seguro por diseño. El servicio de tokenización maneja los datos sensibles de la tarjeta. Dos flujos: tokenizado (menor alcance PCI) y datos en crudo (requiere PCI L1).

Cómo funciona

La API se basa en la simplicidad: un único endpoint /process/ que cubre todas tus necesidades de transacción. Cuando envías una petición, especificas qué tipo de operación quieres realizar y el sistema la enruta al procesador correcto. La misma estructura procesa pagos con tarjeta, SPEI, OXXO y otros métodos, y también retiros.

Fuente de verdad: GET /api/v1/transactions/{id}/. Nunca confíes solo en la respuesta inicial; verifica siempre el estado aquí.

Endpoints y autenticación

Servicio	Sandbox	Producción
API Direct (S2S)	`https://stage.tonder.io/api/v1/`	`https://app.tonder.io/api/v1/`
Hosted Checkout	`https://api-stage.tonder.io/checkout/v1/`	`https://api.tonder.io/checkout/v1/`
Tokenización de tarjetas	`https://token-sandbox.tonder.io/`	`https://token.tonder.io/`
Datos de tarjeta en crudo (PCI L1)	`https://process-sandbox.tonder.io/`	`https://process.tonder.io/`
Dashboard	`https://dashboard-stage.tonder.io/`	`https://dashboard.tonder.io/`

Verbo	Operación	Endpoint	Notas
POST	Pagos no-tarjeta (APMs)	`/api/v1/process/`	No requiere tokenización ni PCI L1 — solo tu llave API
GET	Obtener access token (tokenización)	`/api/v1/tokenization/auth/`	Requerido antes de tokenizar una tarjeta · usa tu llave API
POST	Tokenizar datos de tarjeta	Sandbox: `https://token-sandbox.tonder.io/v1/gateway/inboundRoutes/{route_id}/token` · Producción: `https://token.tonder.io/v1/gateway/inboundRoutes/{route_id}/token`	Requiere el `access_token` de `tokenization/auth` primero · el endpoint vive en un dominio distinto, no bajo `/api/v1/` de Tonder · el `route_id` de la ruta es distinto por ambiente, no confundas stage con producción
POST	Pago con tarjeta tokenizada	`/api/v1/process/`	Envía los tokens en `payment_method` · alcance PCI reducido (SAQ A / SAQ A-EP)
POST	Datos de tarjeta en crudo	`process[-sandbox].tonder.io/raw-data`	Requiere PCI DSS Nivel 1
GET	Estado de transacción	`/api/v1/transactions/{id}/`	Fuente de verdad — verifica siempre aquí
POST	Retiro	`/api/v1/process/`	Solo server-side — requiere la llave API

Headers para peticiones POST /process/:

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

X-Request-Id no es un header de autenticación — es la llave de idempotencia para deduplicar reintentos (ver Idempotencia). Detalles completos de ambos en Autenticación.

Alcance PCI

Modo de integración	Certificación PCI requerida
Hosted Checkout	Ninguna — Tonder aloja la captura de la tarjeta
SDK (Full o Lite)	Ninguna — los datos de tarjeta se tokenizan en el cliente
Híbrido	Ninguna — las tarjetas pasan por el leg de SDK/Hosted
API Direct (S2S) — flujo tokenizado	SAQ A o SAQ A-EP — la tarjeta se tokeniza antes de llegar a ti
API Direct (S2S) — datos en crudo	PCI DSS Nivel 1 — la tarjeta pasa por tus servidores

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

In: header

Cuerpo de la petición

application/json

TypeScript Definitions

Use the request body type in TypeScript.

operation_type*string

Type of transaction to process

amount*number

Transaction amount

currency?string

Currency code. Mexico and Chile use the same flow — only this value changes (MXN vs CLP).

customer*

client_reference?string

Your reference identifier

metadata?

Additional data for your records

return_url?string

URL for redirection after 3DS processing

payment_method?

transfer_method?string

Transfer method for withdrawals

reference?string

Your withdrawal reference

description?string

Withdrawal description

beneficiary?

Cuerpo de la respuesta

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

Autorización

Authorization

Authorization<token>

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

In: header

Parámetros de ruta

transaction_id*string

The unique transaction identifier returned from the /process/ endpoint

Cuerpo de la respuesta

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

Resumen

Características clave

Cómo funciona

Endpoints y autenticación

Alcance PCI

Webhooks

Referencia de la API

Autorización

Cuerpo de la petición

Cuerpo de la respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Autorización

Parámetros de ruta

Cuerpo de la respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Siguientes pasos

Inicio rápido

Migrar al Web SDK

Autenticación

Pagos con tarjeta

Pagos APM

Retiros

En esta página

Resumen

200application/json

201application/json

202application/json

400application/json

401application/json

402application/json

422application/json

429application/json

500application/json

200application/json

400application/json

401application/json

404application/json

500application/json

Successful card payment

SPEI payment still pending (asynchronous method)

Withdrawal sent to the provider

Inicio rápido

Migrar al Web SDK

Autenticación

Pagos con tarjeta

Pagos APM

Retiros

En esta página

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`