Procesar transacción

Procesa pagos y retiros con una sola llamada. Este endpoint unificado maneja todos los tipos de transacción según el campo `operation_type`.

Autorización

Authorization

Authorization<token>

Your public API key, with the word Token and a space in front of it. Example: Token 6534bc0a7e1f4d2b9c8e3a5f7b1d2c4e6f8a9b0c — that whole value is the header. Sending the key alone returns 401 'Authentication credentials were not provided'. In this playground you may paste just the key; the prefix is added for you.

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. For CLP withdrawals, a whole number of pesos with no decimal part (also accepted as a string, e.g. "50000"); a fractional amount is rejected with 400.

currency?string

Currency code. Mexico, Chile and Colombia use the same flow — only this value changes (MXN, CLP or COP). Argentina uses ARS: if currency is omitted there it defaults to MXN and the request is rejected with currency_mismatch.

country?string

Optional ISO 3166-1 alpha-2 country code. AR sets currency to ARS. On Chile withdrawals, CL; when omitted it defaults to your business's country.

customer?

The paying customer. Required for payments; not used on withdrawals.

client_reference?string

Your reference identifier. Returned in the response and in the webhooks. Recommended on withdrawals. Required, and not empty, for Argentina bank transfers (payment_method.type: transfer).

metadata?

Your own data, stored and returned as is. On withdrawals, latitude and longitude are recommended for operations in Mexico.

return_url?string

URL for redirection after 3DS processing

payment_method?

threeDomainSecure?

External 3DS — the result of a 3-D Secure authentication you ran with your own provider. Send it at the top level of the request (nested inside payment_method it is ignored and Tonder runs its own 3DS). Direct API only; the account must be enabled for External 3DS. Full guide: /docs/api-reference/payments/external-3ds.

transfer_method?string

Withdrawals only. SPEI sends to an 18-digit CLABE; DEBIT_CARD sends to a 16-digit debit card number. Nothing else changes between the two. BANK_TRANSFER sends ARS to a CBU, CVU or alias in Argentina, and is the only value there. CLP_TRANSFER sends CLP to a checking or sight account in Chile, and is the only value there.

description?string

Withdrawals only. Payment concept; defaults to Retiro de fondos if omitted.

beneficiary?

fee_model?string

SPEI and debit-card withdrawals (Mexico). Required; always "01".

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",
  "withdrawal_id": "5a27414e-14a7-4e08-9823-6274a2900c69",
  "transfer_method": "SPEI",
  "operation_type": "payment",
  "status": "Pending",
  "amount": 0,
  "currency": "string",
  "client_reference": "string",
  "payment_method_type": "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"
    },
    "display_qr_code": {
      "qr_string": "string",
      "amount": 0,
      "currency": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "verify_transaction_status_url": "string"
    },
    "display_bank_transfer": {
      "account_type": "string",
      "account_number": "string",
      "alias": "string",
      "holder_name": "string",
      "holder_tax_id": "string",
      "amount": 0,
      "currency": "string",
      "reference": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "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",
  "withdrawal_id": "5a27414e-14a7-4e08-9823-6274a2900c69",
  "transfer_method": "SPEI",
  "operation_type": "payment",
  "status": "Pending",
  "amount": 0,
  "currency": "string",
  "client_reference": "string",
  "payment_method_type": "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"
    },
    "display_qr_code": {
      "qr_string": "string",
      "amount": 0,
      "currency": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "verify_transaction_status_url": "string"
    },
    "display_bank_transfer": {
      "account_type": "string",
      "account_number": "string",
      "alias": "string",
      "holder_name": "string",
      "holder_tax_id": "string",
      "amount": 0,
      "currency": "string",
      "reference": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "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",
  "withdrawal_id": "5a27414e-14a7-4e08-9823-6274a2900c69",
  "transfer_method": "SPEI",
  "operation_type": "payment",
  "status": "Pending",
  "amount": 0,
  "currency": "string",
  "client_reference": "string",
  "payment_method_type": "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"
    },
    "display_qr_code": {
      "qr_string": "string",
      "amount": 0,
      "currency": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "verify_transaction_status_url": "string"
    },
    "display_bank_transfer": {
      "account_type": "string",
      "account_number": "string",
      "alias": "string",
      "holder_name": "string",
      "holder_tax_id": "string",
      "amount": 0,
      "currency": "string",
      "reference": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "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"
}

Ejemplos por tipo de operación

El ejemplo de arriba es un pago con tarjeta tokenizada. El mismo endpoint cubre los demás casos: cambia operation_type y los campos propios del método.

Pago SPEI

