Server-to-server payments

Once you have a Processing Key (tp_sk_…) + a storeId, the entire payment lifecycle is yours. No checkout session, no funnel, no UI assumptions on our side.

The four steps

Tokenize  (browser)  → tagadaToken
Instrument (server)  → paymentInstrumentId  ─┐
                                                ├─ optional 3DS
3DS        (server)  → threedsSessionId    ─┘
Charge     (server)  → paymentId

Steps 2 and 3 happen on your server. Step 1 happens in your customer’s browser. Step 4 closes the loop.

Step 1 — Tokenize the card (browser)

Use @tagadapay/core-js. The card data goes directly to BasisTheory’s vault — never to your server, never to ours:

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

const tokenizer = new Tokenizer({ environment: 'production' });

const tagadaToken = await tokenizer.tokenizeCard({
  cardNumber: '4242 4242 4242 4242',
  expiryDate: '12/30',
  cvc: '123',
  cardholderName: 'Jane Doe',
});

// → 'eyJraWQiOiJ...' — a single-use, opaque token
// Send it to your server. It expires in ~30 minutes.

PCI scope-out. Because the PAN never traverses your stack, your PCI obligations stay at SAQ-A. See @tagadapay/core-js for the full tokenization API.

Alternative: you already hold the card (server-side tokenization)

If you are already PCI-compliant and hold card numbers in your own environment (your own vault, your own collection form), you can skip the browser step entirely and hand the card to the SDK from your server. It tokenizes straight into Tagada’s PCI vault and returns a ready payment instrument — steps 1 and 2 in one call.

This path must be switched on by TagadaPay before you can use it. It is off by default on every account, including yours today. Until we enable it, createFromCard() fails with:

TagadaPermissionError: Please contact support to ask for raw card data enablement

Ask your account manager or write to support to have it enabled, and expect to show that you are already PCI-DSS compliant — we only grant it to merchants who legitimately hold card data. Nothing in the snippet below works until that is done, so request it before you start integrating.

const { paymentInstrument, scaRequired } = await charging.paymentInstruments.createFromCard({
  storeId: 'store_xxx',
  card: { number: '4242424242424242', expMonth: 12, expYear: 2030, cvc: '123', holderName: 'Jane Doe' },
  customerData: { email: 'jane@example.com' },
});

// scaRequired === true → the issuer mandates 3DS. See Step 3.

Where the card goes. createFromCard() posts the card from your process straight to Tagada’s PCI vault over TLS, then sends only the resulting vault token to the Tagada API. The card number and CVC never reach the Tagada API and are never logged. Your PCI scope is unchanged — it is already whatever it was before, since you were holding the PAN; ours stays out of it.

The SDK checks the card locally first (Luhn, expiry, CVC length), so a malformed card never leaves your process. If you use this path, skip Step 2 — you already have your paymentInstrument.

Step 2 — Create a payment instrument (server)

Convert the single-use tagadaToken into a reusable paymentInstrument:

const charging = new Tagada(process.env.MERCHANT_42_PROCESSING_KEY!);

const { paymentInstrument, customer } = await charging.paymentInstruments.createFromToken({
  tagadaToken,
  storeId: 'store_xxx',
  customerData: {
    email: 'jane@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
    phone: '+33612345678',
    billingAddress: {
      address1: '10 rue de Rivoli',
      city: 'Paris',
      postal: '75001',
      country: 'FR',   // ISO 3166-1 alpha-2 — required; acquirers reject an empty country
    },
  },
  // The shopper behind this call, as seen by YOUR server (Express behind a
  // trusted proxy shown). Never your own server's address.
  customer: { ipAddress: req.ip, userAgent: req.get('user-agent') },
});

// {
//   paymentInstrument: { id: 'pi_xxx', last4: '4242', brand: 'visa', ... },
//   customer:          { id: 'cust_xxx', ... }
// }

The same customer is reused if you provide a matching email — one customer can hold multiple instruments.

