Accept a payment with your own cart

This page is not the Headless SDK. Use it when you already have the order (Medusa, WooCommerce, a custom order API) and only need to tokenize and charge. Native apps and partner server-to-server flows live here too.If TagadaPay should manage the cart, upsells, and funnel, use the Headless SDK instead (processPayment(), not this page).Not sure? Choose how you accept payments.

Which Approach Should I Use?

	Headless SDK	This page (core-js + REST)
Package	`@tagadapay/headless-sdk` (+ `core-js` peer for cards)	`@tagadapay/core-js` + REST / Node `payments.process`
Who owns the cart?	Tagada checkout session	You (Medusa, Woo, your backend)
Pay	`tagada.payment.processPayment({ checkoutSessionId, tagadaToken })`	Tokenize → instrument → 3DS → `POST /payments/process`
Checkout sessions	Built-in (`useCheckout()`, cart, promos, shipping)	Not used — you already have an order
3DS handling	Automatic inside `processPayment()`	Manual (create session + start challenge)
Best for	Custom UI, TagadaPay manages the cart	Your own commerce backend, mobile, later charges (MIT), platforms

Rule of thumb: You already have the order → this page. TagadaPay manages the cart → Headless. Hosted on TagadaPay → Plugin SDK. Charge a saved card later → Node payments.process(). See Choose how you accept payments.

When to Use This

Use case	Example
Own commerce backend	Medusa, custom Woo, your own order API — tokenize in the browser, charge with `/payments/process`
Mobile apps	Native iOS/Android apps that collect card data via your own UI
Embedded checkout	Injecting a payment form into a third-party page or iframe
Marketplace / platform	Collecting card details on behalf of sub-merchants
Later charges (MIT)	Subscription renewals, metered billing, retries — merchant-initiated, customer not present
Auth + capture	Authorize now, capture later (hotels, car rentals, pre-orders)

When NOT to Use This

Instead of…	Use…
Building a web checkout where TagadaPay manages the cart	Headless SDK — sessions, APMs, 3DS
You just want a hosted checkout page	Merchant Quick Start — 7 API calls, zero frontend code
You want a custom-branded page (HTML or Plugin SDK)	Funnel Pages — deploy pages as plugins
You need server-side recurring billing	Subscriptions Guide — managed subscription lifecycle

The Flow

Every payment follows 4 steps:

Tokenize card    →  Client-side, via @tagadapay/core-js
Create instrument →  Server-side, POST to TagadaPay API
3DS authenticate  →  Client + Server (if required by the card issuer)
Process payment   →  Server-side, POST to TagadaPay API

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  1. Tokenize │────▶│ 2. Instrument│────▶│   3. 3DS     │────▶│  4. Charge   │
│  (client)    │     │  (server)    │     │ (client+srv) │     │  (server)    │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
  Card details         TagadaToken          Challenge if         Amount + currency
  → Secure Vault       → Payment Inst.      required             → PSP routing
  → TagadaToken        + Customer                                → Transaction

Prerequisites

A TagadaPay account with an API key (Bearer token)
A store with at least one payment flow configured (connects to your PSP: Stripe, NMI, Airwallex, etc.)
Install the tokenization SDK:

npm install @tagadapay/core-js

The tokenization SDK runs client-side (browser). Steps 2–4 happen server-side with your API key. Never expose your API key in the browser.

Step 1: Tokenize the Card (Client-Side)

The card number never touches your server. It goes directly to a PCI-compliant secure vault (BasisTheory) and returns a token.

React
Vanilla JavaScript
Apple Pay / Google Pay

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

function CheckoutForm() {
  const { tokenizeCard, isLoading, error } = useCardTokenization({
    environment: 'production', // 'production' | 'development' | 'local'
  });

  async function handleSubmit() {
    const { tagadaToken, rawToken } = await tokenizeCard({
      cardNumber: '4242424242424242',
      expiryDate: '12/28',
      cvc: '123',
      cardholderName: 'Jane Doe',
    });

    // tagadaToken → base64 string, send to your server
    // rawToken.metadata.auth.scaRequired → true if 3DS is needed
    await sendToServer(tagadaToken, rawToken);
  }
}

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

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

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

// tagadaToken → base64 string, send to your server

For the raw token with SCA metadata:

const rawToken = await tokenizer.tokenizeCardRaw({
  cardNumber: '4242424242424242',
  expiryDate: '12/28',
  cvc: '123',
});

if (rawToken.metadata?.auth?.scaRequired) {
  console.log('3DS will be required');
}

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

const { tokenizeApplePay, tokenizeGooglePay } = useCardTokenization({
  environment: 'production',
});

// Apple Pay
const appleResult = await tokenizeApplePay(applePayToken);

