Payment Setup

The payment module is the core of the Headless SDK. It lets you discover which payment methods are configured for a store, tokenize cards, and process payments with automatic 3DS, redirect, and polling handling.

Discover Available Payment Methods

Every store has a payment setup config — a map of payment methods (card, Apple Pay, Google Pay, Klarna, etc.) with their enabled/disabled state, processor IDs, and flow IDs.

const setup = await tagada.payment.getPaymentSetup(checkoutSessionId);

// Example response:
// {
//   "card": { enabled: true, method: "card", paymentFlowId: "pf_xxx" },
//   "apple_pay:stripe": { enabled: true, method: "apple_pay", express: true, processorId: "proc_xxx" },
//   "google_pay:stripe": { enabled: true, method: "google_pay", express: true },
//   "klarna:stripe": { enabled: true, method: "klarna", processorId: "proc_stripe" },
// }

Where the config comes from, in order: an explicit paymentSetupConfig you pass in, the config injected on Tagada-hosted pages, and otherwise the payment methods enabled on the store for that checkout session (resolved from the API). Keys are method or method:provider — so on a self-hosted page an Apple Pay integration shows up as "apple_pay", the card form as "card". An empty object means no payment method is enabled for the session’s store/currency.

Just the enabled method keys

const methods = await tagada.payment.getEnabledMethods(checkoutSessionId);
// ["card", "apple_pay:stripe", "google_pay:stripe"]

Express methods with browser availability

const express = await tagada.payment.getExpressMethods(checkoutSessionId);
// {
//   applePay: { available: true, processorId: "proc_xxx" },
//   googlePay: { available: true },
//   klarna: { available: true, processorId: "proc_stripe" },
// }

The SDK automatically checks ApplePaySession.canMakePayments() in the browser to determine Apple Pay availability.

Card Payment Flow

Recommended: `processPayment()`

processPayment() is the high-level orchestrator that handles the entire payment lifecycle automatically:

Submits payment to the processor
If 3DS / bank auth is required → redirects the user and resumes on return
If the payment is async → polls until a terminal status
Returns a typed ProcessPaymentResult

// 1. Tokenize
const { tagadaToken } = await tagada.payment.tokenizeCard({
  cardNumber: '4242424242424242',
  expiryDate: '12/28',
  cvc: '123',
  cardholderName: 'Jane Doe',
});

// 2. Process payment (3DS, redirects, polling all handled)
const result = await tagada.payment.processPayment({
  checkoutSessionId: session.id,
  tagadaToken,
});

// 3. Handle result
switch (result.status) {
  case 'succeeded':
    console.log('Payment confirmed!', result.order);
    break;
  case 'requires_redirect':
    // In React, usePayment() handles this automatically.
    // In vanilla JS, redirect manually:
    window.location.href = result.redirectUrl;
    break;
  case 'failed':
    console.error('Payment failed:', result.error);
    break;
  case 'pending':
    console.log('Still processing...', result.paymentId);
    break;
}

tokenizeCard() requires @tagadapay/core-js as an optional peer dependency. Install it: npm install @tagadapay/core-js.

Return type: `ProcessPaymentResult`

The return value is a discriminated union — check result.status for exhaustive handling:

Status	Fields	Meaning
`succeeded`	`payment`, `order`	Payment confirmed. Show success screen.
`requires_redirect`	`redirectUrl`, `method?`, `postData?`, `paymentId`	User must visit a URL (3DS, bank auth, APM).
`failed`	`error`, `payment?`	Payment declined or errored.
`pending`	`paymentId`	Still processing (rare — polling timed out).

3DS Return URL

After a 3DS redirect, the bank sends the user back to your page with query parameters. The SDK auto-detects these and resumes the payment:

React (usePayment): Handled automatically on mount — detects ?paymentAction=... params, polls for result, fires callbacks.
Vanilla JS: Call tagada.payment.maybeResumeFromUrl() on page load. That is the one-liner. resumeAfterRedirect(paymentId) is the lower-level equivalent if you already parsed the query yourself.

returnUrl passed to processPayment() (defaults to window.location.href) must be the page that runs this resume hook. After 3DS the bank sends the shopper back there.

// Vanilla JS — first thing on page load
const resumed = await tagada.payment.maybeResumeFromUrl();
if (resumed?.status === 'succeeded') {
  window.location.href = `/thank-you?orderId=${resumed.order?.id}`;
} else if (resumed?.status === 'failed') {
  showError(resumed.error);
}
// null → no 3DS return, render the checkout as usual

Express Checkout

Apple Pay

const result = await tagada.payment.processApplePay({
  checkoutSessionId: session.id,
  applePayToken: applePayEvent.payment.token,
});