Address field names. The platform stores and validates addresses as address1, address2, postal, city, state, country (ISO 3166-1 alpha-2), plus firstName / lastName. The SDK still accepts the legacy line1 / line2 / postalCode aliases and maps them for you, but prefer the canonical names.

Addresses are optional — including for digital products. Neither billingAddress nor shippingAddress is required to charge: selling digital goods with no shipping address works out of the box. If you do provide an address, it is only forwarded to the acquirer when it carries a valid ISO 3166-1 alpha-2 country — an incomplete address (e.g. missing country) is safely omitted from the acquirer call instead of failing the payment. Providing a complete billingAddress is still recommended: it improves issuer approval rates (AVS) and 3DS frictionless outcomes.

Pass the shopper’s IP — you are the only one who can. On this server-to-server path your server calls Tagada, so what Tagada sees is your datacenter, not the shopper. Processors weigh the shopper IP heavily (Stripe Radar, Adyen risk, issuer scoring): forward it, together with the browser’s User-Agent, in customer: { ipAddress, userAgent } on createFromToken() / createFromCard() and on payments.process(). Tagada never substitutes your server’s address; a value that is not a valid IP is refused (400). With Express, req.ip is the shopper only behind app.set('trust proxy', true); otherwise take the first entry of X-Forwarded-For. The context is kept on the customer, so later charges on the same customer inherit it, but send it on every charge you can: the shopper may have moved.

Step 3 — 3DS (usually nothing to do)

Most integrations skip this step. Whether 3-D Secure runs, and how, is decided by the PSP/acquirer behind your TPA — and most of them handle it themselves. There are two ways it can happen:

Option 1 — PSP/acquirer-hosted 3DS (the default)

Modern PSPs (Adyen, Stripe, …) own the 3DS challenge. You don’t call threeds.createSession. You just charge (Step 4) with a returnUrl; if the issuer requires SCA, payments.process comes back with requireAction: 'redirect' and a redirectUrl pointing at the processor’s own hosted 3DS page. You send the customer there, they authenticate, and they return to your returnUrl. Nothing to collect, nothing to pass through — the processor reconciles the authentication internally. Always send the returnUrl. Without it, on Stripe the customer ends on a neutral page hosted by TagadaPay after authenticating instead of coming back to you. Either way you still have to send them to the redirectUrl: a payment whose redirect nobody follows stays pending. This is the path the rest of this guide uses. If your TPA is on a hosted-3DS PSP, ignore the code below and go straight to Step 4.

Option 2 — Tagada standalone 3DS (the exception)

Some gateway-style processors (e.g. NMI) don’t host 3DS, but they do accept pre-authenticated 3DS values (CAVV, ECI, DS transaction id…) on the charge. For those — and only when the acquirer is compatible and takes those values as input — Tagada can run the 3DS flow for you, collect the values, and pass them raw to the acquirer. You opt in explicitly:

// Only for processors that need externally-supplied 3DS values (e.g. NMI).
// Hosted-3DS PSPs like Adyen / Stripe do NOT use this — see Option 1.
const threeds = await charging.threeds.createSession({
  provider: 'basis_theory',
  storeId: 'store_xxx',
  paymentInstrumentId: paymentInstrument.id,
  sessionData: {
    /* device info collected client-side via core-js */
  },
});

// status === 'challenge_required' → render threeds.challengeUrl in an iframe;
//                                   the customer authenticates in-browser.
// status === 'frictionless'      → no challenge; proceed straight to charge.
//
// Pass threeds.id to payments.process() as `threedsSessionId` (Step 4) so the
// authenticated values flow through to the acquirer.

Option 3 — Bring your own 3DS (you already run an MPI)

You collect cards and run 3-D Secure in your own PCI environment — your own 3DS server, Basis Theory 3DS, Ravelin, … — and only want Tagada to charge. Don’t run a second authentication: report the final values and Tagada stores them as an already-authenticated session.

