> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://academy.zrupay.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Create and manage Orchestrations

# 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](https://academy.zrupay.com/en/article/what-is-a-payment-orchestrator-deamj/).

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

| Block | First payment | Recurring payment | Physical payment | Financing | Alternative method |
|---|---|---|---|---|---|
| Route | ✅ | ✅ | ✅ | ✅ | ✅ |
| Split traffic | ✅ | ✅ | ✅ | ✅ | ✅ |
| Complete payment | ✅ | ✅ | ✅ | ✅ | ✅ |
| Reject payment | ✅ | ✅ | ✅ | ✅ | ✅ |
| Execute 3DS | ✅ | ❌ | ❌ | ❌ | ❌ |
| Create Network Token | ✅ | ✅ | ❌ | ❌ | ❌ |

# 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 (35 total)

**Operation (12):** Price, Currency, Type, Language, Authorize only, MOTO, Partial approval, POS, POS Terminal, Fraud score, Recurring from authorization, Recurring from subscription.

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

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

> 🧐 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. **Financing** and **Alternative method** orchestrations do not offer Card variables either: they resolve to a single payment method, so there is no card to evaluate.

# Notes on blocks

Each block can carry an internal **note** explaining why it is configured that way, so anyone on the team can understand the flow without asking whoever built it.

- To write one, open the block's **"..."** menu and choose **Add note**. The **Notes** window opens: type your text and click **Save**.
- When a block has a note, a button appears in its header that opens it for reading. From that same window you can edit it or remove it with **Delete**.
- In view mode the note can be read but not edited.

> 🧐 Notes are saved as soon as you click **Save**, without publishing the orchestration, and they are not affected by undo/redo. The only exception is a newly added block that has not been published yet: its note is saved when you publish.

> 🧐 It is an internal note: it does not affect routing and is never shown in the checkout.

# 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 12 + Customer 9 + Card 14). 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.