Skip to main content
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.

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.
Do not branch your code on the store’s payments version. It is not exposed in V2 responses, and it can change back.

When the bank asks for authentication on a one-click

A merchant-initiated charge cannot show 3DS. If it is declined with payment.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.
  1. Resend /payments/process once with initiatedBy: 'customer', the same paymentInstrumentId, a returnUrl and a new Idempotency-Key.
  2. If the answer has requireAction: 'redirect', send the browser to requireActionData.metadata.redirect.redirectUrl.
  3. Read the new payment on return. It may also succeed immediately. Ask for a new card only if this customer payment fails.
Never treat 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

  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.