// You ran 3DS yourself. Report the result — no challenge, no redirect.
const threeds = await charging.threeds.createFromValues({
  eci: '05',                                   // two-digit ECI from your 3DS server
  authenticationValue: 'AAABBIIFmAAAAAAAAAWYAAAAAAA=', // CAVV / AAV, base64
  transStatus: 'Y',                            // Y authenticated · A attempted (both usable)
  dsTransID: 'dd21fcc9-6725-4a82-9591-ce603405b0db', // required for 3DS 2.x
  messageVersion: '2.2.0',
  cardBrand: 'visa',
  // type: 'merchant'  → for a 3RI authentication you will charge later as a MIT
});

// Pass threeds.id to payments.process() as `threedsSessionId` (Step 4). The
// values are forwarded verbatim to the acquirer, which validates the CAVV.

Rules of the road:

Only transStatus Y / A create a usable session. N / U / R / I are stored as failed and their values are never forwarded.
dsTransID is mandatory for an authenticated 3DS 2.x result. The session is still created without one — sessions are often created and never used — but its values are not forwarded to the charge, because acquirers reject an authenticated 2.x result with no DS transaction id.
The target processor must accept externally-authenticated values: NMI, RouteSense, Mastercard MPGS, Adyen, Airwallex. The processor needs enable3DS on and the payment flow threeDsEnabled. Stripe accounts connected directly (not through TagadaPay) ignore them and run their own 3DS (Option 1).
TagadaPay processors (Adyen, Stripe, Checkout.com): on a TagadaPay account whose PSP is Adyen, Stripe or Checkout.com, the values are used without enable3DS or threeDsEnabled, on customer-initiated card charges: the PSP receives them in place of Tagada’s request for its own 3DS, and can still ask the shopper to authenticate. They are not used, and the payment runs as if none had been sent (the PSP’s own 3DS included), for a 3RI session, a result other than Y / A, a CAVV that is not 28-character base64, a dsTransID that is not a UUID, an ECI other than 01 / 02 / 05 / 06, a 3DS version other than 2.1.x / 2.2.x, a Cartes Bancaires card, an authentication older than 90 days, a merchant-initiated charge, a wallet payment or a $0 card verification. Stripe also skips them on a co-badged Cartes Bancaires card and on a charge without customer-initiated stored credentials; Checkout.com skips them on a card saved at Checkout.com. TagadaPay accounts on another PSP ignore them.
For a MIT on a card you authenticated once (3RI), create the session with type: 'merchant' and charge with initiatedBy: 'merchant' + reasonType. TagadaPay processors do not use 3RI sessions.

When does 3DS trigger? When the card flow has threeDsEnabled: true (set per-merchant via Payment Flows) or the issuer requests SCA. How it runs is up to the processor: hosted PSPs return requireAction: 'redirect' (Option 1); gateways that need raw values use the standalone session (Option 2). When in doubt, skip this step and just handle the requireAction that the charge returns.

Step 4 — Charge

const { payment } = await charging.payments.process({
  paymentInstrumentId: paymentInstrument.id,
  storeId: 'store_xxx',
  amount: 4999,           // minor units — 4999 = €49.99
  currency: 'EUR',
  paymentMethod: 'card',
  mode: 'purchase',       // 'auth' to authorize-only
  threedsSessionId: threeds?.id,  // if you ran 3DS upfront
  // OPTIONAL — recommended for approval rates, but a charge works without any
  // address (digital products). If set, include a 2-letter `country`.
  billingAddress: {
    address1: '10 rue de Rivoli',
    city: 'Paris',
    postal: '75001',
    country: 'FR',
  },
  // OPTIONAL — only for physical goods; omit entirely for digital products.
  // shippingAddress: { address1: '...', city: '...', postal: '...', country: 'FR' },
  // STRONGLY RECOMMENDED — the shopper behind this call, as seen by your server.
  // Processors weigh the shopper IP heavily; Tagada cannot read it from a
  // server-to-server call and never sends your server's address instead.
  // On a store with gateway protection, `userAgent` is also what brings the
  // shopper back to your `returnUrl` after 3DS: without it they stay on the
  // protected domain. Send the browser's User-Agent verbatim.
  customer: { ipAddress: req.ip, userAgent: req.get('user-agent') },
  // Where the issuer's hosted 3DS / SCA page sends the customer back. REQUIRED
  // for any flow that can challenge (e.g. Adyen on EU cards) — without it the
  // payment can't be resumed after authentication.
  returnUrl: 'https://your-site.example/checkout/return?order=order_42',
});