// Google Pay
const { tagadaToken } = await tokenizeGooglePay(googlePayToken);

Merchant-scoped Apple Pay domains (BYOK / platform integrator): the payment-setup config attaches a domain-keyed applePayByok map to the apple_pay method’s metadata for these domains. Resolve the current hostname with resolveApplePayByok and pass the resulting merchantRegistrationId to both the merchant session and the tokenize call — Apple encrypts the wallet token to that registration’s certificate:

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

const byok = resolveApplePayByok(applePayMethod.metadata, window.location.hostname);

// Merchant session (inside onvalidatemerchant)
const session = await validateApplePayMerchant(
  byok?.displayName ?? storeName,
  window.location.host,
  byok?.merchantRegistrationId,
);

// Tokenization (inside onpaymentauthorized)
const appleResult = await tokenizeApplePay(applePayToken, byok?.merchantRegistrationId);

A null result from resolveApplePayByok means the domain uses the legacy platform configuration — omit the argument and behavior is unchanged. Alternatively, startApplePaySession from @tagadapay/core-js drives the whole sheet (session + tokenization) and accepts merchantRegistrationId in its config.See the Apple & Google Pay example for the full integration including wallet button setup.

What’s in a TagadaToken? It’s a base64-encoded JSON envelope containing the provider token, card metadata (last4, brand, BIN, expiry), SCA flags, and issuer information. It’s safe to send over the network — no raw card data.

Step 2: Create a Payment Instrument (Server-Side)

Send the tagadaToken from your client to your server, then call TagadaPay to create a reusable payment instrument:

curl -X POST https://app.tagadapay.com/api/public/v1/payment-instruments/create-from-token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tagadaToken": "eyJ0eXBlIjoiY2FyZC...",
    "storeId": "store_abc123",
    "customerData": {
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Doe"
    }
  }'

Response:

{
  "paymentInstrument": {
    "id": "pi_a1b2c3d4",
    "type": "card",
    "customerId": "cus_x1y2z3",
    "card": {
      "last4": "4242",
      "brand": "visa",
      "expMonth": 12,
      "expYear": 2028
    }
  },
  "customer": {
    "id": "cus_x1y2z3",
    "email": "jane@example.com"
  }
}

If the customer already exists, pass customerId instead of customerData. The instrument will be attached to the existing customer.

Save the paymentInstrument.id — you’ll use it for every charge on this card. The instrument is reusable for future payments (subscriptions, repeat purchases).

Step 3: 3DS Authentication (If Required)

3DS (3D Secure) is required by many card issuers, especially in Europe (SCA regulation). The tokenization step tells you if it’s needed via rawToken.metadata.auth.scaRequired. 3DS has two parts: creating a session (server + client) and handling the challenge (client).

3a. Create a 3DS Session

Client-side: Create a local session with the 3DS provider SDK:

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

const { createSession, startChallenge } = useThreeds({
  environment: 'production',
});

const session = await createSession(
  {
    id: paymentInstrument.id,
    token: rawToken.id,
    type: 'card',
    card: {
      last4: '4242',
      bin: '424242',
      expirationMonth: 12,
      expirationYear: 2028,
    },
  },
  {
    amount: 2999,       // in cents
    currency: 'USD',
    customerInfo: {
      name: 'Jane Doe',
      email: 'jane@example.com',
    },
  },
);

Server-side: Persist the session to TagadaPay so the payment processor can use it:

curl -X POST https://app.tagadapay.com/api/public/v1/threeds/create-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "basis_theory",
    "storeId": "store_abc123",
    "paymentInstrumentId": "pi_a1b2c3d4",
    "sessionData": {
      "sessionId": "bt_session_xyz",
      "metadata": {}
    }
  }'

Response:

{
  "id": "threeds_abc123",
  "externalSessionId": "bt_session_xyz",
  "provider": "basis_theory",
  "status": "created",
  "paymentInstrumentId": "pi_a1b2c3d4"
}

3b. Handle the Challenge (After Payment — See Step 4)

If the issuer requires a challenge (password, SMS, biometric), it comes back in the payment response. You handle it client-side — see Step 4b below.

Step 4: Process the Payment (Server-Side)

4a. Send the charge request

curl -X POST https://app.tagadapay.com/api/public/v1/payments/process \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2999,
    "currency": "USD",
    "storeId": "store_abc123",
    "paymentInstrumentId": "pi_a1b2c3d4",
    "threedsSessionId": "threeds_abc123",
    "initiatedBy": "customer",
    "mode": "purchase"
  }'