{
  "operation_type": "payment",
  "amount": 500.00,
  "currency": "MXN",
  "customer": { "name": "Carlos Eduardo López", "email": "carlos.lopez@empresa.mx" },
  "payment_method": { "type": "SPEI" },
  "client_reference": "invoice-456"
}

El flujo completo —referencia de pago, expiración y conciliación— está en Pagos APM.

Retiro SPEI

{
  "operation_type": "withdrawal",
  "amount": 20.00,
  "currency": "MXN",
  "client_reference": "payout-001",
  "transfer_method": "SPEI",
  "description": "Pago de comisiones",
  "beneficiary": {
    "account": "012969100000000110",
    "name": "Ana Maria Gonzalez",
    "rfc": "GOAN850315AB2",
    "institution": "40012",
    "email": "ana.gonzalez@email.com"
  },
  "metadata": {
    "latitude": "22.8870221",
    "longitude": "-109.911775",
    "order_reference": "ORD-001"
  },
  "fee_model": "01"
}

La respuesta trae dos identificadores: id es la transacción (úsalo con GET /transactions/{id}/) y withdrawal_id es el retiro (úsalo para aprobarlo y leer su detalle). Un retiro nuevo se queda en Pending hasta que lo apruebas con POST /withdrawals/perform_action/. Aprobación, estados, webhooks y datos de prueba están en Retiros.

Pago con QR en Argentina

{
  "operation_type": "payment",
  "amount": 15000.00,
  "currency": "ARS",
  "customer": { "name": "Juan Pérez", "email": "juan.perez@email.com" },
  "payment_method": { "type": "qr", "apm_config": { "expires_in": 1800 } },
  "client_reference": "ORD-001",
  "metadata": { "external_id": "ORD-001" }
}

Las transferencias a una CVU ("type": "transfer") y los pagos a una CBU, CVU o alias están en Argentina.

Pago con tarjeta con External 3DS

Si autenticaste al tarjetahabiente con tu propio proveedor de 3DS, pasa el resultado en un objeto threeDomainSecure de nivel superior (y la red en payment_method.card_brand). Tonder cobra con él — sin reto. Requiere habilitación en la cuenta; solo API Direct.

{
  "operation_type": "payment",
  "amount": 150.00,
  "currency": "MXN",
  "customer": { "name": "Jane Doe", "email": "jane@testuser.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",
    "card_brand": "mastercard"
  },
  "threeDomainSecure": {
    "ucaf": "kCO52e75N318oAB3MPZU6EhB2Td6",
    "eci": "02",
    "directoryServerTransactionID": "9e8c4ff6-23d9-4fba-8446-6e8e9d13f42e",
    "specificationVersion": "2.2.0"
  },
  "client_reference": "ORD-001",
  "return_url": "https://tonder.io"
}

Campos, reglas de ECI, ubicación y errores están en External 3DS.

Retiro en Chile

Los retiros en Chile usan transfer_method: "CLP_TRANSFER", currency: "CLP", un amount en pesos enteros y un beneficiary chileno (cuenta, account_type, id de institución del banco y RUT). La petición completa está en Retiros en Chile.

Pagos con Apple Pay

Para cobrar un token de Apple Pay, usa payment_method.type con el valor "APPLE_PAY" y envía el token en payment_method.token.

Hay dos formas de integrarlo. Elige la que corresponda a tu comercio:

Managed: Tonder valida el comercio y muestra el botón con el Web SDK. Este flujo no requiere el campo apm_config.
Bring Your Own: usas tu propio Merchant ID. Envías el token con apm_config.apple_pay_integration: "V2". Guía: Bring Your Own.

Campo	Descripción
`payment_method.type`	`APPLE_PAY`
`payment_method.token`	El objeto `PKPaymentToken` completo que devuelve Apple Pay. Debe incluir `paymentData`
`payment_method.apm_config.apple_pay_integration`	Obligatorio en Bring Your Own. Envía `"V2"`.

Respuesta por modo no coincidente (HTTP 400):

{
  "error": {
    "code": "apple_pay_integration_mismatch",
    "message": "apm_config.apple_pay_integration does not match the Apple Pay integration mode enabled for this business",
    "type": "bad_request"
  }
}

Pago no autorizado (HTTP 402):

{
  "error": {
    "code": "payment_declined",
    "message": "The payment could not be authorized",
    "type": "business_error",
    "details": { "reason": "upstream_decline" }
  },
  "request_id": "<id>"
}

Para el ejemplo completo del request y la configuración de tu negocio, consulta Bring Your Own.

Procesar transacción

200application/json

201application/json

202application/json

400application/json

401application/json

402application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`