Payment flows for your merchants

A payment flow is the routing rule a charge runs through: which processors to try, in what proportion, in what fallback order, and whether 3DS is enforced. Server-to-server payments explains how a flow is executed at charge time. This page is about the other half — creating and managing flows on behalf of one of your merchants, entirely over the API.

Yes — a partner can create payment flows for a merchant. Verified end-to-end against production: a merchant-scoped key can list, create, update and delete flows for that merchant’s account. The flow you create is owned by the merchant and routes across that merchant’s TPAs.

The direct-merchant guide Multi-PSP Routing & Vault shows a merchant wiring flows across PSPs they connected. As a partner you do the exact same thing, with one difference: each processor in a partner flow is one of the merchant’s TPAs (the Adyen sub-merchant, the Stripe MoR account, etc.) that you provisioned for them.

Which key can manage flows

The payment-flow endpoints are account-scoped and require org:admin. Use a merchant-scoped key, not your raw partner key:

Key	Manages flows?	Why
Processing Key `tp_sk_…` (restricted to a TPA)	✅	Resolves to the TPA’s merchant account as `org:admin`. The same key you charge with.
CRM Key `sk_crm_…`	✅	Account-scoped, `org:admin`.
Partner key `tp_sk_…` (partner-scoped)	❌	Spans many accounts — it can’t resolve a single merchant for an account-scoped call. Mint a merchant-scoped key first.

One merchant-scoped key is enough for all of that merchant’s TPAs. A processing key restricted to one TPA still resolves to the merchant account, so a flow it creates can reference every TPA the merchant owns. You don’t need a key per processor.

Mint a merchant-scoped key with your partner key, then build a fresh client with it:

import Tagada from '@tagadapay/node-sdk';

const partner = new Tagada(process.env.TAGADA_PARTNER_KEY!); // tp_sk_… (partner-scoped)

// Option A — a CRM key for the merchant account
const crmKey = await partner.partners.crm.merchants.keys.create('acc_merchant42');
const merchant = new Tagada(crmKey.token);          // sk_crm_live_…

// Option B — reuse the Processing Key you already charge that merchant with
const merchant2 = new Tagada(process.env.MERCHANT_42_PROCESSING_KEY!); // tp_sk_…

See API keys for the full minting flow.

What’s auto-created with a TPA

Provisioning a TPA doesn’t leave you with nothing — but it doesn’t fully wire a chargeable store either. Here’s exactly what exists, and when:

Entity	Auto-created?	When
Store (`store_…`)	✅ Yes	At TPA creation — for convenience, so you have a `storeId` to charge. It is not bound to the TPA.
Processor (`tagadapay-router`)	✅ Yes	When the TPA goes `active` — one router processor pointing at the TPA.
Payment flow (`"Default"`)	✅ Yes	When the TPA goes `active` — a `simple` flow with that one processor at `weight: 100`.
Store → flow link (`selectedPaymentFlowId`)	❌ No	Never set automatically.

The store and the Default flow are not linked out of the box. A charge by storeId alone will fail with Payment flow ID not found until you either:

pass paymentFlowId explicitly on payments.process (recommended — see Step 3), or
set the store’s default flow in the dashboard → Store → Payments.

This is intentional: one merchant can own several TPAs, so Tagada doesn’t guess which one a store should default to — you decide, per charge or per store.

So the minimum to charge a freshly provisioned TPA is: one storeId + one paymentFlowId (the auto-created Default flow is enough for a single TPA). Create your own cascade/weighted flow only when you want routing across several TPAs.

Step 1 — Find the merchant’s processors

Each TPA shows up as a processor of type tagadapay-router, and the TPA id lives in options.tagadapayAccountId. That’s how you map a TPA to its processor:

const { processors } = await merchant.processors.list();

// The router processor for a specific TPA:
const tpaProcessor = processors.find(
  (p) => p.type === 'tagadapay-router' && p.options?.tagadapayAccountId === 'tpa_xxx',
);
console.log(tpaProcessor?.id); // 'processor_…' → use this in processorConfigs

listWithProcessors is the convenience variant — it returns every processor on the account plus the existing flows in one call:

const { flows, allProcessors } = await merchant.paymentFlows.listWithProcessors();

console.log(allProcessors);
// [
//   { id: 'processor_11737089bcd4', type: 'tagadapay-router', name: 'Adyen sub-merchant' },
//   { id: 'processor_c1a3f4309244', type: 'tagadapay-router', name: 'Stripe MoR' },
// ]

For partner-provisioned merchants the processor type is tagadapay-router — that’s the TPA being routed to. (A merchant who connects their own Stripe/NMI would instead see type: 'stripe', 'nmi', etc.)

Step 2 — Create a flow

Cascade (failover)

Primary TPA first; if it declines (non-terminal), Tagada automatically retries the same charge on the next TPA — no retry code on your side.

const adyen  = 'processor_11737089bcd4';
const stripe = 'processor_c1a3f4309244';

