Workflows

Workflows give you full control over how payments are routed across processors—without writing code. Integrate once, then use the visual builder to update routing logic anytime. Key benefits:

Full control — Decide exactly which processor receives each payment based on any attribute
Flexibility — Update routing rules instantly from the Dashboard, no code deployments needed
Higher acceptance — Implement failover to automatically recover declined payments
Data-driven optimization — A/B test processors and track results to find the best performer

Getting Started

Connect processors

Add at least two processor integrations in Dashboard → Integrations

Create workflow

Go to Dashboard → Workflows and click Create workflow

Add a trigger

Drag Payment Pending onto the canvas and select the payment method (e.g., Cards, Apple Pay)

Build your flow

Add conditions, splits, and actions by dragging components and connecting them

Save and publish

Click Save to create a draft, then Publish to make the workflow live

Building Blocks

Workflows are built from four types of components. You can connect them in any order to create complex routing logic.

Triggers

Triggers start the workflow when an event occurs. Each workflow has exactly one trigger, and each trigger is tied to a specific payment method.

Trigger	Description
Payment Pending	Fires when a new payment is initiated for the selected payment method

Each payment method can only have one workflow. To route Cards and Apple Pay differently, create separate workflows—one for each payment method.

Conditions

Route payments based on attributes. Can be placed at any point in the workflow. Combine multiple rules with AND/OR logic.

Condition	Description
Transaction Type	CIT (customer-initiated) or MIT (merchant-initiated)
BIN	First 6-8 digits of card number
Card Network	Visa, Mastercard, Amex, Discover, etc.
Issuer Country Code	Issuer country
Currency	Payment currency (USD, EUR, etc.)
Issuer Name	Name of the issuing bank
Customer Country	Customer’s billing country
Metadata	Custom metadata from previous workflows or client session
CIT Processor	Processor used for the original CIT payment

Combining rules: Create complex logic by combining conditions:

AND — All conditions in a group must match
OR — Add a new group; payment matches if any group matches

Group 1: Card Network = Visa AND Issuer Country = US
OR
Group 2: Card Network = Mastercard AND Currency = EUR

Condition priority: Conditions are evaluated left to right. Only the first matching condition is executed—subsequent matches are ignored.

Split

Divide traffic by percentage. Can be placed at any point in the workflow.

Example	Use Case
50% / 50%	Distribute traffic evenly between two paths
90% / 10%	Gradual rollout—send most traffic to primary path, test with 10%
33% / 33% / 34%	Distribute across three paths

Use Split to run experiments, distribute load across processors, or gradually roll out routing changes.

Actions

Execute operations on the payment.

Action	Description	Placement
Authorize Payment	Send to a specific processor for authorization	Any point (requires Settle Payment in flow)
Settle Payment	Settle a previously authorized payment	After Authorize Payment
Block Payment	Block the payment (marked as `BLOCKED` status)	Instead of Authorize Payment
Set Metadata	Save key-value data to customer or payment	Any point
Delay	Wait before executing the next action	Between Authorize Payment and Settle Payment

Use Delay for delayed settlement workflows—for example, authorize immediately but settle after 24 hours to allow for order review or fraud checks.

Authorize Payment configuration:

Setting	Description
Primary Merchant Account	Processor to send the authorization request
Fallback Merchant Account	Backup processor if the primary fails (optional)
3D Secure	Authentication mode for card payments

3D Secure options:

Option	Description
No 3DS	Skip 3D Secure authentication
Adaptive 3DS	Apply 3DS based on risk and issuer requirements
Frictionless 3DS	Request frictionless flow when possible

See 3D Secure for details on each mode.

Set Metadata

Save custom key-value data at any point in the workflow. Use metadata to track experiments, enable advanced routing, or record decisions. Configuration:

Field	Description
Key	Metadata field name (required)
Value	Metadata field value
Destination	Save to customer, payment, or both

You can add multiple key-value pairs in a single Set Metadata node.

