Changelog

What's new in the Tonder platform. The most recent entries appear first.

November 5, 2026

Withdrawals: one way to create them

Withdrawals are now created one way: POST /api/v1/process/ with operation_type: "withdrawal". POST /api/v1/withdrawals/ is no longer documented, so if your integration uses it, move to /process/:

amount, currency, transfer_method, description, metadata and fee_model keep their names.

The response changes too:

• It answers 201 instead of 200.
• id is now the transaction, and withdrawal_id is the withdrawal. Store both, and send withdrawal_id to POST /api/v1/withdrawals/perform_action/.
• status uses the readable names, such as Pending instead of PENDING.

See Withdrawals.

October 30, 2026

Cash vouchers in Colombia (COP)

Cash vouchers now take payments in Colombian pesos:

• The same request as Mexico and Chile, with currency: "COP" and country: "Colombia".
• Cash at Efecty, SuRed, MovilRed Colombia and Acciones y Valores (safetypayCash, channel: "WP"), or online transfer from 44 banks and wallets, among them Bancolombia, Davivienda and Nequi (safetypayTransfer, channel: "OL").
• Limits per bank or network, up to COP 41,500,000 per transaction.
• Enabled per account: ask your integration manager to turn on Colombia before you charge.

The bank IDs and request examples are on Cash vouchers › Colombia; the limits are on Limits & Business Rules.

October 29, 2026

Withdrawals in Chile (CLP)

Withdrawals › Chile (CLP)

Send Chilean pesos from your balance to a Chilean bank account through the Direct API:

• transfer_method: "CLP_TRANSFER" with currency: "CLP", to a checking (cuenta corriente) or sight account (cuenta vista).
• Whole pesos: amount takes no decimals, as a number or a string ("50000").
• A Chilean beneficiary: the account number, its type, the bank's institution id and the holder's RUT, validated before approval.
• Success or Failed, with decline_code and decline_reason when a transfer is rejected or returned.

Everything is on Withdrawals in Chile; the bank ids are in Banking reference.

October 28, 2026

Monthly statements in Finances

Finances › Statements

Finances in the dashboard has a new Statements tab. Pick a month in Period to see one statement for it: the opening balance; payments, disputes, refunds and voids; every fee line with its total; the reserve held and released; and the settlements credited to withdrawals. Download PDF exports it.

Details in Finances › Statements.

October 26, 2026

Argentina: QR payments, bank transfers and payouts to CBU/CVU/alias

Accept ARS in Argentina through the Direct API, over the country's instant, 24/7 rails:

• QR payment (payment_method.type: "qr"): one interoperable QR that any wallet or bank app scans.
• Bank transfer ("transfer"): a fixed CVU and alias for each customer.
• Payouts to a CBU, CVU or alias with transfer_method: "BANK_TRANSFER", from a pre-funded balance.
• QR payments can be refunded in full, once.

Everything is on Argentina. The methods are enabled per business.

Webhooks 2.0: choose events per endpoint, automatic retries, signatures and an events log

Webhooks 2.0 is enabled per account — if Developers in your dashboard shows an Events tab, you have it. The Webhooks section now documents it as the default, with the previous behavior kept where it differs.

• Endpoints — up to 10, each subscribed only to the events you pick, with a Send test button and a signing secret shown once.
• Events catalog — every event, grouped as in the dashboard: API Direct payments and refunds (Short), Hosted & SDK checkout sessions (Long), withdrawals — including withdrawal_Canceled, spelled with one L — and endpoint.test.
• Verify signatures — every webhook is signed with Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature); rotating the secret keeps the old one valid for 24 hours.
• Delivery and retries — delivered means any 2xx within 10 seconds; otherwise up to 6 attempts over about 8.5 hours, plus Resend event and Retry all.
• Events log — every delivery and attempt for 60 days, also from a transaction's or withdrawal's details.
• Webhooks API — the same operations by API; your Tonder contact gives you the base URL.
• Deduplicate on webhook-id. It is the same on every retry and resend. Accounts without Webhooks 2.0 keep deduplicating on id + event_type.

