Process Transaction

Process both payments and withdrawals through a single API call. This unified endpoint handles all transaction types based on the `operation_type` field.

Authorization

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

Request Body

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".

Response Body

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

Examples by operation type

The example above is a tokenized card payment. The same endpoint covers the other cases: change operation_type and the method-specific fields.

SPEI payment

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

The full flow — payment reference, expiry and reconciliation — is in APM payments.

SPEI withdrawal

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

The response carries two identifiers: id is the transaction (use it with GET /transactions/{id}/) and withdrawal_id is the withdrawal (use it to approve it and to read its detail). A new withdrawal stays Pending until you approve it with POST /withdrawals/perform_action/. Approval, statuses, webhooks and test data are in Withdrawals.

Argentina QR payment

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

Bank transfers to a CVU ("type": "transfer") and payouts to a CBU, CVU or alias are on Argentina.

Card payment with External 3DS

If you authenticated the cardholder with your own 3DS provider, pass the result in a top-level threeDomainSecure object (and the network in payment_method.card_brand). Tonder charges with it — no challenge. Account enablement required; Direct API only.

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

Fields, ECI rules, placement and errors are on External 3DS.

Chile withdrawal

Withdrawals in Chile use transfer_method: "CLP_TRANSFER", currency: "CLP", a whole-peso amount and a Chilean beneficiary (account, account_type, bank institution id and RUT). The full request is on Withdrawals in Chile.

Apple Pay payments

To charge an Apple Pay token, set payment_method.type to "APPLE_PAY" and send the token in payment_method.token.

There are two ways to integrate it. Choose the one that fits your business:

Managed: Tonder validates the merchant and shows the button with the Web SDK. This flow doesn't need the apm_config field.
Bring Your Own: you use your own Merchant ID. You send the token with apm_config.apple_pay_integration: "V2". Guide: Bring Your Own.

Field	Description
`payment_method.type`	`APPLE_PAY`
`payment_method.token`	The complete `PKPaymentToken` object Apple Pay returns. It must include `paymentData`
`payment_method.apm_config.apple_pay_integration`	Required on Bring Your Own. Send `"V2"`.

Response when the mode doesn't match (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"
  }
}

Payment not authorized (HTTP 402):

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

For the complete request example and your business setup, see Bring Your Own.

Process Transaction

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`