> ## 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.

# Migrate from V2 to the Payments API

> What changes, what stays, how a store is switched, and how V2 calls keep working on a switched store.

Moving to the Payments API happens in two independent steps:

1. **TagadaPay switches your store** from V2 to the Payments API. Your existing integration does not change.
2. **You adopt the V3 API** for new code, when you want to, and while it is in preview.

You can stop after step 1. Most merchants will.

## Step 1: the per-store switch

Each store has a payments version, `v2` by default. When a store is switched to `v3`, its **new** payments are processed by the Payments API.

| | |
| - | - |
| Who switches | TagadaPay. There is no merchant setting or API call to switch a store. |
| When | Only after the store passes a readiness check. A store that uses a feature the Payments API does not support yet stays on V2. |
| Routing | The store's V2 payment flows are imported as payment policies. A `paymentFlowId` sent by V2 code selects the imported policy. |
| Payments made before the switch | Stay on V2 for capture, void, refund, disputes and 3DS continuation. |
| Subscriptions | Each renewal period is collected by the side that owns it, so a period is never charged twice. |
| Going back | A store can be moved back to V2. Open renewals are handed back. |

### Compatibility: V2 calls keep working

On a switched store, every V2 payment call is answered by the Payments API through a compatibility layer. You change nothing:

| You call | On a V3 store |
| - | - |
| Headless SDK `processPayment()` (`checkout/pay-v2`) | Works. Same request, same response. |
| Plugin SDK payments | Works. |
| Node SDK `payments.process()`, including `paymentFlowId` | Works. `paymentFlowId` selects the policy imported from that flow. |
| Node SDK `payments.refund()`, `payments.void()` | Works. Routed to whichever side owns the payment. |
| V2 webhooks | Keep firing. |

V2 responses on a V3 store are the same as on a V2 store, except for **new fields** that may appear. Ignore fields you do not know.

> [!WARNING]
>
> Do not branch your code on the store's payments version. It is not exposed in V2 responses, and it can change back.

## Step 2: adopt the V3 API

Use the V3 API for a new integration on a switched store. A call to `/v1` for a store still on V2 gets `409 store_not_on_payments_api`.

### What changes

| Topic | V2 | V3 |
| - | - | - |
| Host and path | `https://api.tagada.io/api/public/v1` | `https://api.tagada.io/v1` |
| Keys | Dashboard API key | Secret key `tsk_` on the server, publishable key `tpk_` in the browser. See [Authentication](https://docs.tagada.io/payments-api/authentication.md). |
| Version | None | `Payments-Version: 2026-11-01`. See [Versioning](https://docs.tagada.io/payments-api/versioning.md). |
| Charge a card | `payments/process` with a payment instrument | `POST /v1/payments`, then confirm in the browser |
| Pay a checkout session | `checkout/pay-v2` | Not exposed to merchants on V3. Keep the Headless SDK. |
| 3D Secure | `threeds/create-session`, then pass `threedsSessionId` | Automatic. Follow `next_action`. See [3D Secure](https://docs.tagada.io/payments-api/three-d-secure.md). |
| Card collection | `@tagadapay/core-js` tokenizer, `tagadaToken` | `@tagadapay/core-js/payments-v3`: `cardFields`, `createPaymentMethod` |
| Status | Per-endpoint shapes | One `status` on the Payment. See [Payment lifecycle](https://docs.tagada.io/payments-api/payment-lifecycle.md). |
| Refund | `payments/refund` | `POST /v1/refunds` |
| Void | `payments/void` | `POST /v1/payments/{id}/cancel` |
| Routing | Payment flows | Payment policies |
| Errors | `{ code, message, data }` | `{ error: { type, code, message, param, request_id } }`. See [Errors](https://docs.tagada.io/payments-api/errors.md). |
| Idempotency | Optional | Required on writes. See [Idempotency](https://docs.tagada.io/payments-api/idempotency.md). |

### What stays

* Stores, products, orders, customers, subscriptions and funnels: the Commerce API.
* Your processors, your dashboard and your payouts.
* Your webhooks (V2).

### Checklist

1. Ask TagadaPay to switch your store, and wait for the switch.
2. Get a secret key for the preview (self-serve keys are coming soon).
3. Get the store's publishable key with `POST /v1/publishable-keys`.
4. Create payments on your server with `Payments-Version` and an `Idempotency-Key`.
5. Confirm them in the browser with `@tagadapay/core-js@^3.7.0` (`/payments-v3`).
6. Fulfil orders from your server after reading the payment's `status`.
7. Keep your V2 webhook handlers.

## Not on V3 yet

Stay on V2 for these, or wait:

* A server SDK. `@tagadapay/node-sdk` has no Payments API methods yet.
* Headless SDK support for `next_action`. Version 1.20 keeps paying through V2.
* Sending your own 3DS result.
* Payments API webhooks.


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