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

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.

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.

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
    },
  },
});

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

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

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

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' },
  // 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: 'captured' | 'authorized' | 'pending' | 'failed' | 'requires_action',
//   amount: 4999,
//   currency: 'EUR',
//   processor: 'proc_stripe_eu',
//   requireAction?: 'threeds' | 'redirect' | undefined,
//   requireActionData?: { ... },
//   ...
// }

// Always check `requireAction` first: a redirect/3DS step can surface with
// status 'pending' OR 'requires_action' depending on the processor.
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 'captured':
    // Money is moving. You're done.
    break;

  case 'authorized':
    // For mode: 'auth' — capture later with payments.capture(payment.id)
    break;

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

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']

// 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 === '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 === 'captured'

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

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

// 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.
});

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

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

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
});

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;
}