Use unique keys. If you set the same key twice, the second value overwrites the first. PayNext does not validate key uniqueness.

Example metadata on payment object:

{
  "id": "pay_f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d",
  "metadata": {
    "workflow": {
      "experiment_variant": "variant_b"
    }
  }
}

Using metadata in conditions: For nested metadata (like workflow), use dot notation for the key:

"metadata": {
  "workflow": {
    "experiment_variant": "variant_b"
  }
}

→ Key: workflow.experiment_variant Value: variant_b For flat metadata, use the key directly:

"metadata": {
  "client_tier": "premium"
}

→ Key: client_tier Value: premium Common uses:

Use Case	Example
A/B test tracking	Set `variant: a` or `variant: b` after a split
Routing audit	Record why a processor was selected
Future routing	Tag customers, then route their future payments based on that tag

Common Use Cases

Geographic Routing

Route payments to regional processors for lower cross-border fees and higher acceptance rates.

Automatic Failover

Retry with another processor when the first one fails. Recovers payments that would otherwise be lost to temporary processor issues.

Failover triggers for processor-level failures (technical errors, temporary declines). Card-level declines like insufficient funds are not retried—they would fail at any processor.

A/B Testing

Compare processor performance by splitting traffic and tracking results with metadata.

After collecting data, filter payments by workflow.experiment_variant to compare acceptance rates and costs.

MIT Routing

Route merchant-initiated transactions (renewals, recurring charges) based on the processor that handled the original customer-initiated transaction. Option 1: Use CIT Processor checkbox (recommended) In the Authorize Payment node, tick Use CIT Processor. This automatically routes MITs to the same processor that was used for the first payment—no additional conditions needed. Option 2: Use CIT Processor condition Add a CIT Processor condition to route MITs to a different processor. For example, route all MITs where the original CIT was processed by Processor A to Processor B instead. Option 3: Use metadata For more control, set metadata on the first payment identifying the processor used, then add a condition checking that metadata value for subsequent MITs.

Block Payments

Block payments before they reach a processor based on any condition. Blocked payments are marked with BLOCKED status and never sent for authorization. Common use cases:

Block specific BINs associated with fraud or chargebacks
Block payments from high-risk issuer countries

Use the Block Payment action in your workflow to block payments that match your conditions.

Lists

Lists let you create reusable collections of values to use across workflows. Instead of adding conditions for each blocked BIN individually, create a list and reference it in your workflow conditions. Currently supported list types:

Type	Description
Card BIN	Block or route based on card BIN prefixes

Create a List

Go to Dashboard → Workflows → Lists
Click Create list
Select Card BIN as the list type
Add BINs to the list

List Details

When you add a BIN to a Card BIN list, PayNext automatically enriches it with card details:

Field	Description
Value	The BIN prefix (first 6-8 digits)
Country	Issuer country code
Brand	Card network (Visa, Mastercard, etc.)
Funding	Card funding type (Credit, Debit, Prepaid)
Issuer	Issuing bank name
Author	Team member who added the BIN

Use Lists in Workflows

Reference a list in workflow conditions:

Add a Condition node
Select BIN as the condition type
Choose is in list or is not in list
Select your list

Use lists to maintain a central block list. When you update the list, all workflows using it are automatically updated—no need to edit each workflow individually.

Version History

Workflows support versioning so you can track changes and roll back if needed. Workflow states:

State	Description
Draft	Saved but not live. Edit freely without affecting production.
Published	Currently active. All payments flow through this version.
Previously Published	Archived versions you can preview or restore.

How to publish:

Make changes in the visual editor
Click Save to create a draft
Click Publish to make the workflow live

History tab: View all versions of a workflow in the History tab. For each version, you can see:

Version number and ID
Status (Draft, Published, Previously Published)
Author who published
Date published
Preview button to view the workflow

Workflow Runs

Every payment that reaches a workflow creates a run — a record of each step the payment took, in order, with its outcome. Use runs to see exactly why a payment routed the way it did, without re-tracing the workflow definition by hand.

