- TagadaPay switches your store from V2 to the Payments API. Your existing integration does not change.
- You adopt the V3 API for new code, when you want to, and while it is in preview.
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.
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:
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.
When the bank asks for authentication on a one-click
A merchant-initiated charge cannot show 3DS. If it is declined withpayment.error.code: authentication_required, keep the customer on the page.
On the V3 API, the signal is next_step.type: customer_authentication; next_step.payment_method names the same saved card.
- Resend
/payments/processonce withinitiatedBy: 'customer', the samepaymentInstrumentId, areturnUrland a newIdempotency-Key. - If the answer has
requireAction: 'redirect', send the browser torequireActionData.metadata.redirect.redirectUrl. - Read the new payment on return. It may also succeed immediately. Ask for a new card only if this customer payment fails.
requireAction: 'error' as a 3DS request.
If the customer-initiated resend already showed 3DS and then fails with authentication_required, authentication failed. Ask for a new card; do not resend again.
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
What stays
- Stores, products, orders, customers, subscriptions and funnels: the Commerce API.
- Your processors, your dashboard and your payouts.
- Your webhooks (V2).
Checklist
- Ask TagadaPay to switch your store, and wait for the switch.
- Get a secret key for the preview (self-serve keys are coming soon).
- Get the store’s publishable key with
POST /v1/publishable-keys. - Create payments on your server with
Payments-Versionand anIdempotency-Key. - Confirm them in the browser with
@tagadapay/core-js@^3.7.0(/payments-v3). - Fulfil orders from your server after reading the payment’s
status. - Keep your V2 webhook handlers.
Not on V3 yet
Stay on V2 for these, or wait:- A server SDK.
@tagadapay/node-sdkhas 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.
