> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# V2 or V3: which one should I use?

> Compare V2 payments on the Commerce API with the Payments API (V3), and pick the right one.

TagadaPay has two payment interfaces. Both run in production on the same host, `https://api.tagada.io`.

| | **V2 payments** | **Payments API (V3)** |
| - | - | - |
| Status | Generally available. Every merchant uses it today. | [Preview](https://docs.tagada.io/payments-api/overview.md#release-phases). Access on request. |
| Base path | `/api/public/v1` (Commerce API) | `/v1` |
| Main calls | `checkout/pay-v2`, `payments/process`, `threeds/*`, `payments/refund`, `payments/void` | `POST /v1/payments`, `/confirm`, `/capture`, `/cancel`, `/retry`, `POST /v1/refunds` |
| Keys | Dashboard API keys | Secret keys `tsk_`, publishable keys `tpk_` |
| Versioning | Not dated; additive changes only | Dated header `Payments-Version: 2026-11-01` |
| Idempotency | Optional `Idempotency-Key` on some calls | `Idempotency-Key` required on every write |
| 3D Secure | You create 3DS sessions (`threeds/*`) or send your own result | The API decides and runs it; the browser follows `next_action` |
| Routing | Payment flows | Payment policies (versioned, pinned on each payment) |
| Browser | `@tagadapay/core-js` tokenizer, `@tagadapay/headless-sdk`, `@tagadapay/plugin-sdk` | `@tagadapay/core-js/payments-v3` |
| Server SDK | `@tagadapay/node-sdk` | No server SDK yet. Call the HTTP API. |
| Webhooks | V2 webhooks | Coming soon. V2 webhooks keep firing for V3 stores. |
| Reference | [Commerce API reference](https://docs.tagada.io/api-reference/introduction.md) | [Payments API reference](https://docs.tagada.io/payments-api/reference/introduction.md) |

## Use V2 if

* You have a live integration. It keeps working, and keeps working after your store moves to the Payments API.
* You use the Headless SDK, the Plugin SDK, Shopify or WooCommerce. You keep the same calls; on a store moved to the Payments API, TagadaPay routes them for you.
* You need a server SDK (`@tagadapay/node-sdk`), self-serve keys, or your own 3DS results.

## Use V3 if

* You are building a **new** direct integration (your own checkout, your own order system) and you are part of the preview.
* You want one Payment object with explicit statuses, `next_action` and a dated contract.

> [!NOTE]
>
> You do not have to pick one per store. A store moved to the Payments API still answers V2 calls through a compatibility layer, so existing code and new V3 code can run side by side. See [Migrate from V2](https://docs.tagada.io/payments-api/migrate-from-v2.md).

## What does not change

* Your stores, products, orders, customers and subscriptions stay on the Commerce API (`/api/public/v1`). Only payments have a V3.
* Your processors and your dashboard.
* Your V2 webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.