Field	Type	Description
`amount`	`number`	Amount in cents (2999 = $29.99)
`currency`	`string`	ISO currency code (USD, EUR, GBP, etc.)
`storeId`	`string`	Your store ID
`paymentInstrumentId`	`string`	From Step 2
`threedsSessionId`	`string`	From Step 3 (optional if 3DS not required)
`initiatedBy`	`string`	`"customer"` (CIT) or `"merchant"` (MIT)
`mode`	`string`	`"purchase"` (charge immediately), `"auth"` (authorize only), or `"capture"` (capture a previous auth)
`reasonType`	`string`	For MIT only: `"recurring"`, `"unscheduled"`, or `"installment"`
`paymentFlowId`	`string`	Optional — forces a specific payment flow (PSP routing rule)

If payment succeeds immediately:

{
  "payment": {
    "id": "pay_xyz789",
    "amount": 2999,
    "currency": "USD",
    "status": "succeeded",
    "requireAction": "none"
  }
}

If 3DS challenge is required:

{
  "payment": {
    "id": "pay_xyz789",
    "status": "pending",
    "requireAction": "threeds_auth",
    "requireActionData": {
      "type": "threeds_auth",
      "metadata": {
        "threedsSession": {
          "externalSessionId": "bt_session_xyz",
          "acsChallengeUrl": "https://acs.issuer.com/challenge",
          "acsTransID": "acs_trans_123",
          "messageVersion": "2.2.0"
        }
      }
    }
  }
}

4b. Handle the 3DS Challenge (Client-Side)

When the payment response has requireAction: "threeds_auth", show the challenge to the customer:

const challengeResult = await startChallenge({
  sessionId: threedsSession.externalSessionId,
  acsChallengeUrl: threedsSession.acsChallengeUrl,
  acsTransactionId: threedsSession.acsTransID,
  threeDSVersion: threedsSession.messageVersion,
});

if (challengeResult.success) {
  // 3DS passed — poll for final payment status
}

The SDK opens a modal with the issuer’s authentication page. Once the customer completes it, poll for the final status.

4c. Poll for Final Status

After 3DS completes, the PSP processes the payment asynchronously. Poll until you get a terminal status:

curl https://app.tagadapay.com/api/public/v1/payments/pay_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Poll every 1–2 seconds. Terminal statuses: succeeded, failed, declined.

CIT vs MIT (Customer vs Merchant Initiated)

	CIT (Customer Initiated)	MIT (Merchant Initiated)
When	Customer is present and clicks “Pay”	Server charges without customer present
Examples	First purchase, one-click reorder	Subscription renewal, metered billing, retry
3DS	Required if issuer demands it	Typically exempt (uses stored credential)
`initiatedBy`	`"customer"`	`"merchant"`
`reasonType`	Not needed	`"recurring"`, `"unscheduled"`, or `"installment"`

CIT Example (Customer Paying Now)

{
  "amount": 2999,
  "currency": "USD",
  "storeId": "store_abc123",
  "paymentInstrumentId": "pi_a1b2c3d4",
  "initiatedBy": "customer",
  "mode": "purchase"
}

MIT Example (Subscription Renewal)

{
  "amount": 2999,
  "currency": "USD",
  "storeId": "store_abc123",
  "paymentInstrumentId": "pi_a1b2c3d4",
  "initiatedBy": "merchant",
  "reasonType": "recurring",
  "mode": "purchase"
}

MIT Example (Auth + Capture)

// Step 1: Authorize
{
  "amount": 2999,
  "currency": "USD",
  "storeId": "store_abc123",
  "paymentInstrumentId": "pi_a1b2c3d4",
  "initiatedBy": "merchant",
  "reasonType": "unscheduled",
  "mode": "auth"
}

// Step 2: Capture later
{
  "paymentId": "pay_xyz789",
  "mode": "capture"
}

Void and Refund

Void (Cancel an Authorization)

curl -X POST https://app.tagadapay.com/api/public/v1/payments/void \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paymentId": "pay_xyz789", "storeId": "store_abc123" }'

Refund (Full or Partial)

curl -X POST https://app.tagadapay.com/api/public/v1/payments/refund \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "pay_xyz789",
    "storeId": "store_abc123",
    "amount": 1000
  }'

Omit amount for a full refund.

What TagadaPay Does Under the Hood

When you call /payments/process, TagadaPay:

Routes to the right PSP — based on your payment flow rules (card brand, currency, amount, BIN range, etc.)
Attaches 3DS data — if a threedsSessionId is provided, the authentication result is forwarded to the PSP
Handles retries — if the primary PSP declines, the payment flow can cascade to a backup PSP
Normalizes the response — regardless of which PSP handled it, you get the same response format
Records the transaction — for analytics, dispute management, and reconciliation