// {
//   id: 'pay_xxx',
//   status: 'pending' | 'succeeded' | 'declined' | 'error' | 'refunded' | 'expired' | 'rejected' | 'on_hold',
//   subStatus: 'authorized' | 'captured' | 'waiting_action' | ...,
//   amount: 4999,
//   currency: 'EUR',
//   processor: 'proc_stripe_eu',
//   requireAction?: 'threeds' | 'redirect' | undefined,
//   requireActionData?: { ... },
//   ...
// }

Handling the response

// Always check `requireAction` first: a redirect/3DS step surfaces with
// status 'pending'.
if (payment.requireAction === 'redirect') {
  // Hosted 3-D Secure (e.g. Adyen on EU cards) OR a redirect APM (Klarna,
  // iDEAL, …). Send the customer to the issuer/processor page; they return
  // to your `returnUrl`, where you poll the payment until it's terminal.
  const redirect = payment.requireActionData.metadata.redirect; // { redirectUrl, method, data }
  if ((redirect.method ?? 'GET').toUpperCase() === 'POST') {
    // 3DS1: auto-submit a form POSTing redirect.data (MD + PaReq) to redirectUrl
  } else {
    window.location = redirect.redirectUrl;
  }
  return;
}
if (payment.requireAction === 'threeds') {
  // SDK-driven (non-redirect) 3DS: render the challenge from
  // payment.requireActionData with core-js, then resume the payment.
  return;
}

switch (payment.status) {
  case 'succeeded':
    // subStatus 'captured': money is moving. You're done.
    break;

  case 'pending':
    if (payment.subStatus === 'authorized') {
      // For mode: 'auth' — capture later with payments.capture(payment.id)
    }
    break;

  case 'declined':
  case 'error':
    // payment.failureReason is structured: 'do_not_honor', 'insufficient_funds', etc.
    break;
}

Multi-TPA routing (cascade & weighted)

payments.process doesn’t hit a processor directly — it runs the payment flow attached to the storeId. A single merchant can own several TPAs (e.g. an Adyen sub-merchant and a Stripe Merchant-of-Record account) and route across them with no code change on your side: same process call, different storeId.

Cascade (failover) — the flow has a primary processor and an ordered fallback list (fallbackMode: true). If the primary declines (non-terminal), Tagada automatically retries the same charge on the next TPA, with a fresh payment method per attempt. Your code just sees the final captured.
Weighted — multiple processors with weights; each charge is routed to one TPA by weight.

const { payment } = await tagada.payments.process({
  paymentInstrumentId,
  storeId,            // ← resolves to a cascade or weighted flow
  amount: 4999,
  currency: 'EUR',
  returnUrl,
});

// Which acquirer ended up capturing, and every attempt along the way:
payment.processorName;                       // final capturing processor
payment.transactions?.map((t) => t.status);  // e.g. ['declined', 'captured']

A processing key restricted to one TPA resolves to that TPA’s merchant account, so it can charge any store of that merchant — including a store whose flow spans several of the merchant’s TPAs. You don’t need a separate key per processor.

You create and manage these flows yourself, over the API — see Payment flows (cascade & weighted). A runnable demo (picker for single / cascade / weighted, plus a “force the primary to decline” toggle) is available to partners from their TagadaPay account manager.

Auth + capture (split-flow)

Authorize now, capture later (hotels, car rentals, pre-orders, marketplaces):

