What is an orchestration?

An orchestration is a routing flow that decides which connection handles each payment. You can define different routes based on payment, customer, or card variables, and add alternative connections that kick in if the primary one fails.

To learn more about what payment orchestration is and what it is for, you can read this Academy article.

Before creating an orchestration

• You can orchestrate three different things, depending on the trigger you choose: card processors with each other, financing providers with each other, or the accounts of a single payment method. What you cannot do is route between different methods, for example switching from Bizum to PayPal.
• The connections you want to use must be added and active in Connections. If you have not added them beforehand, they will not appear when you build the orchestration.
• If you are going to orchestrate card processors, the processor cannot be in redirect mode. When adding it in Connections, make sure it shows "No redirect". If it shows "with redirect", the flow leaves Zru and cannot be redirected to another processor.

The orchestrations list

Go to the Orchestrations section in the left side menu. You will see two tabs: Active and Deactivated.

• You can switch between grid view and list view with the toggle in the top right corner.
• The All triggers dropdown filters the list by trigger: First payment, Recurring payment, Physical payment, Financing and Alternative methods.
• In list view, the "..." menu in the table header opens Customize table, where you choose and reorder the columns. It is applied with Apply changes.
• The Export CSV button, in the header next to Create orchestration, downloads the contents of the list.

✋ Export CSV only appears if your role has the Export permission under Environment → Orchestrations. It works the same way as the Connections export permission.

How to create an orchestration?

• Go to the Orchestrations section in the left side menu.
• Click "Create orchestration".
• The canvas editor will open. Enter the orchestration name in the top field.
• Choose the trigger you want this orchestration to fire with (see the next section).
• If you choose Alternative method, the next thing you are asked for is the payment method you are going to route within (see The Method card).
• From there, build the flow by adding blocks from the panel on the right.
• When you are done, click Publish for the changes to take effect.

⚠️ When publishing, changes take effect immediately across all Checkouts using that orchestration.

The canvas: how it works

The orchestration editor is a visual canvas. You can move around it by dragging with the mouse and zoom with the trackpad scroll.

When you open an orchestration you enter view mode, with the flow drawn but not editable. In the header you will find:

• Orchestration activation toggle.
• Last updated date.
• Orchestration name.
• Usage counter: how many Checkouts are using this orchestration.
• Edit button.

When you click Edit you move to editing and the header adds:

• Undo (↶) and redo (↷) buttons.
• Publish button.

🧐 In view mode the delete menus are not offered and the activation toggle cannot be moved. The Edit button only appears if your role has edit permission.

Triggers

When creating an orchestration, the first thing to do is choose the trigger, that is, what type of payment will activate it:

• First payment: payments initiated by the user at checkout.
• Recurring payment: recurring charges from authorizations or subscriptions.
• Physical payment: payments made at a physical terminal (POS).
• Financing: payments settled by a financing provider. It goes straight from the trigger to the action and only lists financing providers.
• Alternative method: routes between the accounts of a single payment method, such as Bizum, PayPal or Klarna.

🧐 The trigger determines which blocks and which connections are available on the canvas. For example, with the "Physical payment" trigger only processors that support card-present payments appear.

✋ Financing and Alternative method route within a single payment method, not between card processors. That is why they do not offer Execute 3DS, Create Network Token or a retry chain: only Route and Split traffic as utilities, and Complete payment or Reject payment as actions. When you choose Complete payment, the account selection opens directly, with no intermediate screen.

The accounts offered in each block depend on the trigger: processors with the card triggers, financing providers with Financing, and connections of the chosen method with Alternative method.

The Method card

It only appears with the Alternative method trigger. It is a card of its own, called Method, placed between the trigger and the first step of the flow.

• When you create the orchestration, the first thing you are asked for is the payment method.
• To change it, click the method on the card: a panel opens with a search box and the list of available methods.
• To remove it, use the card's "..." menu, which offers the delete option.
• From that method onwards, the action blocks only offer accounts of that method.

⚠️ Removing the Method card also removes the trigger and everything you have built below it.

Blocks

Once the trigger is chosen, you build the flow by combining blocks. There are two types: utility blocks (they organize the flow) and action blocks (they execute something on the payment).

Utility blocks:

• Route: splits the flow into branches based on conditions. It works like a switch/case (see the next section).
• Split traffic: distributes traffic between branches at configurable percentages.