View all runs

Go to Dashboard → Workflows → Runs. Filter runs by:

Filter	Description
Workflow	Limit to one workflow
Date and time	Limit to a time range
Status	One or more of Completed, Failed, Waiting, Running

The counter row above the table shows totals for Failed, Waiting, Running, and Completed within the current workflow and date filter. Each row shows the run ID, status, workflow, workflow version, trigger, amount, start time, and duration. Click a row to open the run.

From inside a workflow, click See workflow runs to jump to the Runs tab pre-filtered to that workflow.

A payment’s own page also shows the run (or runs) it went through, under Workflow Runs—no need to search the Runs tab for it.

View a run

A run’s page shows:


Workflow	Name and the exact version that executed—not necessarily the workflow’s current version
Trigger	The event that started the run
Started at / Completed at	Timestamps in UTC. Completed at is omitted while the run is still in progress
Duration	Elapsed time, or time elapsed so far if the run is still running
Transaction type	CIT or MIT
Payment method, amount, currency	The payment the run was triggered for
Payment, customer, subscription	Links to the related records, when available

Below that, the Execution path lists every step the run took, in order. Click a step to open its details.

Step details

Every step shows its status (completed, failed, or skipped), start time, and duration. What else appears depends on the step type:

Step type	Shows
Condition	Every route the workflow evaluated, and why each did or didn’t match—see Condition evidence
Authorize / Settle	The processor used and its reference
Block	The decline reason, decline code, advice code, and PSP reference, when available
Set Metadata	The keys written and their destination (customer, payment, or both)
Split	The percentage split and which path the run took
Delay	The wait duration

Failed on a step or run means the workflow itself hit an error—for example, no processor configured. A declined or blocked payment is a normal outcome and still reports as Completed.

Condition evidence

A condition step shows every route the workflow checked, not only the one that matched, so you can see why the others lost too:

The selected route is expanded by default; every other route stays collapsed but can be opened
Each route is labeled Selected, Not selected, or No match
Inside a route, each condition group shows its own outcome, and each field shows the actual value from the payment next to the value the condition expected

Groups within a route combine with OR; fields within a group combine with AND—matching how you build conditions in the canvas.

Sensitive values, like masked card or metadata fields, appear as *** Hidden *** in the evidence instead of the real value.

Best Practices

Start simple

Begin with a default processor and basic failover. Add complex routing after you have payment data to analyze.

Always tag A/B tests

Set metadata when running experiments. Without tags, you can’t analyze results by variant.

Route MITs consistently

In the Authorize Payment node, tick Use CIT Processor to automatically route recurring payments to the processor that was used for the first payment.

Test before publishing

Save as draft first. Review the workflow logic, then publish when ready.

Introduction

Use Cases

Platform

Payments

Fraud Prevention

Advanced Features

Developers

Getting Started

Building Blocks

Triggers

Conditions

Split

Actions

Set Metadata

Common Use Cases

Geographic Routing

Automatic Failover

A/B Testing

MIT Routing

Block Payments

Lists

Create a List

List Details

Use Lists in Workflows

Version History

Workflow Runs

View all runs

View a run

Step details

Condition evidence

Best Practices

​Getting Started

​Building Blocks

​Triggers

​Conditions

​Split

​Actions

​Set Metadata

​Common Use Cases

​Geographic Routing

​Automatic Failover

​A/B Testing

​MIT Routing

​Block Payments

​Lists

​Create a List

​List Details

​Use Lists in Workflows

​Version History

​Workflow Runs

​View all runs

​View a run

​Step details

​Condition evidence

​Best Practices

Getting Started

Building Blocks

Triggers

Conditions

Split

Actions

Set Metadata

Common Use Cases

Geographic Routing

Automatic Failover

A/B Testing

MIT Routing

Block Payments

Lists

Create a List

List Details

Use Lists in Workflows

Version History

Workflow Runs

View all runs

View a run

Step details

Condition evidence

Best Practices