// Step A — authorize
const { payment: auth } = await charging.payments.process({
  paymentInstrumentId: 'pi_xxx',
  storeId: 'store_xxx',
  amount: 4999,
  currency: 'EUR',
  paymentMethod: 'card',
  mode: 'auth',
});

// auth.status === 'pending', auth.subStatus === 'authorized'
// Funds reserved on the card, not yet moved.

// Step B — capture (within ~7 days for most networks)
const { payment: captured } = await charging.payments.capture(auth.id, {
  amount: 4999,  // can capture less than authorized; partial captures supported
});

// captured.status === 'succeeded', captured.subStatus === 'captured'

You can also payments.cancel(auth.id) to release the authorization without capturing.

Refunds

Full refund:

await charging.payments.refund('pay_xxx');

Partial refund:

await charging.payments.refund('pay_xxx', { amount: 2000 });  // €20 back

Refunds route through the same processor as the original charge — no decisions on your side.

Merchant-initiated transactions (MIT)

For subscription renewals, retry logic, or any charge initiated without the customer present:

// First charge (customer-initiated, with 3DS if required)
const { payment: first } = await charging.payments.process({
  paymentInstrumentId: 'pi_xxx',
  storeId: 'store_xxx',
  amount: 4999,
  currency: 'EUR',
  paymentMethod: 'card',
  mode: 'purchase',
  initiator: 'customer',  // default
  saveForFuturePayments: true,  // tells the processor we'll re-use
});

// Subsequent renewals (no customer present, no 3DS)
const { payment: renewal } = await charging.payments.process({
  paymentInstrumentId: 'pi_xxx',
  storeId: 'store_xxx',
  amount: 4999,
  currency: 'EUR',
  paymentMethod: 'card',
  mode: 'purchase',
  initiator: 'merchant',  // ← MIT flag
  reasonCode: 'recurring',
  // The original network transaction id from `first` is auto-included
  // by the SDK so processors honor the MIT exemption.
});

The SDK reuses the original network transaction id transparently; you don’t have to track it yourself.

Listing and retrieving payments

// Single payment
const payment = await charging.payments.retrieve('pay_xxx');

// List with filters
const list = await charging.payments.list({
  filters: {
    status: 'succeeded',
    createdAt: { gte: '2026-04-01', lte: '2026-04-30' },
  },
  pagination: { page: 1, pageSize: 50 },
});

A Processing Key sees only payments belonging to its TPA. Partner keys can list across all TPAs they own.

Webhooks

To learn about asynchronous events (3DS callbacks, settlement, disputes), set up webhooks at the TPA level:

await charging.webhooks.endpoints.create({
  url: 'https://your-platform.com/webhooks/tagada',
  enabledEvents: [
    'charge.succeeded',
    'charge.failed',
    'charge.refunded',
    'dispute.created',
    'dispute.closed',
  ],
  secret: 'whsec_xxx',  // or auto-generate
});

See Webhooks for the full event catalog and signature verification.

Errors you should handle

HTTP	Code	Meaning	Action
400	`invalid_request`	Bad params	Fix the request, don’t retry
401	`auth_failed`	Bad / revoked key	Don’t retry; check key
402	`card_declined`	Issuer declined	Show a friendly message; don’t retry the same instrument
402	`insufficient_funds`	Issuer declined for funds	Same as above
409	`duplicate_charge`	Idempotency key collision	Re-fetch the existing payment
422	`processor_unavailable`	Processor down	Retry with exponential backoff
422	`requires_action`	3DS / redirect needed	Surface to customer, follow `requireAction`
429	`rate_limited`	Throttled	Honor `Retry-After` header
5xx	`server_error`	Our problem	Retry with exponential backoff

The SDK throws typed errors:

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

try {
  await charging.payments.process({ ... });
} catch (err) {
  if (err instanceof TagadaError) {
    if (err.code === 'card_declined') { ... }
    if (err.code === 'requires_action') { /* err.payment.requireAction === '...' */ }
  }
  throw err;
}

Get Started

CRM provisioning

Processing provisioning

REST reference