A merchant on WinkPG can hold more than one processor account, including several on the same processor. When you submit a transaction the gateway usually picks the account, and you can name one yourself when you need to choose per sale. This guide explains how the gateway picks, how routing rules and a named profile change that, what happens when the chosen processor doesn't process, and how to read the decision back for a sandbox transaction so you can see the reasoning rather than infer it.

You don't have to configure anything to use routing. A merchant with a single processor account routes to it every time, and everything below still describes what happened.

How a processor is chosen

Routing runs once per transaction, after the gateway has enriched the request and before it authorizes. It works on a candidate list, not a lookup:

1. The candidates are the merchant's active processor profiles, narrowed to those that can service the payment method you sent.
2. A pipeline of rules runs over the list. Each rule can strike a candidate out, or score one up. Rules are the merchant's own configuration expressed as decisions: which card brands a profile accepts, which rail an EBT transaction needs, whether a processor is switched off at the platform level, whether the merchant is pinned to a sandbox processor.
3. The highest-scoring survivor wins, and the transaction authorizes against it.
4. If nothing survives, the gateway may fall back. Some eliminations are advisory and the gateway would rather route than decline: if every candidate was struck out for a reason of that kind, it takes the first active profile anyway. Other eliminations are absolute and are never rescued, so a transaction eliminated only for those reasons is refused instead. A refusal comes back as a ProcessorNotConfigured result rather than as a decline: nothing was sent to a processor.

The reason an elimination is absolute rather than advisory is always a safety one. A merchant pinned to the sandbox simulator must never reach a real processor because something else went wrong, and a processor an operator has switched off must not take traffic because a filter misfired.

Routing rules

A merchant's routing rules choose between its processor profiles by attributes of the transaction in front of them. A rule can match on:

• Card brand, such as Visa or American Express.
• Tender, such as credit and debit, or an EBT rail.
• Amount, as a range the single transaction's amount falls in.
• Channel, the surface the transaction came from, such as the API or the Virtual Terminal.
• Entry mode, how the payment instrument reached the gateway: ManualEntry, PosTerminal, DigitalWallet, StoredPaymentMethod, or AlternativePayment.

Rules run in order, and the first rule that matches sends the transaction to its target profile. A rule whose target can't be used either declines the transaction or lets the next rule try, depending on how it's set. A transaction no rule matches goes to the merchant's default profile.

PosTerminal covers everything captured at a terminal: a chip read, a magnetic stripe read, and a contactless tap. A wallet tap at the terminal arrives as a contactless chip read, so it's PosTerminal too. Only a request that carries a wallet token, or sends entryMode as DigitalWallet, classifies as DigitalWallet. A rule meant for terminal traffic lists PosTerminal alone.

The WinkPG team configures rules for a merchant on request. The endpoint that manages them appears in your API reference only once processor routing is enabled for your environment.

A rule can't move traffic between profiles by volume. It looks at one transaction at a time, never at a running total, so "use this profile until it has taken a set amount, then the next one" isn't something a rule can say.

Several profiles on one processor

Two common reasons a merchant holds more than one profile on the same processor:

• Card-present and card-not-present traffic. A TSYS profile carries one versionId, the developer identifier TSYS sees on every message the profile sends, and terminal and online traffic are registered under different ones: B001 for card-present and B002 for card-not-present. A merchant that takes both holds two TSYS profiles, and a rule with entryModes set to PosTerminal sends terminal sales to the B001 profile while everything else goes to the B002 profile.
• Several merchant accounts on different sponsor banks. A large merchant can hold several TSYS profiles that share a versionId and differ only in merchant ID and terminal ID. A rule chooses between them by transaction attributes, or your integration names the profile for each sale, as described next.

Either way, the transaction is sent with the merchant ID, terminal ID, and versionId of the profile routing chose, and it settles in that profile's batch.

Naming the processor profile for a sale

Send processorProfileId on the create request to choose the profile yourself. The transaction goes to that profile or isn't sent at all: the gateway never substitutes another one. This is how an integration that runs its own allocation between several merchant accounts drives it.

To find the IDs, list the merchant's profiles with GET /api/merchants/{id}/processor-profiles. Every transaction response also reports the profile it used in processorProfileId, so you can confirm the choice landed.

A named profile outranks the merchant's routing rules and its default, and it works whether or not routing rules are in use. Four things refuse it:

