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 charging = new Tagada(process.env.MERCHANT_42_SUBKEY!);

const { paymentInstrument, customer } = await charging.paymentInstruments.createFromToken({
  tagadaToken,
  storeId: 'store_xxx',
  customerData: {
    email: 'jane@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
    phone: '+33612345678',
    billingAddress: {
      line1: '10 rue de Rivoli',
      city: 'Paris',
      postalCode: '75001',
      country: 'FR',
    },
  },
});

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

const threeds = await charging.threeds.createSession({
  provider: 'basis_theory',
  storeId: 'store_xxx',
  paymentInstrumentId: paymentInstrument.id,
  sessionData: {
    /* device info collected client-side via core-js */
  },
});

// If status === 'challenge_required':
//   - Render an iframe pointing to threeds.challengeUrl
//   - The challenge happens in the customer's browser
//   - On completion, the SDK fires a callback with the verified result

// If status === 'frictionless':
//   - No challenge needed, proceed directly to 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
  metadata: {
    yourOrderId: 'order_42',
    // any free-form key-value
  },
});

// {
//   id: 'pay_xxx',
//   status: 'captured' | 'authorized' | 'pending' | 'failed' | 'requires_action',
//   amount: 4999,
//   currency: 'EUR',
//   processor: 'proc_stripe_eu',
//   requireAction?: 'threeds' | 'redirect' | undefined,
//   requireActionData?: { ... },
//   ...
// }

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 'requires_action':
    if (payment.requireAction === 'threeds') {
      // Render the 3DS challenge using payment.requireActionData
      // Then re-call payments.process with the result
    } else if (payment.requireAction === 'redirect') {
      // Redirect APM (Klarna etc.) — see the APMs page
      window.location = payment.requireActionData.metadata.redirect.redirectUrl;
    }
    break;

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

// 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: [
    'payment.succeeded',
    'payment.failed',
    'payment.refunded',
    'dispute.opened',
    '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;
}