Routing & Cascading in PayStar: business use cases and setup

1) What Routing & Cascading gives you

Routing & Cascading is a “traffic management engine” that allows you to:

Improve conversion: route payments to where approval/velocity/quality is higher.

Meet PSP requirements: limits by attempts, volume, and traffic quality.

Reduce risk: quotas for “untrusted” PSPs, turnover caps, piloting.

Increase resilience: fallback during degradation, processing/failed growth, quick channel disabling without rewriting the integration.

Segment traffic: FTD/STD, product storefronts, time, amounts, currency, issuer, etc.

2) Top use cases (ready recipes)

Anti-spam: the PSP doesn’t want “spam” from unsuccessful attempts

The PSP accepts a user no more than 3 times per day

The PSP accepts a user for 5,000 USD per week

Traffic split: FTD (primary) vs STD (repeat)

Overlapping amount ranges across PSPs (50–500 and 100–700)

PSP degradation: processing/failed is growing

“Untrusted” PSP: limit by quota/turnover

Piloting a PSP on a segment

3) Where this is configured in the UI

3.1 Merchants section

3.2 Merchant card and pipelines list

4) Condition builder: Add pipeline condition (field table + examples)

Why it’s needed: you define a “selection rule” (condition) that determines which branch/route a payment will go to.

4.1 Condition fields (Attribute / Operation / Value)

Field	What it is	How to fill it	Example
Attribute	What we check (amount, currency, time, issuer, etc.)	Select from the list (see table below)	`Payment amount`
Operation	How we compare	`>`, `>=`, `<`, `<=`, `==`, `!=`, ranges `(a-b)` / `[a-b]`	`<=`
Value	Threshold/value for comparison	Depends on Attribute: number, currency code, range, time window	`500`

4.2 Attribute: available parameters (with explanation and example)

Attribute (UI)	Meaning	Value format	Typical business use case	Example condition
Payment amount	Current payment amount	Number (major units) or range	Split PSPs by amount ranges	`Payment amount` `>=` `100`
Payment currency	Payment currency	ISO code: `USD`, `EUR`, `INR`, etc.	Different PSPs for different currencies	`Payment currency` `==` `USD`
Payment created at — time	Time-of-day window	Time/range (as in UI)	“Day/night” provider, time-based SLA	`time` in range `10:00–17:00`
Payment created at — day, time	Date+time window	Two timestamps (as in UI)	Promo period / pilot on specific dates	`2026-01-01 10:00 … 2026-01-30 17:00`
Product code	Product/storefront code sent by the merchant	String	Split traffic by products	`Product code` `==` `CASINO`
Card issued bank	Card issuer bank	String/enum (as in UI)	PSP-A performs better for a specific issuer	`Card issued bank` `==` `HDFC`
Card issued payments processing	Card scheme (processing)	Enum/string (as in UI)	Different PSPs for Visa/Mastercard	`processing` `==` `VISA`
Card issued country	Card issuer country	Country ISO code / enum	GEO rules by issuer country	`country` `==` `IN`
Telecom operator	Telecom operator (carrier)	String/enum	Rules for mobile scenarios/methods	`operator` `==` `Airtel`
Payment details	Payment history condition (aggregation)	Separate form (see section 5)	Anti-spam, attempt/volume limits, FTD/STD	`CountUnSuccess >= 3 for 1 hour`

Note on time: Payment created at — time / day, time conditions are applied in the organization/team timezone.

4.3 Operation: available comparison operations (with examples)

Operation	Meaning	Example (amount)	When to use
`>`	strictly greater than	`amount > 500`	VIP/high-value branch
`>=`	greater than or equal	`amount >= 100`	minimum threshold
`<`	strictly less than	`amount < 100`	micro-payments
`<=`	less than or equal	`amount <= 500`	upper limit
`==`	equals	`currency == USD`	exact match
`!=`	not equals	`currency != EUR`	exclusion
`(a-b)`	between, excluding bounds	`amount (100-500)`	when bounds must be excluded
`[a-b]`	between, including bounds	`amount [100-500]`	when bounds must be included

4.4 Example of a “simple” rule (without history)

Case: PSP-A works for amounts 50–500, PSP-B for 100–700.
Solution: create branches by Payment amount, and add a cascade in the overlap.

Example branches:

amount < 100 → PSP-A

100 <= amount <= 500 → PSP-A → PSP-B

amount > 500 → PSP-B

5) Payment details (history aggregation): detailed field table + examples

Why it’s needed: “look back” and make a business decision based on payer history: anti-spam, attempt limits, volume limits, FTD/STD.

5.1 Payment details fields (each field in plain words)