October 20, 2026

Withdrawals: the complete integration guide

The Withdrawals guide was rewritten around how an integrator reads it, from the integrations team's merchant guide, verified in sandbox:

• Two creation paths, two identifiers. POST /process/ answers 201 with id (the transaction) and withdrawal_id (the withdrawal); POST /withdrawals/ answers 200 with the full record, where id is the withdrawal id. Approval, detail and the other actions take the withdrawal id — the wrong one answers 404 Withdrawal not found: 'Item'.
• A new withdrawal doesn't advance on its own until you approve it with POST /withdrawals/perform_action/, unless your account has automatic approval.
• Two status vocabularies. /process/, GET /transactions/{id}/ and the flat webhooks use Pending … Returned; the /withdrawals/* endpoints and the extended webhook use the internal names, PENDING … REFUNDED. The guide maps them and asks you to handle both.
• Every read endpoint, in the guide and in the API Reference: detail (no trailing slash; the only place with the failure reason), list, balance (its shape depends on your account) and account activity (a range of at least two days).
• Webhooks come in a flat or an extended format, chosen by your account's configuration; five events, with a third one (withdrawal_Returned) when the funds come back. Dedupe on id + event_type.
• One set of sandbox test data, always with institution 40012, including a CLABE that returns the funds on its own, in Test cases — Withdrawals.
• Before going to production: the balance is neither checked at creation nor reserved while pending, the beneficiary's name has a practical 40-character limit, the receipt (CEP) appears 4 to 30 minutes after settlement, and the amount limit is the executing institution's.

October 18, 2026

Apple Pay: Managed, or Bring Your Own Merchant ID

Apple Pay now comes in two models, named so the choice fits in one line:

• Managed Apple Pay — Tonder's Apple Merchant ID and certificate. You send your domains, host Tonder's verification file, and the Web SDK button or Hosted Checkout 2.0 renders Apple Pay; no Apple Developer account. Every current integration runs on this model, and its page gained a pre-flight checklist, the file-serving rules, Apple's IP ranges for geo-blocked sites and a troubleshooting table by symptom.
• Bring Your Own Apple Pay — new. Your own Apple Developer account and Merchant ID: Tonder sends you a certificate request, you create the Payment Processing Certificate in Apple and return it, and Tonder keeps the key. Your website or iOS app sends each Apple Pay token through the Direct API, and Tonder decrypts it under your Merchant ID. Enabled on request through your representative; the Direct API request for the token is shared during onboarding.

The Apple Pay overview compares both models and keeps the shared sandbox test cards.

October 13, 2026

Web SDK: Card-on-File from the browser, and saved cards that need a phone

Saving cards with Card-on-File from the browser requires @tonder.io/web-sdk 0.1.11 or later. The Web SDK guide and reference now document the whole saved-cards flow, verified in stage:

• Only for signed-in users. The secure_token is not tied to a customer — session.customer is. Build it on your server from the authenticated account, and skip saved cards for guests.
• Businesses that require a phone. Saved cards always belong to session.customer.email; some businesses, configured by Tonder, also require session.customer.phone (E.164). Without it, canSaveCards() returns false and getCustomerCards(), enrollCard() and saved-card payments throw SAVE_CARDS_UNAVAILABLE; a new card is still charged, but not saved. The phone never replaces the email. See Businesses that require a phone for saved cards.
• A new-card payment also saves the card when Card-on-File is enabled, and it comes back from getCustomerCards() with a subscription_id — cards that have one are charged without a CVV. Show the consent text in your checkout.
• enrollCard() saves without charging and clears the fields; subscription_id is present only with Card-on-File.
• A recommended nine-step flow and the error codes it can produce — SAVE_CARDS_UNAVAILABLE, SECURE_TOKEN_INVALID, CUSTOMER_OPERATION_ERROR, CUSTOMER_AUTH_TOKEN_NOT_VALID, FETCH_CARDS_ERROR, SAVE_CARD_PROCESS_ERROR — are in the reference.

The Hosted Checkout pages now state the same rule: the email always identifies the customer, and the phone is an additional requirement on the accounts that need it — never a replacement.

A CLABE for every user

POST /api/v1/clabe-assignments gives each of your end users their own SPEI CLABE: one call per user, idempotent on user_id (201 the first time, 200 with is_new: false after that), and every SPEI transfer to it is credited to your account. It lives on the deposits service — https://api.tonder.io/deposits in production, api-stage in sandbox — with your usual Authorization: Token key, server-side only. Guide: Assign a CLABE per user; schema and playground: Deposits.

The Frictionless SPEI deposit-status endpoints now use the same domains — https://api-stage.tonder.io/deposits/… and https://api.tonder.io/deposits/… — instead of the raw execute-api.amazonaws.com URLs. The old URLs keep working; the new ones stay the same if the infrastructure changes. See Check a deposit's status.

October 9, 2026

Hosted Checkout: saved cards by phone, dark backgrounds, embedding domains

Clarifications from the Hosted Checkout 2.0 QA campaign:

• Some accounts also require a phone for saved cards. Saved cards always belong to the customer's email; Tonder can set your account to also require customer.phone. In that case send it on every session that includes saved_cards and on card-enrollment sessions, always the same E.164 value — it is compared exactly as sent. See Which customer a saved card belongs to.
• Use light backgrounds. theme.background_color and theme.card_background_color do not change the text colors, so a dark background leaves the order summary unreadable. See Customize the checkout.
• Embedding domains are origins. Register https://shop.example.com, never a path — an entry with a path leaves the iframe blank without any error. See Embed the checkout.

October 7, 2026

Fintoc, a second payout rail for withdrawals

Withdrawals can now settle on Fintoc as well as STP. The rail is set on your account by Tonder, for each transfer method — SPEI and debit card both work on either rail — and your /process/ request does not change: there is no field to choose it. The only difference you see is the provider value in withdrawal webhooks, now STP or FINTOC, so match on event_type and status rather than on provider. See Withdrawals.

Sandbox test accounts differ by rail: on the Fintoc rail use a real 5-digit Banxico institution code such as 40012 — 97846 is rejected. See Test cases — Withdrawals.

October 2, 2026

Hosted Checkout 2.0

Hosted Checkout has a new generation. The endpoints are the same — POST /checkout/v1/sessions and its companions — and new payment sessions get the 2.0 page by default. Try the interactive demo, then read the overview.

• New design — an order summary, three templates (ecommerce, deposit, subscription), fonts, corner shapes and automatic button contrast. See Customize the checkout.
• Button and language — submit_type (pay, deposit, subscribe) and locale (es, en, zh), per session or as a business default. Business defaults can now be read back with GET /checkout/v1/business/config.
• Apple Pay — add apple_pay to payment_method_types.
• Embedded mode — load the checkout in an iframe and follow it with events. See Embed the checkout.
• Card enrollment — save a card without charging, now documented in Save a card without charging.
• Direct API processing — payments run through the Direct API and send the standard Tonder webhooks. payment_id is returned when the session is created and never changes; Direct API sessions also return payment_flow and the latest direct_transaction_id.
• Payment links — a link created in the Dashboard is now a Hosted Checkout session, with filters, KPIs, the customer's payment and a live preview of the appearance. See Payment Links.

Three things to check if you already integrate Hosted Checkout:

• Session webhooks are not sent. session.created, session.completed and session.expired are no longer emitted; the docs that described them have been corrected. Follow a session with the payment webhooks or Get a session.
• GET /checkout/v1/payments/{payment_id} takes only the numeric payment_id. Other ids return 404 E003.
• Webhook format changes when your account moves to the Direct API. Update your handler first — see Legacy Hosted Checkout, which also explains how to stay on the first-generation design (checkout_ui_version: v1).

Corrections from integration QA

Fixes to pages that did not match how the platform behaves, found while integrating with merchants:

• Webhooks are delivered once. A failed delivery (4xx, 5xx or a timeout) is recorded but the event is not resent, so reconcile with GET /api/v1/transactions/{id}/ for any period your endpoint was down. The retry policy and Dead Letter Queue sections were removed. See Delivery.
• Webhook authentication headers, per auth_method, are now spelled out in Setup & management. One URL receives every method and operation.
• Withdrawals need approval unless automatic approval is enabled for your account, from the Dashboard or with POST /api/v1/withdrawals/perform_action/. The response returns a withdrawal_id, different from id, and that is the one the approval takes. See Withdrawals.
• Withdrawal test accounts depend on your payout rail, and the provider value in withdrawal webhooks varies by account. Test cases — Withdrawals now shows how to force Success, Failed, Declined and Returned.
• Finding a decline reason in the Dashboard — it is in the Raw data section of the transaction detail. See Transactions.
• OXXO Pay — payment_method.type is oxxopay, lowercase.

September 25, 2026

Institution codes refreshed against Banxico

The institution code catalogue now matches Banxico's SPEI participant list exactly — 97 institutions. Sixteen participants were added (Hey Banco 40167, Revolut 40170, Klar, albo, Clip, MexPago, Peibo and other newer entrants), six codes no longer listed by Banxico were removed (40143, 90608, 90630, 90642, 90686, 90689), the six legacy …2 indirect codes (91802–91927) were dropped, and five names were updated (40128 → KAPITAL, 40138 → UALA, 90631 → TRF, 90661 → KLAR, 90706 → ARCUS FI). If you hardcoded any of the removed codes for withdrawals, check them.

97 SPEI participantsChecked September 25, 2026

September 23, 2026

Account Validation — know who owns the CLABE before the money moves

A new standalone API confirms that a CLABE is real and that it belongs to your user — holder name and RFC, straight from the bank — before a single peso is at risk. Tonder sends a 0.01 MXN test deposit (on us) and reads the owner from the official interbank receipt. Two calls: POST /api/v1/account-verifications/ to start, GET /api/v1/account-verifications/{account_number} to read holder_name, holder_id, institution and the name_match / rfc_match flags. One validation per CLABE, cached for 24 hours; use it for deposits, payouts, or both. Same Authorization: Token header as the rest of the API. Guide on Account Validation; endpoints in the API Reference.

External 3DS on the Direct API

If you authenticate the cardholder with your own 3-D Secure provider, you can now pass the result to Tonder in the same POST /process/ request — a top-level threeDomainSecure object with the ECI, the cryptogram (cavv for Visa, ucaf + directoryServerTransactionID for Mastercard) and, when the ECI says not authenticated, acceptRisk: true. Tonder charges with it: approved in one call, no challenge. Send payment_method.card_brand too, so mismatches are a clear 400 instead of an acquirer decline.

Direct API only, and the account must be enabled first. The one thing to get right: the object goes at the top level — nested inside payment_method it is silently ignored and you get a regular 3DS challenge. Fields, ECI rules and errors on External 3DS.

"threeDomainSecure": {
  "eci": "02",
  "ucaf": "kCO52e75N318oAB3MPZU6EhB2Td6",
  "directoryServerTransactionID": "9e8c…"
}

September 21, 2026

Refund endpoint in the API Reference

A processor-agnostic refund is now documented: POST /business/{business_id}/payments/{transaction_reference}/refunds. Send only the amount; Tonder resolves the processor from the transaction reference. Cards only, and only for Direct API and Web SDK integrations — every other integration keeps refunding from the dashboard. Read the not-found note before you integrate: a missing transaction answers HTTP 200 with a plain string, not a 404.

Withdrawals — the Returned status

Withdrawals can end in a seventh status, Returned: the transfer was sent and processed, but the receiving bank returned the funds afterwards. It is terminal, and it comes after Success — so a handler that only reconciles on Success never sees the reversal. Treat Success, Failed, Declined, Cancelled and Returned as final. It also has its own webhook, withdrawal_Returned, the third one on that withdrawal. Full table on Withdrawals → Step 3 and the payload under Webhooks.

Correction to the July 9 entry: it listed REFUNDED as retired. It was not — it maps to Returned.

September 17, 2026

Apple Pay — sandbox test cards

The Apple Pay guide now includes Apple's sandbox test cards for the networks Tonder processes — Visa, Mastercard and American Express — with the expiry and CVV/CVC/CID for each, plus the three-step Sandbox Tester setup (App Store Connect tester account → sign in on a real device → add the card manually in Wallet). These are Apple's latest FPANs (August 2025); Tonder's regular test cards cannot be added to Wallet, and Apple's cards work only in sandbox.

September 15, 2026

Chile — per-method limits, and a correction

Minimum and maximum amounts for every Chilean method are now published on Limits & Business Rules:

Correction to the September 11 entry: it said the online-transfer bank IDs (Banco BCI 8296, Machpay 8416, Khipu 8488/8490/8494/8491) were retired. They were not — they remain available and are back on Cash vouchers and Coverage. Only the Walmart Chile network (8198) was retired. If you removed those IDs on the strength of that entry, they still work.

September 11, 2026

Cash vouchers in Chile — Caja Vecina and BancoEstado Express

Cash vouchers accepts cash in Chile again, through two new collection networks:

Send channel: "WP" with one or both bank IDs. The Walmart Chile network (8198) is retired — if you had it hardcoded, update to the two above. Online transfer (Banco BCI, Machpay, Khipu) is unchanged. See Cash vouchers and Coverage.

August 17, 2026

Settlements — cycles, rolling reserve, and the report

When your money arrives was undocumented: T+1 and T+2 appeared nowhere in the docs, and the rolling reserve was a single line. Two new pages under Payments Management:

• Settlements — the T+1, T+2 and batch cycles and where each is available, the twice-weekly batch schedule, and how the rolling reserve is withheld and released after 90 days.
• Settlement report — every section and column of the report, plus a worked reconciliation from processed volume down to the amount deposited.

August 17, 2026

Payments Management — Handling Disputes

A new top-level section for the operational side of running payments. It opens with a chargeback reference per market:

• Handling Disputes — Mexico
• Handling Disputes — Chile

Each covers the response windows published by Visa, Mastercard and American Express, what changes between domestic and cross-border cases, and what's expected of you at each stage. Brand deadlines, pre-arbitration and arbitration were previously undocumented.

The dispute response window is now stated as 15 days to submit evidence, corrected on Transactions so the site holds one figure.

August 17, 2026

Saved cards and Card-on-File in Hosted Checkout

Both already worked; neither was documented outside the SDK path. Create a Payment Session now covers them:

• Saved cards — add saved_cards to payment_method_types and the checkout lists the customer's stored cards beside the new-card form. payment_method_config.saved_cards.show_save_card_checkbox adds the opt-in checkbox.
• Card-on-File — with an active Tonder connection, cards are saved automatically (3DS on save, a subscription per card) and repeat payments skip the CVV. Nothing to configure, and it takes precedence over the checkbox.

saved_cards and payment_method_config are in the OpenAPI spec too, so the request schema on that page lists them.

August 7, 2026

Web SDK migration guides + Apple Pay

Two new guides to reach @tonder.io/web-sdk from wherever you are today:

• Migrating from the legacy SDK — from tonder-web-sdk v2 (InlineCheckout / LiteInlineCheckout), with the method-by-method mapping and the webhook change to the Short format — the part to budget for.
• Migrating from Direct API — move your checkout to the browser without changing your backend: same /process/, same webhooks, same reconciliation.

And Apple Pay gets its own payment-method page: the Web SDK button, domain registration, availability, and events.

Checkout

Business licence$250.00 MXN

August 6, 2026

Check your withdrawal balance by API

You can now check the available balance of your Mexican withdrawals account with the Get Balance API (GET /withdrawals/balance): see how much you can disperse before creating withdrawals via POST /process/. The Withdrawals guide includes the balance section with per-environment examples.

Nu México's SPEI code changes to 40638

By order of Banco de México, Nu México now operates as NUBANK, S.A., Institución de Banca Múltiple, and its SPEI code changed with it. This affects you if you send withdrawals to Nu accounts or receive transfers from them.

What to update:

• Payouts — send 40638 in institucionContraparte.
• Deposits — your system and your H2H connection must recognise 40638 in institucionOrdenante.

Code 90638 stopped working on 5 August 2026 at 18:00 Mexico City time. Anything sent with it is rejected.

• Banking reference — the institution code table.

July 28, 2026

New Analytics module in the Dashboard

We launched Analytics, a new Dashboard section that goes deeper into payment performance than the Home KPIs. It's organised into two views:

• Acceptance & Conversion — Overall, FTD and Trusted acceptance rate, APM conversion rate, acceptance rate over time, acceptance by method, card network performance, best and worst issuing banks, and the FTD vs. Trusted comparison.
• Deposit Analytics — total deposits, FTDs, active depositors and average deposit, plus deposit volume and count, the first-time deposit funnel and the deposit amount distribution.

Both views filter by period (Today, 7D, 30D, 90D or a custom range).

• Analytics — every KPI, chart and section explained.

July 9, 2026

New withdrawal statuses

Withdrawals now use the same status vocabulary as payments. If your integration expected the previous names, update it with this mapping:

See the full flow in Withdrawals.

July 8, 2026

New Web SDK (@tonder.io/web-sdk)

We launched the new Tonder Web SDK on npm: @tonder.io/web-sdk — a browser TypeScript SDK that replaces the Full/Lite variants for web with a single package:

• Secure card fields mounted in your own UI (createTonder → init → create('card_fields') → mount → pay).

• Saved cards and Card-on-File: enrollCard(), getCustomerCards(), removeCustomerCard() with a secure_token.

• Alternative methods: SPEI, OXXO Pay, and SafetyPay banks (getPaymentMethodBanks()).

• Hosted/3DS presentation via redirect or embedded (SDK modal).

• TypeScript types included, structured errors (AppError), and webhook-aligned responses. Also available via CDN (window.Tonder).

• Web SDK (guide) — quick start and payment flows.

• Web SDK Reference — every method, type, and error.

Tonder Web SDK plugin for AI agents

We launched tonder-ai-integrations: plugins that help AI agents integrate Tonder SDKs correctly. The first plugin is Tonder Web SDK (v0.1.7), for Claude Code, Claude Desktop, Codex CLI, and Codex Desktop. It packages a framework-aware integration skill (HTML, React, Next.js, Angular) and a local MCP server (tonder-docs) with versioned Web SDK documentation — recipes, API reference, errors, and payment statuses.

Supported flows: card payment, enrollment, saved cards, payment methods, and SafetyPay banks. It installs today from the GitHub repository marketplace.

• MCP Integration — what it is and how it works.
• Installation — step by step per host.
• Usage — example prompts and the MCP tools.

June 10, 2026

Documentation redesign

This documentation shipped a full redesign:

• Two-row header with centered search and tabs (Docs · API Reference · SDK Reference · Resources · Changelog).
• Sidebar with icon chips, breadcrumbs above every title, and a refreshed table of contents.
• Inset-style code blocks, minimal tables, and Tonder-branded share (OG) cards.
• Native diagrams (flows and sequences) in the Hosted Checkout guides.

June 8, 2026

New Tonder dashboard

We launched a redesigned dashboard — faster, clearer, and with native analytics: Home, Analytics, Fraud & Risk, Transactions, Withdrawals, Finances, Payment Links, Developers, Webhooks, and Team Members.

Also in this release

• Cash vouchers — the cash payment method formerly called SafetyPay is now Cash vouchers. The integration is unchanged (same API type). See Cash vouchers.