const cascade = await merchant.paymentFlows.create({
  data: {
    name: 'Cascade — Adyen → Stripe',
    strategy: 'cascade',
    fallbackMode: true,
    maxFallbackRetries: 2,
    threeDsEnabled: true,
    stickyProcessorEnabled: true,
    pickProcessorStrategy: 'weighted',
    processorConfigs: [
      { processorId: adyen, weight: 100, disabled: false, nonStickable: false }, // primary
    ],
    fallbackProcessorConfigs: [
      { processorId: stripe, orderIndex: 0 }, // tried if Adyen declines
    ],
    abuseDetectionConfig: null,
  },
});

console.log(cascade.id); // 'flow_…'

Weighted (traffic split)

Send a share of traffic to each TPA. Great for load-balancing or gradually migrating a merchant onto a new acquirer.

const weighted = await merchant.paymentFlows.create({
  data: {
    name: 'Weighted — Adyen 50 / Stripe 50',
    strategy: 'cascade',
    fallbackMode: false,
    maxFallbackRetries: 0,
    threeDsEnabled: true,
    stickyProcessorEnabled: false,
    pickProcessorStrategy: 'weighted',
    processorConfigs: [
      { processorId: adyen,  weight: 50, disabled: false, nonStickable: false },
      { processorId: stripe, weight: 50, disabled: false, nonStickable: false },
    ],
    fallbackProcessorConfigs: [],
    abuseDetectionConfig: null,
  },
});

Field reference

Field	What it does
`strategy`	`'simple'` (one processor) or `'cascade'` (routing + fallback).
`fallbackMode`	If `true`, a declined primary retries the `fallbackProcessorConfigs` in order.
`maxFallbackRetries`	How many fallback TPAs to try before giving up.
`pickProcessorStrategy`	`'weighted'`, `'lowestCapacity'`, or `'automatic'` (round-robin).
`stickyProcessorEnabled`	Returning customers reuse the TPA that last succeeded for them.
`threeDsEnabled`	Enforce 3DS when the issuer requires it.
`processorConfigs`	Primary TPAs + weights.
`fallbackProcessorConfigs`	Backup TPAs, tried in `orderIndex` order on decline.

Step 3 — Use the flow when charging

Pass paymentFlowId to payments.process to route a charge through a specific flow. It overrides the store’s default for that call:

const { payment } = await merchant.payments.process({
  paymentInstrumentId,
  storeId: 'store_xxx',
  paymentFlowId: cascade.id, // ← this charge runs the cascade
  amount: 4999,
  currency: 'EUR',
  returnUrl,
});

payment.processorName;                       // final capturing TPA
payment.transactions?.map((t) => t.status);  // e.g. ['declined', 'captured']

You can omit paymentFlowId only if the store has a default flow set (see the warning above — it isn’t set automatically). Passing it explicitly is the reliable path and lets you keep several flows on one merchant (e.g. a standard cascade and a high-value flow) and pick per charge — exactly like the direct-merchant guide.

Manage existing flows

// List
const flows = await merchant.paymentFlows.list();

// Retrieve one (with processor details resolved)
const flow = await merchant.paymentFlows.retrieveWithProcessors('flow_xxx');

// Update — note: fallbackProcessorConfigs is always required on update
await merchant.paymentFlows.update({
  flowId: 'flow_xxx',
  data: {
    threeDsEnabled: true,
    processorConfigs: [
      { processorId: adyen,  weight: 70, disabled: false, nonStickable: false },
      { processorId: stripe, weight: 30, disabled: false, nonStickable: false },
    ],
    fallbackProcessorConfigs: [{ processorId: stripe, orderIndex: 0 }],
  },
});

// Delete (soft-delete; also clears the flow from any store using it as default)
await merchant.paymentFlows.del('flow_xxx');

See it running

The cascade + weighted flows above are wired in the runnable demo — a picker for single / cascade / weighted, plus a “force the primary to decline” toggle so you can watch the failover happen:

partners-examples/02-merchant-checkout

One merchant, several TPAs, cascade and weighted routing — end to end.

Get Started

CRM provisioning

Processing provisioning

REST reference

Server-to-server payments

Money movement

Reporting & disputes

End-to-end

Payment flows (cascade & weighted)

Payment flows for your merchants

Which key can manage flows

What’s auto-created with a TPA

Step 1 — Find the merchant’s processors

Step 2 — Create a flow

Cascade (failover)

Weighted (traffic split)

Field reference

Step 3 — Use the flow when charging

Manage existing flows

See it running

partners-examples/02-merchant-checkout

​Payment flows for your merchants

​Which key can manage flows

​What’s auto-created with a TPA

​Step 1 — Find the merchant’s processors

​Step 2 — Create a flow

​Cascade (failover)

​Weighted (traffic split)

​Field reference

​Step 3 — Use the flow when charging

​Manage existing flows

​See it running

partners-examples/02-merchant-checkout

Payment flows for your merchants

Which key can manage flows

What’s auto-created with a TPA

Step 1 — Find the merchant’s processors

Step 2 — Create a flow

Cascade (failover)

Weighted (traffic split)

Field reference

Step 3 — Use the flow when charging

Manage existing flows

See it running