Rotating Transaction Gateway


Rotating transaction gateways allow a merchant to spread credit card transactions across multiple gateways. While available to all UltraCart merchants, it is primarily intended for merchants with substantial transaction volume. Merchants should thoroughly test their configuration before going live with this feature.


Home → Configuration (Checkout) → Payments →  ("Debit and Credit Cards" section) → Multiple (rotating) gateways


Warning Message

When you navigate to the to the rotating gateways tab you will see a a message at the top of the page alerting you to the fact that you must migrate
the existing gateway in order to properly configure rotating gateways:

If you see the above  warning  about existing configuration under the transaction gateways tab, use the migration wizard located at the bottom of the page (other wise navigate to the transaction gateways configuration page and carefully copy and paste the credentials into notepad or text editor then manually un-configure the gateway there (unselect its checkbox then scroll down and click the save button.) Then navigate back to rotating gateways and click new then configured the gateway with the credentials you previously saved in the notepad/text editor.

Refunds for order processed prior to Rotating Gateway configuration

The migration tool will set a merchant property called "defaultRefundRtgCode" which will be used to initiate a refund on an order if the order does not have an RTG code assigned to it.  So refunds should work against the old migrated gateway.

Configuring a New Rotating Gateway

Rotating Gateway Editor

In this section, you will enter some basic information about this transaction gateway.


Each rotating transaction gateway requires a unique code. It is recommended that you use a code that will allow you to quickly identify either the gateway or merchant account

Traffic %

Enter the desired traffic percentage you want this gateway to receive. If there are other restrictions (as discussed below) on this gateway, then UltraCart will resolve those restrictions, then compare the relative percentages across all gateways that qualify to handle the transaction

100% MAX

The total traffic percentage among all configured gateways should not exceed 100%.


Each rotating transaction gateway can be placed in one of three states:

  • Active - The default status, this indicates that the gateway is ready to receive transactions. If an active gateway experiences a certain number of consecutive failures (configured below), it will be marked as inactive.
  • Inactive - When marked inactive, this gateway will not receive any new transactions.
  • Stand-by- A stand-by transaction gateway will only receive transactions if there are no active gateways.

    If all configured gateways are marked as inactive, then UltraCart will attempt to route the transaction through any configured gateway, regardless of status, rather than simply failing

Deactivate after X consecutive failures

(Optional) If specified, UltraCart will automatically place this gateway into inactive status if the specified number of consecutive failures are encountered.

Charges Appears On Statement As

(Optional) If this gateway has a different Charges Appear On Statement message than your store's default, then this value will be used for transactions conducted through this rotating transaction gateway

Customer Service Email

(Optional) If this gateway has a different Customer Service email address than your store's default, then this value will be used for transactions conducted through this rotating transaction gateway

Customer Service Phone

(Optional) If this gateway has a different Customer Service phone number than your store's default, then this value will be used for transactions conducted through this rotating transaction gateway

If Charge Declines Try Other RTG

(Optional) If selected, then during a checkout, if the initial transaction is declined, attempt the next credit card authorization against the configured rotating gateway.


Select the gateway vendor from the list provided. Each gateway has different required information about your account. When you select a vendor, the vendor-specific fields will appear. This section behaves in an identical fashion as the Transaction Gateways tab, which is documented on this wiki in further detail.

Monthly Restrictions

Some merchant accounts have strict limits regarding the maximum monetary volume permitted each month. If the merchant account associated with this transaction gateway has such restrictions, this section will allow you to specify them to UltraCart.

Maximum Monthly

The maximum monetary volume that is permitted by this merchant account

Current Monthly

The current monetary volume processed through this merchant account. UltraCart will automatically keep this field up to date

Reset Monthly at X EST

Enter the date and time the next reset will occur for this merchant account. UltraCart will automatically update this field each month to the correct date

Important Note Concerning The Handling Of Limits

Limit Override

PLEASE NOTE: If you configure each rotating gateway with a Maximum limit and the limit is reached for each gateway, then ultracart will randomly pick one of the gateways to attempt to authorization. Whether or not the gateway authorizes the payment is up to the gateway. If the gateway rejects the transactions, then the order will be captired after the number of failed attempts configured in the credit and debit card settings is reached (the default is 3 attempts.)

Configuring Restrictions

Monthly Restrictions

Daily Restrictions

Daily Auto Order Restrictions

Date Restrictions

You can restrict each transaction gateway to only be allowed on specific dates, or specific days of the week, or days of the month. One common use of this feature is to alternate traffic between multiple gateways throughout the week. You can specify any of the options in this section, but the transaction date must match all of the selected rules in order to be deemed valid for use.

Date Between X and Y

Only allow transactions to be processed by this gateway if the transaction occurs within the specified date range. This is frequently used if a merchant is testing a new gateway provider or merchant account

Only on Day of Week

Only allow transactions to be processed by this gateway if the transaction occurs on one of the specified days of the week.

Only on Day of Month

Only allow transactions to be processed by this gateway if the transaction occurs on the specified day of the month

We have no idea of a practical use for this restriction. If you have any suggestions, please post them on our forums!

Storefront Screen Branding Theme Restriction

Use the "Invalid For" & "Valid For" columns to configure the available storefront/SB themes that are valid for the rotating gateway. 

Please Note: IF you have only one valid theme, you can use the Valid only For".

Total Restrictions

The total restriction allows you to limit this rotating gateway from processing transactions where the total matches a certain criteria.  For instance if your merchant account provider has approved transaction up to $100 then you could set the total restriction to <= $100 so only those transactions would be processed on this gateway.

Per-Transaction Restrictions

UltraCart can restrict a gateway to transactions whose total matches a certain criteria. For example, if the merchant account provider associated has only approved transactions up to $100, you could set this restriction to be "≤ $100"

To use this feature, first you need to select the comparison type to use.


Total must be below the specified value

Total must be below or exactly equal to the specified value


Total must exactly equal the specified value

Total must be exactly equal to or higher than the specified value


Total must be higher than the specified value

Next, simply enter the desired transaction total amount.

Trial Restrictions

UltraCart considers a trial to be "the first item that is purchased in an auto order sequence". Some merchants need to limit the number of transactions sent to a particular gateway in a given day or month to ensure that number of received chargebacks don't cross Visa / MasterCard thresholds. You can set a daily, monthly or both limits if you would like. Once configured, you can activate the "Rotating Transaction Gateway" notification on one of more of the users on your account from the Email Notifications section of the User configuration screen. When the gateway reaches this limit, UltraCart will send a notification email to those users.

Daily Trial Limit

The maximum number of transactions permitted through this gateway per day

Daily Trial Current Count

The number of transactions processed through this gateway on the current day

Monthly Trial Limit

The maximum number of transactions permitted through this gateway per month

Monthly Trial Current Count

The number of transactions processed through this gateway during the current month

Payment Process Reserve tracking

UltraCart can help you judge the profitability of ongoing free trial campaigns by keeping track of whether the reserves associated with an order have been released or not. If you payment processor withholds a percentage of your transactions for a certain time period you can configure that information here. On the auto order profit report UltraCart  will automatically determine your profitability based upon whether the reserves have been released or not. This will help you to maintain campaigns that are always cash flow positive.

Reserve PercentageSet your reserve percentages as established with your merchant account/ gateway provider.
Reserves Released ThroughSet date in following format: MM/DD/YYYY
Reserve DaysConfigure the number of days reserves are held.
Reserves Returned on RefundTracking reserves related to refunded orders.

Applying specific rotating gateway to specific items

There are two option for overriding the default rotating gateway behavior and assigning a specific rotating gateway to be used with a specific item:

  1. Using buy link parameter RtgCode which sets the specific rotating transaction gateway that should be used to process this order.

    Example assigned Rotating Gateway Code of "Auth3.1"
    On the "Buy Link" URL: 
    In "Buy Form" code:      <input type="hidden" name="rtgCode" value="Auth3.1" />
  2. Configuring the rotating gateway via the "Payment Settings" section of the "Other" tab of the item editor:

    Home → Store (Items) → Edit Item → Other (Tab) → Payment Settings

    Applying RTG to a buy link

    You can append the following to the buy link to specify a specific rotating gateway:

    &RtgCode=DFLT (replace DFLT with the actual code you gave your rotating gateway.)

    NOTE: IF you use this approach you'll need to make sure that all the items that the customer is placing into their cart ar assigned the same rotating gateway code. If the customer adds items to their cart that are assigned different RTG's the cart will randomly choose one of the RTG's to process the order.

Frequently Asked Questions

Q: One of our gateways charges less to process AMEX transactions than the other. If I turn off AMEX under the one that charges more, will UltraCart route the transactions to the one that charges less?

A: Yes, when UltraCart selects the gateway to use it considers which ones handle the specific method. You could conceivably have only one gateway that handles AMEX.

Q: What if I want to fill up one rotating gateways trial limit before using another one?

A: Typically you configure which product is using a particular rotating gateway on the "other" tab of the item editor. You can also configure the priority that the rotating transaction gateways are used in. So if you set priority of 1 and then 2 on two rotating transaction gateways with trial limits it will fill up the first one completely before rotating to the second gateway.

Q: We have multiple gateways and one gateway is never getting any transactions process through it. We do not have any gateways configured at the item level and we are only using a simple traffic percentage (along with cascade on decline). What would be the reason for the one gateway being skipped?

A: If a gateway fails the credential handshake, UltraCart will automatically choose one of the other configured gateways for subsequent transactions. So the first thing you will want to do is verify that the gateway credentials are accurate and active. Some gateways, like, will automatically expire the "Transaction Key" 24 hours after a new transaction key is generated. So, if in testing it appears not to be working , you may need to go back in there and review the active transaction key and potentially generate a new one.

Q: I wish to configure rotating gateways with the PayPal Payments Pro ("Direct Payments") are there any special precautions using this gateway in a rotating gateways configuration?

A: Yes. Specifically, the migration tool with NOT work IF you initially configured paypal settings using the "3rd Party" API credentials. You'll need to use the "First Party" credentials in the rotating gateways configuration. Log into your PayPal account and gather the 1st party API credentials (write down the "API Username", " API Password & "Signature" credentials.) Then navigate to the "Multiple (Rotating) gateways" configuration page and then click the new button and fill out the top section of the editor with a RTG code, then set as "Active" then configure the traffic percentage as 100.00%. After configuring the PayPal Payments Pro gateway, navigate back to the payments configuration page and in the PayPal section click settings and change the "Integration type" from " Payments Pro (Express Checkout and Direct Payments)" to "Express Checkout" then save the changes. (That changes allows the rotating gateways configuration to handle the credit card processing. Finally, add the secondary gateway(s) into the Multiple (rotating) gateways configuration page. 

Q: We have auto orders - what is the best process of migrating from our existing rotating gateways to a new gateway that will take over all of the payment processing moving forward? 

A: The safest path to migrating from existing rotating gateways to a new gateway will be to plan for an overlap of approximately 60 days between the activation of the new gateway and any potential termination of the existing accounts. The overlap will allow you to perform refunds for authorizations that occurred with the gateway(s) you will be removing from the rotating gateways configuration. IF you remove a gateway that processed the original transaction for an order, you will no longer be able to process a refund for that order within UltraCart (you can update the order to reflect the refund you would have processed directly within the gateway website. Please Note: You must make sure to configure the new gateway being added to your rotating gateways so that it can process the auto order rebills without the CVV number. You must configure the CVV rules within the gateway website. Enable the rule to decline on a mis-match, but do not enable the rule to decline "if missing" or "unavailable".