Migrating from the legacy SDK

For merchants on tonder-web-sdk v2 — InlineCheckout or LiteInlineCheckout — moving to @tonder.io/web-sdk.

Read this before you plan the work

This is not only a front-end change. Your webhook handler has to change too, and that is the part merchants underestimate when they plan the work.

Everything else is a feature-for-feature move. Saved cards, Card on File, enrollment, CVV re-collection, APMs, SafetyPay, 3DS and secure fields all exist in the new SDK.

Which class did you import?

Both paths then share Webhooks, which is the same work either way.

Setup — both paths

Load the SDK (client-side)

The legacy SDK shipped as an npm package and as a script tag. So does this one, and you are not tied to the one you used before — both options work in every framework, React and Next.js included.

If you were on npm, remove the old package so the two cannot both be loaded:

npm uninstall tonder-web-sdk

A TypeScript app can install the npm package as a devDependency for types only and keep the CDN runtime.

Install and CDN snippets: Install.

Create the instance (client-side)

Before — a class you construct, then configure, then pay with

const checkout = new LiteInlineCheckout({
  mode: 'stage',
  apiKey: 'YOUR_KEY',
  returnUrl: 'https://merchant.example.com/return',
  callBack: (result) => handleResult(result),
});
await checkout.injectCheckout();

checkout.configureCheckout({
  customer: { firstName: 'Ada', lastName: 'Lovelace', email: 'ada@example.com' },
  order_reference: 'ORD-001',
});

After — one factory, and the customer belongs to the session

const tonder = createTonder({
  api_key: tonderPublicConfig.api_key,
  environment: 'stage', // switch to 'production' when you go live
  session: {
    customer: { email: 'ada@example.com', first_name: 'Ada', last_name: 'Lovelace' },
  },
});
await tonder.init();

Full reference: createTonder(config).

Results: callback or promise (client-side)

The legacy callBack fired for everything. The new SDK gives you both channels, and they are not alternatives:

• pay() returns a promise with the transaction — use it to update the screen.
• events.payment fires for every method, including flows with no promise. One set of handlers covers the whole checkout.

Path A: from LiteInlineCheckout

You already build your own UI, so this is a rename pass plus one behavioural change.

1. Map the methods (client-side)

card_id and unmount_context keep the same meaning they had in mountCardFields, including the all / none / current values.

2. Mount card fields (client-side)

Before

await checkout.mountCardFields({ /* field config */ });

After — the container ids are the same defaults the legacy SDK used

<div id="collect-cardholder-name" class="card-field"></div>
<div id="collect-card-number" class="card-field"></div>
<div id="collect-expiration-month" class="card-field"></div>
<div id="collect-expiration-year" class="card-field"></div>
<div id="collect-cvv" class="card-field"></div>

const card_fields = tonder.create('card_fields');
await card_fields.mount();

Every configured field needs its container in the DOM before mount(), or the call rejects with MOUNT_COLLECT_ERROR.

Styles, labels and placeholders move to customization.card_fields on createTonder() — they are no longer passed to the mount call. See customization.card_fields.

3. Charge (client-side)

Before

checkout.configureCheckout({ customer, order_reference: 'ORD-001' });
const result = await checkout.payment({ /* cart */ });

After

const transaction = await tonder.pay({
  amount: 150,
  currency: 'MXN',
  return_url: 'https://merchant.example.com/return',
  client_reference: 'ORD-001',
  payment_method: { type: 'card' },
});

Saved cards use { type: 'saved_card', card_id }; APMs use their method code. Full field list: tonder.pay(input).

4. Drop verify3dsTransaction() (client-side)

The legacy flow required you to call it on the return page. The new SDK resolves 3DS itself and gives you a choice of presentation:

• presentation_mode: 'redirect' — the browser navigates, as it does today
• presentation_mode: 'embedded' — a modal, and the shopper never leaves your page

See Presentation mode.

