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
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 only

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

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

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

Best Practices

Introduction

Use Cases

Platform

Payments

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

​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

Best Practices