Patterns

Routing provider card

The provider node on the Routing flow canvas. It represents ONE provider (acquirer / PSP) that processes the payment and is the base block of the routing graph — the next steps of the route chain off its outputs (a waterfall / cascade). A header (provider logo + connection name + an optional Set rules and lists) sits over a list of outputs: one row per result, each with a status icon and a connection point.

Updated Aug 4, 2026 by Juan Pablo Turina

Live preview

CybersourceCybersource test 1 fx

Authorized

All other declines

Error

import {
  RoutingProviderCard,
  RoutingProviderCardHeader,
  RoutingProviderCardOutputs,
  RoutingProviderCardOutput,
} from "@/components/patterns/routing-provider-card";

<RoutingProviderCard warning>
  <RoutingProviderCardHeader
    logo={cybersourceLogo}
    name="Cybersource"
    subtitle="Cybersource test 1 fx"
    onConfig={openRules}
    onMenu={openMenu}
  />
  <RoutingProviderCardOutputs>
    {/* Authorized first → declines → Error last */}
    <RoutingProviderCardOutput status="success" label="Authorized" retry="removable" />
    <RoutingProviderCardOutput status="decline" label="All other declines" />
    <RoutingProviderCardOutput status="error" label="Error" />
  </RoutingProviderCardOutputs>
</RoutingProviderCard>

Anatomy

A fixed-width canvas card (216px, rounded-xl, shadow-sm). A white header — the provider logo, name + connection subtitle, an optional Set rules and lists button, a top-right icon stack (menu / edit / add to list) and a single top-left warning — over a muted outputs section. Each output row carries a status icon, its copy, and a connector handle that sticks out the right edge.

CybersourceCybersource test 1 fx

Authorized

All other declines

Error

1
Provider logo
40px provider brand logo at the top of the header.
2
Name + connection
Provider name (text-base semibold) with the connection name / id below it.
3
Set rules and lists
Optional outline button that opens the provider's rules & lists configuration.
4
Icon stack
Top-right menu (kebab) / edit / add-to-list actions. The node menu must portal so a neighbouring card can't clip it.
5
Warning / badge
A single top-left warning triangle when the node needs attention, OR a traffic / split badge (e.g. 1%, Smart Routing).
6
Output row
One row per result: a status icon + the output copy + a connector handle on the right edge.

Outputs — the routing logic

The outputs are NOT a fixed list — they come from the step's outputs[]. Each row is a status + icon + a connection point that defines the `next` step; a row whose connector is not active is a terminal branch and must read as one. Semantic order: Authorized first → declines (named groups, then the 'All other declines' catch-all LAST) → Error last. Statuses map to the DS output states: Authorized → success (green check); a decline group or 'All other declines' → decline (no-entry); a technical failure / timeout → error (red); an async hold → pending (blue).

CybersourceCybersource test 1 fx

Authorized

High-risk BIN

All other declines

Error

Elements & states

The card is composed from three individual elements — the connector handle, the auto-retry chip and the output row. Each is exported and reusable on its own.

Connector (action)

The connection point on an output. active (primary caret), disabled (muted), or block (minus). Add step chains off it; a non-active connector marks a terminal branch.

Retry chip

The auto-retry affordance on an output: on, or removable (with an X). Hover shows an Auto-retry enabled tooltip.

Output row (provider states)

One result row. Four DS statuses drive the icon + colour: success (green check), pending (blue no-entry), decline (no-entry), error (red).

Success

Pending

Decline

Error

Import

Copy this import line at the top of the file where you compose this molecule.

Compose the card from its parts: a RoutingProviderCardHeader over a RoutingProviderCardOutputs list of RoutingProviderCardOutput rows. The connector and retry render inside the row via props; RoutingConnector / RoutingRetry are also exported for standalone use.

import { RoutingProviderCard, RoutingProviderCardHeader, RoutingProviderCardOutputs, RoutingProviderCardOutput } from "@/components/patterns/routing-provider-card";

Props

The card is a shell + overlays; the header and each output row carry their own props.

RoutingProviderCard

Prop	Type	Default	Description
warning	boolean	—	Single top-left validation triangle. A node surfaces at most one warning.
trafficAlert	string	—	Traffic / split badge, e.g. '1%' or 'Smart Routing'. Omit to hide.
children	ReactNode	—	The header + outputs.
className	string	—	Merged onto the card shell.

RoutingProviderCardHeader

Prop	Type	Default	Description
name	string	—	Provider name (text-base semibold).
subtitle	string	—	Connection name / id below the name.
logo	string \| ReactNode	—	Provider logo — a URL (40px square) or a custom node.
onConfig	() => void	—	Renders the 'Set rules and lists' outline button.
onMenu / onEdit / onAddToList	() => void	—	Top-right icon stack — each renders only when set. Portal the menu.

RoutingProviderCardOutput

Prop	Type	Default	Description
status	'success' \| 'pending' \| 'decline' \| 'error'	—	Drives the leading icon + colour (Figma 'Provider states').
label	string	—	Output copy: 'Authorized', 'All other declines', 'Error', or a group name.
connector	'active' \| 'disabled' \| 'block' \| 'none'	'active'	The right-edge handle. Non-active = terminal branch.
expandable	boolean	—	Show the expand caret (drills into sub-config).
retry	'off' \| 'on' \| 'removable'	'off'	Auto-retry chip; 'removable' adds an X.
onConnect / onExpand / onRetryRemove	() => void	—	Row action handlers.

RoutingConnector · RoutingRetry

Prop	Type	Default	Description
RoutingConnector.state	'active' \| 'disabled' \| 'block'	'active'	The connector handle state.
RoutingRetry.removable	boolean	—	Add the X to remove auto-retry.
RoutingRetry.label	string	'Auto-retry enabled'	Tooltip copy.

When to use

When a merchant adds a payment provider to a routing condition (Add step on a branch).
To process, fall back / cascade, or split traffic across providers (% split or Smart Routing).
As the chaining point — the next steps of the route are added from its outputs.

When not to use

For fraud / 3DS / auth checks — that is the Risk Profile / Risk Conditions node.
For the capture action — that is the Capture card, chained on the Authorized output.
To represent a condition — that is the condition-set card.

Usage

One provider per card — represent multi-provider splits with a % per card or the Smart Routing badge, never two providers in one card.
Order outputs Authorized → declines → Error, and keep 'All other declines' last among the declines.
Treat every output as a connection point; a branch with no connection is terminal and must read as such.
Surface at most one warning per node, paired with a one-line why (e.g. nothing can follow a Pending).

Don't

Don't leave a dead-end without a why — explain why an output can't chain (async method with no Declined branch, a Redirect provider that doesn't route declines…).
Don't offer Capture outside the Authorized output (and only for the card method).
Don't publish a decline group with no valid id, a paused provider with no fallback, or Smart-Routing-by-cost with no costs configured — the card should flag these.
Don't let the node menu get clipped by a neighbouring card — portal it, and keep it keyboard + screen-reader accessible.

Cross-links to the atoms this molecule composes and sibling patterns.

Routing cardThe provider card for the routing LIST screen (not the canvas node).
Connection cardThe provider card for the Connections screen.
TooltipThe Auto-retry enabled hint on the retry chip.
ButtonThe Set rules and lists action in the header.