Field	Meaning (plain words)	Format/values	Example
Aggregation type (`aggregationType`)	What exactly we calculate over history	`Count` or `Sum` (see table below)	`CountUnSuccess`
Property (`property`)	Which “key” to group history by (who we consider the same payer)	`payeerIdentifier`, `email`, `ip`, `cardToken`, `phoneNumber`, …	`payeerIdentifier`
Period (`periodSeconds`)	How far back to look	Seconds or a human-readable choice in UI	`3600` (1 hour)
Direction type (`directionType`)	Which operations to include	`Deposit`, `Withdrawal`, `Inherit`	`Deposit`
Entity type (`entityType`)	Where to search for history	`Pipeline` (current only) or `Partner` (all partner pipelines)	`Partner`
Operation (`operation`)	How to compare the metric to the threshold	`>`, `>=`, `<`, `<=`, `==`, `!=`, range	`>=`
Value (`value`)	Threshold value	For `Count` — number of attempts; for `Sum` — amount	`3`

Important:

the current payment is not included in the calculation;

if there is no history, the metric is 0.

5.2 Aggregation type: what each metric means

aggregationType	What it counts	Plain explanation	Example use case
`CountTotal`	Count of all (success + failed + processing)	“How many times they tried to pay”	daily attempt cap
`CountSuccess`	Count of successful	“How many times it worked”	FTD/STD, trust level
`CountFailed`	Count of failed	“How many explicit declines”	anti-retry by declines
`CountUnSuccess`	failed + processing	“How many did not reach success”	anti-spam + catching “hangs”
`SumTotal`	Sum of all	“Total turnover (any statuses)”	rare scenario
`SumSuccess`	Sum of successful	“How much actually went through”	5,000 USD/week cap
`SumFailed`	Sum of failed	“How much failed by amount”	risk rules
`SumUnSuccess`	Sum of failed + processing	“How much is stuck/unsuccessful by amount”	degradation/risk

6) Webhooks: Callbacks

Key points:

callbackUrl can be passed dynamically in the request (it has priority over the static one);

callbacks are not sent “retroactively” if URL/events were not configured in advance;

retries use Fibonacci backoff with a 7-minute step, up to ~27 hours.

you can configure notification types: status change (created, processing, success, failed) and payment amount change (relevant in some cases)

Callbeck tech doc

https://apidoc.paystar.uk/callbacks

:

7) Integration: Keys, Required fields, cURL example

7.1 Keys

Key points:

opened in a modal by clicking the “lock” icon in the pipeline row;

you can regenerate — old keys will stop working;

you can build the token from keys yourself or use the ready-made token.

API Key tech doc

https://apidoc.paystar.uk/authorization

7.2 Required fields

Key points:

the exact list of required fields depends on the pipeline settings — in practice, it is a superposition of fields requested by banks and payment gateways within this pipeline;

required fields are passed in the request body in the Additional Fields field.

Additional Fields tech doc

https://apidoc.paystar.uk/additionalfields

7.3 cURL example

Key points:

to simplify integration, you can get an example of a ready-made request with required fields already assembled and an authorization token included.

8) Troubleshooting

8.1 The payment doesn’t go through due to rules/limits

Typically, HTTP 423 is returned — this means that, under the current rules/constraints, the payment cannot be routed or is blocked by policy.

9) Best practices (quick)

Always keep an alternative branch for fallback.

For anti-spam and degradations, CountUnSuccess is convenient.

For FTD/STD, use CountSuccess == 0.

For a pilot, segment by amount/time/FTD or use a separate Pilot pipeline.

For Sum* rules, avoid mixing currencies.

Routing & Cascading

1) What Routing & Cascading gives you#

2) Top use cases (ready recipes)#

3) Where this is configured in the UI#

3.1 Merchants section#

3.2 Merchant card and pipelines list#

4) Condition builder: Add pipeline condition (field table + examples)#

4.1 Condition fields (Attribute / Operation / Value)#

4.2 Attribute: available parameters (with explanation and example)#

4.3 Operation: available comparison operations (with examples)#

#

4.4 Example of a “simple” rule (without history)#

5) Payment details (history aggregation): detailed field table + examples#

5.1 Payment details fields (each field in plain words)#

5.2 Aggregation type: what each metric means#

6) Webhooks: Callbacks#

:#

7) Integration: Keys, Required fields, cURL example#

7.1 Keys#

7.2 Required fields#

7.3 cURL example#

#

8) Troubleshooting#

8.1 The payment doesn’t go through due to rules/limits#

9) Best practices (quick)#

1) What Routing & Cascading gives you

2) Top use cases (ready recipes)

3) Where this is configured in the UI

3.1 Merchants section

3.2 Merchant card and pipelines list

4) Condition builder: Add pipeline condition (field table + examples)

4.1 Condition fields (Attribute / Operation / Value)

4.2 Attribute: available parameters (with explanation and example)

4.3 Operation: available comparison operations (with examples)

4.4 Example of a “simple” rule (without history)

5) Payment details (history aggregation): detailed field table + examples

5.1 Payment details fields (each field in plain words)

5.2 Aggregation type: what each metric means

6) Webhooks: Callbacks

:

7) Integration: Keys, Required fields, cURL example

7.1 Keys

7.2 Required fields

7.3 cURL example

8) Troubleshooting

8.1 The payment doesn’t go through due to rules/limits

9) Best practices (quick)