Merchant-scoped Apple Pay domains. When the checkout domain runs merchant-scoped Apple Pay — either the merchant’s own Apple certificates (BYOK) or Tagada’s platform-integrator registration — the backend attaches a domain-keyed applePayByok map to the apple_pay method’s metadata. The SDK resolves the current hostname against that map automatically and sends the matching merchant_registration_id to Basis Theory during tokenization, so no code change is needed. Pass merchantRegistrationId explicitly on processApplePay only to override the automatic resolution, or call tagada.payment.resolveApplePayRegistration() yourself when minting the Apple Pay merchant session (its merchantRegistrationId and displayName must go into the Basis Theory POST /apple-pay/session call for these domains).

Google Pay

const result = await tagada.payment.processGooglePay({
  checkoutSessionId: session.id,
  googlePayToken: paymentData.paymentMethodData.tokenizationData.token,
});

Redirect APMs (Klarna, iDEAL, etc.)

For the APM lifecycle rules (redirect → webhook, vouchers, recurring limits) see Alternative payment methods.

const result = await tagada.payment.processApm({
  checkoutSessionId: session.id,
  paymentMethod: 'klarna',
  processorId: 'proc_stripe',
});

if (result.payment.requireAction === 'redirect') {
  window.location.href = result.payment.requireActionData.redirectUrl;
}

React Hook

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

function PaymentForm({ sessionId }) {
  const {
    processPayment,
    tokenizeCard,
    isProcessing,
    paymentSetup,
    loadPaymentSetup,
  } = usePayment({
    onPaymentSuccess: (result) => {
      router.push(`/thank-you?orderId=${result.order?.id}`);
    },
    onPaymentFailed: (result) => {
      setError(result.error);
    },
  });

  const handleSubmit = async () => {
    const { tagadaToken } = await tokenizeCard({ cardNumber, expiryDate, cvc });
    await processPayment({ checkoutSessionId: sessionId, tagadaToken });
    // 3DS redirects + return detection + polling all handled automatically
  };

  return (
    <button onClick={handleSubmit} disabled={isProcessing}>
      {isProcessing ? 'Processing...' : 'Pay Now'}
    </button>
  );
}

Full Hook API

Property / Method	Description
`processPayment(opts)`	High-level: tokenize → pay → 3DS → poll → callbacks. Recommended.
`pay(opts)`	Low-level: submit payment, returns raw `PayResult`. No auto-redirect.
`tokenizeCard(card)`	Tokenize card via `@tagadapay/core-js`
`isProcessing`	True during payment processing
`paymentSetup`	Cached payment method config
`loadPaymentSetup(sessionId)`	Fetch available payment methods
`getExpressMethods(sessionId)`	Check Apple Pay / Google Pay availability
`onPaymentSuccess`	Callback when payment succeeds (including after 3DS return)
`onPaymentFailed`	Callback when payment fails or is declined

Advanced API

For advanced use cases, you can create instruments and process payments separately:

// Create a reusable payment instrument
const { paymentInstrument } = await tagada.payment.createInstrument({
  tagadaToken,
  storeId: 'store_xxx',
  customerData: { email: 'jane@example.com' },
});

// Create 3DS session
const threeds = await tagada.payment.create3dsSession({
  paymentInstrumentId: paymentInstrument.id,
  sessionData: { sessionId: 'bt_session_xyz' },
});

// Process with instrument directly
const result = await tagada.payment.payDirect({
  checkoutSessionId: session.id,
  paymentInstrumentId: paymentInstrument.id,
  threedsSessionId: threeds.id,
});

Test your integration

In sandbox, any 16-digit card works. Use this one:


Card	`4242 4242 4242 4242`
Expiry	Any future date
CVC	Any 3 digits

Call processPayment() and confirm result.status === 'succeeded'.
Confirm returnUrl is the page that runs maybeResumeFromUrl() (vanilla) or usePayment (React). After a 3DS challenge the bank sends the shopper back there.

Full sandbox setup: Sandbox testing.

Need even more control? For instrument-level management, later charges (MIT — merchant-initiated, customer not present), auth+capture, or mobile apps, see Accept a payment with your own cart.

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

Payment Setup

Payment Setup

Discover Available Payment Methods

Just the enabled method keys

Express methods with browser availability

Card Payment Flow

Recommended: `processPayment()`

Return type: `ProcessPaymentResult`

3DS Return URL

Express Checkout

Apple Pay

Google Pay

Redirect APMs (Klarna, iDEAL, etc.)

React Hook

Full Hook API

Advanced API

Test your integration

​Payment Setup

​Discover Available Payment Methods

​Just the enabled method keys

​Express methods with browser availability

​Card Payment Flow

​Recommended: processPayment()

​Return type: ProcessPaymentResult

​3DS Return URL

​Express Checkout

​Apple Pay

​Google Pay

​Redirect APMs (Klarna, iDEAL, etc.)

​React Hook

​Full Hook API

​Advanced API

​Test your integration

Payment Setup

Discover Available Payment Methods

Just the enabled method keys

Express methods with browser availability

Card Payment Flow

Recommended: `processPayment()`

Return type: `ProcessPaymentResult`

3DS Return URL

Express Checkout

Apple Pay

Google Pay

Redirect APMs (Klarna, iDEAL, etc.)

React Hook

Full Hook API

Advanced API

Test your integration