Skip to main content

Connecting an External Gateway

This page describes the general flow for connecting any external gateway. Each gateway also has its own page with provider-specific details (see the supported gateways).

Before you start​

For any gateway other than the PaymentsAI Gateway, you bring your own account and credentials. PaymentsAI does not process on external gateways. Processing is handled entirely by the external gateway and its backend processor, where applicable.

VAR sheet:

Some external gateways (such as NMI) require a VAR sheet. PaymentsAI is not the processor for any gateway other than the PaymentsAI Gateway, so it cannot issue VAR sheets for external platforms. These must come directly from that gateway's own processor. PaymentsAI can issue a VAR sheet only for its own gateway upon request. See NMI and Supported Gateways.

General steps​

  1. Open an account with the gateway provider and its backend processor, if required.
  2. Obtain the credentials the gateway requires. These differ per provider (see the gateway's specific documentation page).
  3. In the PaymentsAI dashboard, go to the Gateways tab.
  4. Add the gateway and enter the credentials.
  5. Save the connection.
  6. Test the connection on stage before processing live traffic.

Multiple gateways​

You can connect more than one gateway to the same account. By default, when several gateways are connected, PaymentsAI distributes processing evenly across them (for example, two gateways receive a 50/50 split). PayPal is handled separately because the customer chooses it explicitly at checkout.

To control this distribution instead of leaving it even, PaymentsAI offers two distinct mechanisms. They cannot be combined (see the limitations at the end of this section).

  • Routing rules: Distribute traffic across multiple gateways by weight, based on conditions like region, payment method, or amount.
  • Backup gateway: Automatically fails over to a second gateway when the primary encounters downtime, disruptions, or declines. This option applies to subscription products only.

Routing rules​

Routing rules are configured under Automation Rules → Gateways → Add New Rule.

Each rule has three steps:

  1. Name: A descriptive label for the rule.
  2. Conditions: When the rule applies (for example, if the transaction bank country is in Europe, or based on specific payment methods and transaction amounts). If conditions do not match, the system evaluates the next rule in line.
  3. Weight per gateway: Choose the selection algorithm (Weighted random or Round-robin) and set a weight from 0 to 100 for each applicable gateway.

Backup gateway​

Backup gateway is an automation rule that automatically switches to a second gateway on the next payment attempt when the primary experiences downtime, disruptions, or declines. This prevents failed transactions and keeps recurring payments processing smoothly.

Configured under Automation Rules → Gateways → Backup Gateway → Configure.

Fields:

  • Default gateway: The primary gateway used first.
  • Backup gateway: The gateway used on the next attempt if the primary fails.

Prerequisites:

  • At least two connected gateways that support card payments (for example, the PaymentsAI Gateway and Stripe).
  • Automation Rules enabled (Pro Feature).

Limitations:

  • Subscription products only: Backup gateway does not run for one-time payments.
  • Mutually exclusive with routing rules: Use either backup gateway or other gateway automation/routing rules, not both at the same time.

Pro Feature:

Routing rules and Backup gateway are Pro Features. Enabling Pro Features adds a 0.5% per-transaction fee.

Selecting gateway currencies​

Currencies are configured per gateway. To choose which currencies a gateway accepts:

  1. Go to the Gateways tab in the dashboard.
  2. Click Configure next to the gateway.
  3. Click Edit next to Currencies.
  4. Use the search box to find a currency, then tick its checkbox. Repeat for each currency you want to enable.
  5. Save your changes.

Disconnecting a gateway​

To disconnect a gateway, go to the Gateways tab, find the gateway, and click the red Disconnect button next to it.

Important:

Disconnecting a gateway breaks the active connection. If you have already processed transactions on it, you can no longer refund those charges from inside PaymentsAI; you must issue refunds directly on the gateway's own platform instead.

If your goal is to send future transactions to a different gateway rather than to cut off an existing one, use routing rules instead of disconnecting.

Testing​

Before going live:

  • Confirm both your PaymentsAI account and the gateway are on stage (test mode).
  • Run test transactions and verify they appear with the expected status.
  • See Troubleshooting for common connection errors.