5. Optional: add Apple Pay (client-side)

Not available in the legacy SDK at all, so this is new capability rather than a migration.

Then follow the Apple Pay guide.

Path B: from InlineCheckout

InlineCheckout drew the entire checkout: the card form, the saved-card list, the APM picker, and the styling around them. The new SDK does not draw a checkout. You build the UI; the SDK gives you secure inputs for card data and the data to render everything else.

That is the whole of this migration. Every capability you had is still there — what changes is who renders it.

1. Inventory what the old UI gave your shoppers (planning)

Before writing code, list which of these your checkout actually showed. You rebuild only those.

You do not have to design payment-method icons. getPaymentMethods() returns a logo URL per method, which is what the old UI rendered.

2. Replace the three lifecycle methods (client-side)

Before — the SDK owned the screen

const checkout = new InlineCheckout({ mode, apiKey, returnUrl, callBack });
await checkout.injectCheckout();   // draws everything into your container
checkout.setCallback(handleResult);
checkout.removeCheckout();

After — you own the screen; the SDK owns card security and the charge

You had one container and the SDK filled it with an entire checkout. Now you lay out your own form, and the SDK mounts a secure iframe into each card input. Everything around them — labels, the pay button, the saved-card list, the APM picker — is your markup.

<!-- your form, your layout; only these five are the SDK's -->
<div id="collect-cardholder-name" class="card-field"></div>
<div id="collect-card-number" class="card-field"></div>
<div id="collect-expiration-month" class="card-field"></div>
<div id="collect-expiration-year" class="card-field"></div>
<div id="collect-cvv" class="card-field"></div>

<button id="pay">Pay</button>

const tonder = createTonder({ /* …see Setup… */ });
await tonder.init();

const card_fields = tonder.create('card_fields');
await card_fields.mount();          // into the containers above

const transaction = await tonder.pay({ /* …see Path A step 3… */ });

card_fields.unmount();              // your teardown, in place of removeCheckout()

Those five ids are the defaults; every configured field needs its container in the DOM before mount(), or the call rejects with MOUNT_COLLECT_ERROR. Give them a max-height in your CSS so the iframes do not grow before they settle.

3. Build the flows you inventoried (client-side)

They are the same flows the old UI walked your shopper through:

4. Styling (client-side)

The old customization had two halves. Only one has a counterpart:

Webhooks (server-side)

Both paths need this, and it is the part that is not a rename.

Today you receive two different payload shapes — one for card payments, another for APMs. You will now receive one, the same for every payment method: the Short format, the same one API Direct sends. Both formats are detailed in the Webhooks model and the events catalog.

Card webhooks

APM webhooks

Before — wrapped, and a different shape from card webhooks

{
  "action": "payment",
  "type": "apm",
  "data": { "transaction_status": "Success", "payment_id": 41714, "checkout_id": "…" }
}

After — identical in shape to a card webhook

{
  "id": "fc38522e-…",
  "operation_type": "payment",
  "status": "Success",
  "payment_method_type": "SPEI",
  "client_reference": "ORD-001",
  "transaction_id": "e9340a04-…",
  "event_type": "payment_Success"
}

What to do

1. Read the current payload spec: How webhooks work and the Webhooks model.
2. Correlate on client_reference instead of checkout_id or payment_id.
3. Keep the handler idempotent by storing processed event ids — the retry policy and Dead Letter Queue are in Delivery & retries.
4. Run both old and new endpoints during the cutover if you are migrating gradually; the payloads are distinguishable by the presence of event_type.

Correlation (server-side)

Your order reference keeps working. It is renamed, and it still identifies the same thing on Tonder's side — reconciliation you already have does not need rethinking, only the field name changes.

metadata is supported by both, unchanged.

Test the migration

Run in stage before switching production traffic.

The last two are the ones worth writing an explicit test for. Everything above them fails loudly; a webhook mismatch fails silently, and you find out when an order is not fulfilled.

Next steps