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?Which Approach Should I Use?
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.- React
- Vanilla JavaScript
- Apple Pay / Google Pay
Step 2: Create a Payment Instrument (Server-Side)
Send thetagadaToken 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:
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 viarawToken.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: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:
requireActionData.metadata.redirect.redirectUrl. They authenticate on the processor’s page and come back to your returnUrl. Then poll for the final status (4c).
4b. Handle the 3DS Challenge (Client-Side)
When the payment response hasrequireAction: "threeds_auth", show the challenge to the customer:
4c. Poll for Final Status
After 3DS completes, the PSP processes the payment asynchronously. Poll until you get a terminal status: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"requiresamount: 0andinitiatedBy: "customer".orderId,subscriptionIdandpaymentMethodare not accepted. Any other mode still requiresamount > 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
customerIdandpaymentInstrumentIdfor 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’sUser-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
customerand without a known device simply carries no IP. ipAddressmust be a valid public IPv4 or IPv6; anything else is refused with400. Behind a proxy, take the first entry ofX-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, addthreeDSecure: "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"andmode: "verify".
Void and Refund
Void (Cancel an Authorization)
Refund (Full or Partial)
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
threedsSessionIdis 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
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
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