Action blocks:

• Complete payment: sends the payment to a connection for processing. Inside the card, + Add fallback adds retry connections that step in if the previous one fails.
• Reject payment: cuts the flow and returns the payment as declined. When configuring it you choose which error you want returned, and the card shows its code and its text.
• Execute 3DS: launches 3D Secure authentication independently from the processor.
• Create Network Token: tokenizes the card with the network scheme before processing.

Not all blocks are available with all triggers:

The Route block

The Route block is the most powerful one in the editor. It is not a simple "if/else": it works as a switch/case, where each condition you add is an independent output branch with its own flow.

When you add a Route block you will see:

• Condition 1, Condition 2...: each one is a branch. You can add as many as you need with the "+ Add condition" button and remove each one with its bin icon.
• All the others: fallback branch that runs when no condition is met. It is always present and cannot be removed.

Within each condition you define the variables the payment must meet to go through that branch. If you add several variables to the same condition, all of them have to be met at once (AND logic).

Available variables in a condition (33 total)

Operation (12): Price, Currency, Type, Language, Authorize only, MOTO, Partial approval, POS, POS Terminal, Fraud score, Recurring authorizations, Recurring subscriptions.

Customer (9): Custom variable, Device type, OS, Browser, IP country, IP region, Country, Region, Email.

Card (12): Brand, Type, Level, Issuing country, Issuing bank, Wallet used, BIN, Network Token, Network Token attempt, Cardholder name, Expiry month, Expiry year.

🧐 The Card category is exclusive to orchestrations. Card data is only known at the moment the payment is processed, not before, which is why this category is not available in Checkouts. The Fraud score is also exclusive to orchestrations for the same reason.

Configuring a connection inside a block

To configure a connection that is already in a block, click directly on it. A panel opens on the right, and what it contains depends on the block and the trigger.

In every case the panel header shows the connection with a Change button to replace it, and a Save button at the bottom.

With Complete payment and a card trigger, the panel is titled "Processor configuration" and has the four sections below. With Financing it only lets you change the connection: there is no 3D Secure, no Network Token, no general condition and no secondary connections, because they do not apply. In Execute 3DS the panel is titled with the block name and also only lets you change the connection.

General condition

It allows that connection to be used only if certain conditions are met (same variables: Operation 10 + Customer 9 + Card 12). When there is none, the section shows "No condition", and you add them with + Add condition. If you do not add any condition, the connection will always be executed.

Secondary connections

It lets you define alternative connections of the same processor that will be used instead of the primary one under certain conditions. You add them with + Add connection.

✋ You can only add connections of the same processor as the primary one. For example, if the primary one is Adyen, the secondary ones also have to be Adyen connections.

This is useful when you have several accounts of the same processor for different markets (Europe, LATAM, US) and you want to use the right account based on IP country or Currency, without having to create separate blocks.

3D Secure

Only available in the Complete payment block.

Choose how you want to apply 3DS authentication on that processor:

• Agnostic: uses the 3DS information already produced by an earlier block ("Execute 3DS") and sends it to the processor, without requesting authentication again.
• Processor: applies 3DS following the decision of the processor and the issuing bank, according to their risk rules.
• Processor (Force 3DS): forces 3DS authentication on all operations, regardless of the amount or the risk.
• No 3DS: does not apply 3DS authentication, although the issuer could request it anyway.

Network Token

Only available in the Complete payment block.

• Use if available: if the card has a network token, it will be used instead of the PAN to process the payment, improving security and the approval rate.
• Do not use: the payment is processed with the original card data, even if a network token is available.

How to edit an orchestration?

• Go to the Orchestrations section in the left side menu.
• Click the orchestration you want to edit. It will open in view mode.
• Click Edit to move to editing.
• Make the changes you need.
• Click Publish for them to take effect.

⚠️ When publishing, changes take effect immediately across all Checkouts using that orchestration.

🧐 If you leave an orchestration with unpublished changes, the panel asks you before you go. Enabling or disabling the orchestration counts as a change, so that is not lost without warning either.

How to enable or disable an orchestration?

From the canvas, use the activation toggle in the header to enable or disable the orchestration. In view mode the toggle cannot be moved: go into Edit first.

You can also do it from the list: in list view, each orchestration shows its status and you can manage it from there.

Updated on: 01/09/2026