Payment Routing

Gatelithix routes each payment to the appropriate payment processor (connector) based on your merchant routing configuration. This page explains how routing works, how to configure it, and how failover protects your transactions.

Routing Model

Each merchant has a routing configuration with two settings:

Field	Description
`default_connector_id`	The primary connector that handles your payments.
`failover_connector_id`	An optional backup connector used when the primary fails.

Routing is config-driven and deterministic — every payment goes to your default connector unless a transport failure triggers failover. Future versions will add ML-optimized routing.

Connector vs. connector account — two-step resolution

As of v2.3, routing is a two-step resolution, not one:

Routing selects the connector — Stripe vs. NMI vs. FluidPay vs. TSYS — based on the merchant’s routing configuration above.
connector_account selects which account of that connector settles the charge. Merchants commonly own more than one account per connector (for example, a US-USD Stripe account and an EU-EUR Stripe account). The request-level connector_account body field (or X-Connector-Account header) picks one; if omitted, the gateway uses the merchant’s default account for the routed (connector, mode, key_kind).

Routing never picks a connector account. Account selection is purely a merchant-level concern once routing has chosen the processor. See Connector Accounts for the full model and Authentication — Selecting a connector account for the request-level override rules.

How Routing Works

When you submit a payment, Gatelithix follows this process:

Request received. The gateway validates your request and authenticates your API key.
Routing config lookup. Your merchant’s routing configuration is loaded, identifying the default connector.
Default connector selected. The payment is sent to your configured default connector (e.g., Stripe, NMI).
If default succeeds: The response is returned immediately.
If default fails with a transport error: The gateway checks for a failover connector.
Failover attempted (if configured). The payment is retried on the failover connector.
Response returned. The final result includes which connector processed the payment.


Payment Request
      |
      v
[Routing Config Lookup]
      |
      v
[Default Connector] --success--> Response
      |
    transport
     error
      |
      v
[Failover Connector?] --yes--> [Retry on Failover] --> Response
      |
      no
      |
      v
    Error Response

Configuring Routing

Set your routing configuration through the dashboard or the API. You need your merchant ID and the connector IDs you want to use.

Routing configuration response:


{
  "merchant_id": "m1234567-89ab-cdef-0123-456789abcdef",
  "default_connector_id": "stripe",
  "failover_connector_id": "nmi",
  "updated_at": "2026-03-18T12:00:00Z"
}

Failover Behavior

Failover is triggered only by transport-level errors — network timeouts, connection refused, or HTTP 5xx from the connector infrastructure. Failover does not trigger on:

Declines. A legitimate decline (insufficient funds, expired card) is a valid connector response, not an error.
Validation errors. Invalid request parameters are returned immediately.
Authentication errors. Credential issues with the connector are returned immediately.

When failover occurs:

The original request is retried on the failover connector using the same idempotency key.
The response includes the failover connector’s ID so you know which processor handled it.
A payment.failover webhook event is emitted (if you have webhook endpoints configured).

If no failover connector is configured, the transport error is returned directly to you.

Supported Connectors

Connector	ID	Description
Stripe	`stripe`	Full-featured payment processing with worldwide coverage.
NMI	`nmi`	Network Merchants Inc. gateway for card-present and card-not-present.
FluidPay	`fluidpay`	Modern payment gateway with developer-friendly APIs.
TSYS (planned)	`tsys`	Transnox REST API — broad acquirer coverage.
Gatelitest	`sandbox`	Built-in mock connector for safe sandbox testing.

Each connector supports the full payment lifecycle (authorize, capture, sale, refund, void). Connector-specific capabilities and limitations are handled internally by the gateway — your integration code stays the same regardless of which connector processes the payment.

Sandbox Routing

When using test API keys (sk_test_):

If your merchant has a routing configuration, sandbox payments are routed to the configured connector’s sandbox environment.
If no routing configuration exists, payments are automatically routed to the Gatelitest mock connector.
Gatelitest provides instant, deterministic responses based on test card numbers. See Sandbox Testing for details.

This means you can start testing immediately without any routing setup.

Next Steps

Sandbox Testing — Test your integration with Gatelitest.
Webhooks — Monitor failover events in real time.
Error Codes — Understand connector error responses.