You don’t need to integrate with Stripe, NMI, Airwallex, etc. individually. Configure the PSP connections in the CRM dashboard, set up payment flow routing rules, and TagadaPay handles the rest.

API Reference

Endpoint	Method	Purpose
`/payment-instruments/create-from-token`	POST	Create instrument from TagadaToken
`/payment-instruments/{id}`	GET	Get instrument details
`/customers/{id}/payment-instruments`	GET	List customer’s instruments
`/threeds/create-session`	POST	Create 3DS session
`/payments/process`	POST	Process a payment (CIT or MIT)
`/payments/{id}`	GET	Get payment status
`/payments/void`	POST	Void an authorization
`/payments/refund`	POST	Full or partial refund

Working Examples

Complete working examples with React, TypeScript, and Tailwind CSS are available on GitHub:

Card Tokenization + Payment

Full 4-step payment flow with 3DS

Apple Pay & Google Pay

Wallet tokenization integration

Test card: 4242 4242 4242 4242 (any future expiry, any CVC)

SDK Reference

`@tagadapay/core-js` Package

Export	Import Path	What it provides
Core	`@tagadapay/core-js`	`Tokenizer` class, `createTagadaToken`, `decodeTagadaToken`
React	`@tagadapay/core-js/react`	`useCardTokenization`, `useThreeds` hooks
3DS	`@tagadapay/core-js/threeds`	`ThreedsManager`, `ThreedsModal` for manual 3DS

Key Types

interface CardPaymentMethod {
  cardNumber: string;
  expiryDate: string;   // "MM/YY"
  cvc: string;
  cardholderName?: string;
}

interface CardTokenResponse {
  id: string;
  type: string;
  data: { number?: string; expiration_month?: number; expiration_year?: number };
  metadata?: {
    auth?: { scaRequired?: boolean };
    tokenizedAt?: string;
  };
}

interface TagadaToken {
  type: 'card' | 'apple_pay' | 'google_pay';
  token: string;
  provider: string;
  nonSensitiveMetadata: {
    last4?: string;
    brand?: string;
    bin?: string;
    expiryMonth?: number;
    expiryYear?: number;
    funding?: string;
    fingerprint?: string;
    authentication?: 'sca_required' | 'optional';
    issuer?: { name?: string; country?: string };
  };
}

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

Confirm the payment succeeds, then list it with tagada.payments.list(). To exercise a 3DS return, use a card your processor flags for authentication and confirm the shopper lands back on the returnUrl you passed. Full sandbox setup (processor, payment flow, store): Sandbox testing.

npm Package

@tagadapay/core-js on npm

API Reference

Full REST API documentation

​Accept a payment with your own cart

​Which Approach Should I Use?

​When to Use This

​When NOT to Use This

​The Flow

​Prerequisites

​Step 1: Tokenize the Card (Client-Side)

​Step 2: Create a Payment Instrument (Server-Side)

​Step 3: 3DS Authentication (If Required)

​3a. Create a 3DS Session

​3b. Handle the Challenge (After Payment — See Step 4)

​Step 4: Process the Payment (Server-Side)

​4a. Send the charge request

​4b. Handle the 3DS Challenge (Client-Side)

​4c. Poll for Final Status

​CIT vs MIT (Customer vs Merchant Initiated)

​CIT Example (Customer Paying Now)

​MIT Example (Subscription Renewal)

​MIT Example (Auth + Capture)

​Void and Refund

​Void (Cancel an Authorization)

​Refund (Full or Partial)

​What TagadaPay Does Under the Hood

​API Reference

​Working Examples

Card Tokenization + Payment

Apple Pay & Google Pay

​SDK Reference

​@tagadapay/core-js Package

​Key Types

​Test your integration

npm Package

API Reference

Accept a payment with your own cart

Which Approach Should I Use?

When to Use This

When NOT to Use This

The Flow

Prerequisites

Step 1: Tokenize the Card (Client-Side)

Step 2: Create a Payment Instrument (Server-Side)

Step 3: 3DS Authentication (If Required)

3a. Create a 3DS Session

3b. Handle the Challenge (After Payment — See Step 4)

Step 4: Process the Payment (Server-Side)

4a. Send the charge request

4b. Handle the 3DS Challenge (Client-Side)

4c. Poll for Final Status

CIT vs MIT (Customer vs Merchant Initiated)

CIT Example (Customer Paying Now)

MIT Example (Subscription Renewal)

MIT Example (Auth + Capture)

Void and Refund

Void (Cancel an Authorization)

Refund (Full or Partial)

What TagadaPay Does Under the Hood

API Reference

Working Examples

SDK Reference

`@tagadapay/core-js` Package

Key Types

Test your integration