Skip to main content

Accept a payment with your own cart

Payments V2. This page documents V2 payments (pay-v2, payments/process, threeds/* on the Commerce API). V2 is the reference for every live integration today. The new Payments API (V3) is in preview: see V2 or V3: which one should I use?
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?

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

When NOT to Use This


The Flow

Every payment follows 4 steps:

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:
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.
Already PCI-DSS compliant and holding the card number yourself? There is a server-side equivalent, paymentInstruments.createFromCard(), that skips the browser entirely — see Server-to-server payments.⚠️ It is off by default and TagadaPay has to enable it on your account first, otherwise the call fails with Please contact support to ask for raw card data enablement. Ask your account manager before building against it. If you are not already PCI-compliant, stay on this page: tokenizing in the browser is what keeps the card number out of your scope.
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:
customer is the shopper as seen by your server (IP and User-Agent), not your server’s own address — see Pass the shopper’s IP. It is kept on the customer so later charges carry it. Response:
customerData reuses the store’s customer with the same email (case-insensitive, surrounding spaces ignored), creating one only when none exists; you can also pass customerId explicitly.
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:
Server-side: Persist the session to TagadaPay so the payment processor can use it:
Response:

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

If payment succeeds immediately:
If 3DS challenge is required:
If the processor runs 3DS itself (Stripe, Adyen and other processors that host the challenge):
Send the shopper to requireActionData.metadata.redirect.redirectUrl. They authenticate on the processor’s page and come back to your returnUrl. Then poll for the final status (4c).
This needs a returnUrl on the charge. Without one there is no page to send the shopper to, so on Stripe a card that needs 3DS is declined straight away, not left pending: status is declined, error.code is authentication_required and error.processorCode is authentication_not_handled. To keep those sales, pass returnUrl on every customer-initiated payment and handle requireAction: "redirect". A merchant-initiated payment (initiatedBy: "merchant") does not need it.

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

When the payment response has requireAction: "threeds_auth", show the challenge to the customer:
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:
Poll every 1–2 seconds. Terminal statuses: succeeded, failed, declined.

CIT vs MIT (Customer vs Merchant Initiated)

CIT Example (Customer Paying Now)

MIT Example (Subscription Renewal)

MIT Example (Auth + Capture)

Save a Card Without Charging ($0 Verification)

For pay-as-you-go, save the card while the customer is present (3DS runs if the issuer asks for it), then charge it off-session later.
  • mode: "verify" requires amount: 0 and initiatedBy: "customer". orderId, subscriptionId and paymentMethod are not accepted. Any other mode still requires amount > 0.
  • If the response has requireAction, send the customer through it exactly as for a payment. The verification completes when they return.
  • Use the same customerId and paymentInstrumentId for the later charges. That is how they are linked to the verification.

Pass the Shopper’s IP and User Agent

On this path your server is the caller, so Tagada sees your datacenter, not the shopper. Processors weigh the shopper IP heavily (Stripe Radar, Adyen risk, issuer scoring). Forward the shopper’s IP and the browser’s User-Agent, as your server received them, in customer — on create-from-token (kept on the customer for later charges) and on every payments/process you can.
  • Never your own server’s address. Tagada never substitutes it either: a charge without customer and without a known device simply carries no IP.
  • ipAddress must be a valid public IPv4 or IPv6; anything else is refused with 400. Behind a proxy, take the first entry of X-Forwarded-For.
  • On merchant-initiated charges (rebills) the shopper is not present: omit customer, the IP kept on the customer from the original purchase is used.

Request a 3DS Challenge

By default, whether 3DS runs depends on your payment setup and on the card. To ask for a challenge on one payment while the customer is present, add threeDSecure: "challenge".
  • The issuer makes the final call. The response has either a requireAction (send the customer through it, as for any 3DS payment) or a final status straight away: the issuer authenticated the customer without a challenge, and the payment still counts as 3DS-authenticated.
  • Card payments with initiatedBy: "customer" only. The request is refused on merchant-initiated charges and on redirect payment methods.
  • It also works with mode: "auth" and mode: "verify".

Void and Refund

Void (Cancel an Authorization)

Refund (Full or Partial)

Omit amount for a full refund.

What TagadaPay Does Under the Hood

When you call /payments/process, TagadaPay:
  1. Routes to the right PSP — based on your payment flow rules (card brand, currency, amount, BIN range, etc.)
  2. Attaches 3DS data — if a threedsSessionId is provided, the authentication result is forwarded to the PSP
  3. Handles retries — if the primary PSP declines, the payment flow can cascade to a backup PSP
  4. Normalizes the response — regardless of which PSP handled it, you get the same response format
  5. 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


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

Key Types

Test your integration

In sandbox, any 16-digit card works. Use this one: 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