Using payment methods from the SDKs

Four packages can charge a payment. They differ in where they run and how much they do for you.

Package	Runs in	Reach for it when
`@tagadapay/headless-sdk`	Browser	You are building a custom storefront and want one call that handles 3DS, redirects and polling
`@tagadapay/core-js`	Browser	You need the low-level primitives — tokenization, wallet sheets, 3DS
`@tagadapay/plugin-sdk`	Browser	You are building a storefront plugin on TagadaPay hosting
`@tagadapay/node-sdk`	Server	You are charging server-to-server, or orchestrating a backend flow

If you are unsure, start with headless-sdk’s processPayment(). It is the one function that covers cards, wallets and APMs, and it handles the parts people get wrong.

The one call that handles everything

processPayment() charges, detects requireAction, runs the 3DS challenge, follows APM redirects and polls until the payment reaches a terminal status.

import { createHeadlessClient } from '@tagadapay/headless-sdk';

const tagada = createHeadlessClient({ storeId: 'store_xxx' });

const result = await tagada.payment.processPayment({
  checkoutSessionId: 'cs_xxx',
  paymentInstrumentId: 'pi_xxx',
});

if (result.status === 'succeeded') fulfil();

Everything below is the same flow taken apart, for when you need control over a step.

Discovering what you can offer

Always render your payment UI from the store’s configuration, not from a hard-coded list.

const setup = await tagada.payment.getPaymentSetup('cs_xxx');
const methods = await tagada.payment.getEnabledMethods('cs_xxx');
const express = await tagada.payment.getExpressMethods('cs_xxx');

import { getStorePaymentSetup } from '@tagadapay/core-js';

const setup = await getStorePaymentSetup({
  storeId: 'store_xxx',
  apiKey: 'tp_pk_live_***',
});

const setup = await tagada.paymentSetup.get('store_xxx');

Group the result by type — card, wallet, apm — to build your UI sections. See the config shape.

Cards

Tokenize in the browser

Raw card data never reaches your server or ours unvaulted.

const { tagadaToken } = await tagada.payment.tokenizeCard({
  cardNumber: '4242424242424242',
  expiryDate: '12/2030',
  cvc: '123',
});

Pay with the token

processPayment creates the instrument from the token for you:

await tagada.payment.processPayment({
  checkoutSessionId: 'cs_xxx',
  tagadaToken,
});

To store the instrument first (e.g. to reuse it), call const { paymentInstrument } = await tagada.payment.createInstrument({ tagadaToken }) and pass paymentInstrumentId: paymentInstrument.id instead.

Server-side, the equivalent is tagada.payments.process({ amount, currency, storeId, paymentInstrumentId }) — the Node SDK charges vaulted instruments directly and takes no checkout session.

Wallets

// You open the sheet (core-js or your own ApplePaySession); headless-sdk
// tokenizes the authorized wallet payload and charges the session.
// Inside session.onpaymentauthorized:
await tagada.payment.processApplePay({
  checkoutSessionId: 'cs_xxx',
  applePayToken: event.payment.token,
});

// Google Pay — inside the paymentsClient callback:
await tagada.payment.processGooglePay({
  checkoutSessionId: 'cs_xxx',
  googlePayToken: paymentData.paymentMethodData.tokenizationData.token,
});

import { isApplePayAvailable, startApplePaySession } from '@tagadapay/core-js';

if (await isApplePayAvailable()) {
  button.addEventListener('click', () => {
    startApplePaySession(config, request, {
      onSuccess: async (token) => { /* charge server-side */ },
      onError: (msg) => console.error(msg),
    });
  });
}

The wallet sheet must be opened from a real user gesture. Do not await anything between the click and startApplePaySession — resolve your configuration beforehand. Full detail in Apple Pay & Google Pay.

Alternative payment methods

APMs need an explicit paymentMethod and a processorId, and they always come back with a redirect rather than a final status.

const result = await tagada.payment.processApm({
  checkoutSessionId: 'cs_xxx',
  paymentMethod: 'ideal',
  processorId: 'proc_xxx',
});

// finalize() resolves the action: it redirects the browser for APMs,
// runs 3DS challenges, and polls to a terminal status otherwise.
const outcome = await tagada.payment.finalize(result);
if (outcome.status === 'succeeded') fulfil();

const { payment } = await tagada.payments.process({
  amount: 4999,
  currency: 'EUR',
  storeId: 'store_xxx',
  customerId: 'cus_xxx',
  paymentMethod: 'klarna',
  processorId: 'proc_xxx',
  returnUrl: 'https://store.example/checkout/return',
});

Coming back from the redirect

When the shopper returns to your returnUrl, resume the payment rather than assuming it worked:

const resumed = await tagada.payment.maybeResumeFromUrl();
if (resumed?.status === 'succeeded') fulfil();

The redirect return is not proof of payment. Fulfil on the webhook, which is the authoritative result.

Server-side payment operations

import { Tagada } from '@tagadapay/node-sdk';

const tagada = new Tagada({ apiKey: process.env.TAGADA_API_KEY });

await tagada.payments.process({ amount, currency, storeId, paymentInstrumentId });
await tagada.payments.retrieve('pay_xxx');
await tagada.payments.refund({ paymentIds: ['pay_xxx'], amount: 1999 });
await tagada.payments.void({ paymentId: 'pay_xxx' });
await tagada.payments.continue('pay_xxx');
await tagada.payments.currencies();
await tagada.payments.processors();

payments.refund() and payments.void() are subject to what the underlying processor supports — CCAvenue, notably, cannot refund through us at all. Check the capability matrix before you rely on one.

Choosing a package

I'm building a custom storefront

headless-sdk. Use processPayment() for cards and wallets, processApm() for redirects, and getEnabledMethods() to decide what to render.

I only need to tokenize

core-js. It is the smallest surface — Tokenizer, the wallet session helpers and 3DS, with no checkout opinions attached.

I'm charging from a backend

node-sdk. Never put a secret key in a browser — use a restricted publishable key (tp_pk_*) client-side and keep tp_sk_* on the server.

I'm building a plugin on TagadaPay hosting

plugin-sdk. It has the richest React surface — usePayment, wallet hooks and the full payment-action handler.

Support matrix

What each processor can charge.

Headless SDK

The full checkout flow.

Node SDK

Server-side quick start.

Overview

Payments

Web Integration

Tracking & Attribution

Node SDK

Funnels

Funnel demos

Examples

Shopify

WooCommerce

SaaS Billing

Headless SDK

Plugin SDK

Plugin CLI

Studio MCP (AI Agents)

Config MCP (AI Agents)

Hosting & A/B Testing

Internal

Using payment methods from the SDKs

Using payment methods from the SDKs

The one call that handles everything

Discovering what you can offer

Cards

Wallets

Alternative payment methods

Coming back from the redirect

Server-side payment operations

Choosing a package

Next

Support matrix

Headless SDK

Node SDK

​Using payment methods from the SDKs

​The one call that handles everything

​Discovering what you can offer

​Cards

​Wallets

​Alternative payment methods

​Coming back from the redirect

​Server-side payment operations

​Choosing a package

​Next

Support matrix

Headless SDK

Node SDK

Using payment methods from the SDKs

The one call that handles everything

Discovering what you can offer

Cards

Wallets

Alternative payment methods

Coming back from the redirect

Server-side payment operations

Choosing a package

Next