• The profile can't take this payment. It isn't one of the merchant's profiles, it's inactive, or it doesn't accept the payment method (card, check, cash, or an alternative payment). The request is refused with 400 Transactions:ProcessorProfileNotEligible, and the response's reason is Missing, Inactive, or PaymentMethod. Nothing is created or charged.
• The request names an original transaction. A transaction that follows an original is sent through the original's profile, so naming one there is refused with a validation error. A capture, void, or reversal always uses the original's profile. A linked refund, a repeat (cardholder-initiated, merchant-initiated, or a resubmission), or a retry of a declined transaction is sent through the original's profile when that profile can still take it, whatever the routing rules or default would choose. When it can't, because the profile has since been switched off or removed or its processor can't be used right now, the transaction is routed normally instead of being refused, and its routing decision records that the original's profile was unavailable. A Force is the exception: it can carry an original transaction's reference alongside its voice authorization code, and it still accepts a profile you name.
• The profile doesn't take the card brand. The brand is known only once the gateway has looked up the card, so this surfaces when the transaction is routed, as a ProcessorNotConfigured result.
• Transaction screening doesn't allow the profile. If a screening rule excludes the profile you named, or requires a different one, the transaction ends as ProcessorNotConfigured. Neither choice wins by substitution.

Leave processorProfileId out and routing chooses as described above.

Failover

If the chosen processor answers that it didn't process the transaction, the gateway re-runs the selection with that processor excluded and authorizes once more on whatever the pipeline picks next.

Four things about this are worth building against:

• It happens once. If the second processor also doesn't process, the transaction ends as a decline. There is no third attempt.
• Only a "didn't process" answer triggers it. A decline, a timeout, or a transport failure is terminal. Those outcomes are ambiguous about whether money moved, and retrying an ambiguous authorization risks charging the cardholder twice, so the gateway doesn't.
• Nothing about the first attempt is persisted. The transaction carries the processor that actually processed it, so a later capture, refund, or void binds to the right one. You won't find a half-written attempt against the excluded processor.
• Follow-up operations never re-route. A capture, refund, reversal, or void always goes to the processor that holds the original authorization. Failover applies to the initial authorization only.

If no fallback survives the exclusion, the transaction is refused with ProcessorNotConfigured rather than declined, for the same reason as above: nothing reached a processor.

A transaction that named its profile with processorProfileId has no fallback: the only profile it may use is the one that didn't process, so it ends as ProcessorNotConfigured.

Sandbox routing

A sandbox merchant carries a processor mode, which decides what its transactions reach:

• Loopback routes every transaction to the built-in simulator. Nothing leaves WinkPG, and the response is whatever the test scenario you triggered says it is. This is the default and is what you want for almost all development.
• Processor Test routes to the merchant's real processor profiles, against those processors' own test hosts. Use it when you are certifying against a specific processor rather than developing against the gateway.

The mode is applied as a routing rule like any other, which is why it shows up in the decision: on a Loopback merchant you will see the real profiles struck out with the reason SandboxProcessorMode, and the loopback profile selected.

Reading the routing decision

For a sandbox transaction, WinkPG keeps the decision and shows it to you. Open Request log in the portal, open the API call that created the transaction, and read the Routing decision section at the bottom of the page.

It shows:

• The verdict, either routed or not routed.
• Every candidate the pipeline considered, in evaluation order, each marked selected, eliminated, or considered. An eliminated candidate carries the reason it was struck out, as a stable reason name such as SandboxProcessorMode, PaymentTypeNotSupported, ProcessorDisabled, LoopbackOutsideSandbox, or ExplicitProfileOverride (the request named a different profile).
• What each rule recorded, in the order the rules ran. A request that named its profile shows an ExplicitProfileOverride step first.

A candidate can be marked both selected and eliminated. That's the fallback described above: nothing survived, and the gateway routed anyway rather than refusing the payment.

Four limits to know before you build a habit around it:

• Sandbox only. Production transactions carry no routing decision, by design. This is a development aid, not a reporting surface.
• It's kept for a limited period. Decisions are pruned after a retention window, so an older sandbox transaction shows nothing. That's ordinary, not a fault.
• It isn't in the API response. The decision is a portal surface. Your integration shouldn't depend on reading it, and nothing about it forms part of the API contract.
• It names processors, not profiles. You see which processor a candidate was configured for and never the internal identifier of the merchant's profile. When a merchant holds two profiles on one processor, the position column is what tells the two rows apart.

Exercising failover

The quickest way to see all of this is the Exercise processor failover blueprint, which sets up a merchant with two processor profiles where the first refuses to process, and runs both outcomes: the fallback approving, and the fallback exhausted. Run it, then open the request log entry for each transaction and compare the two routing decisions.

The sandbox testing guide lists the other simulator triggers you can combine with it, including the declines and host errors that aren't failover-eligible, which is a useful thing to confirm for yourself.

What to build against

Most integrations leave routing to the gateway. Send processorProfileId only when you're choosing between a merchant's profiles yourself, don't infer a profile from a previous transaction's routing, and don't treat the routing decision as an API contract.

Three outcomes are worth handling explicitly:

• ProcessorNotConfigured means the gateway had nowhere to send the transaction. It's a configuration problem on the merchant, not a payment failure, and retrying the same request unchanged won't help. Surface it differently from a decline.
• Transactions:ProcessorProfileNotEligible means the profile you named can't take this payment. Read the reason, then name another profile or leave the field out.
• A decline after failover looks exactly like any other decline. There is no field that says a second processor was tried, and your handling shouldn't depend on one.