Rotating Transaction Gateway
- Perry Tew
- Hunter Schaeffer
- Jonathan Tew
Introduction
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.
Navigation
Home → Configuration (Checkout) → Payments → ("Debit and Credit Cards" section) → Multiple (rotating) gateways
Configuration
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.
Code | 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 Important Note Regarding Traffic Percentage Configuration100% MAX The total traffic percentage among all configured gateways should in most cases equal 100%. However, UltraCart will normalize the sum of the traffic percentages for the RTGs being considered based upon all the other restrictions that can be applied. So, the normalization will spread the traffic evenly among the active gateways. |
Status | Each rotating transaction gateway can be placed in one of three states:
|
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. |
| Rebill Auto Order against RTG | (Optional) If set, any auto orders originally process with this gateway will have its rebills processed with the selected gateway. |
| Require CVV2 | (Optional) This force the gateway to require the CVV2. Setting this will mean that auto orders would not be processed with this gateway. |
| Preferred for Auto Orders | (Optional) When checked, this gateway will be preferred over others is the transaction is related to an auto order. This can be used to shift traffic towards gateways that have card updating services. |
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 captured after the number of failed attempts configured in the credit and debit card settings is reached (the default is 3 attempts.)
Configuring Restrictions
Batch Cutoff Time
New Feature - -
If you configure the batch cut-off time for this gateway, partial refunds that occur before the batch has closed out will be queued for processing 12 hours after the batch has closed.
NOTE: 24 hour format, based on EST
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! |
International Percentage Restriction
If your merchant account has strict limits on the amount of international volume that you can process, this restriction allows you to place a percentage cap on the amount of international volume you process.
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.
| Field | Description |
|---|---|
| Reserve Percentage | Set your reserve percentages as established with your merchant account/ gateway provider. |
| Reserves Released Through | Set date in following format: MM/DD/YYYY |
| Reserve Days | Configure the number of days reserves are held. |
| Reserves Returned on Refund | Tracking 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:
- 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: http://secure.ultracart.com/cgi-bin/UCEditor?merchantId=DEMO&ADD=BONE&rtgCode=Auth3.1
In "Buy Form" code: <input type="hidden" name="rtgCode" value="Auth3.1" />
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.
Advanced Features
Prevent Cascading on Hard Declines
A new feature was added to the Rotating Transaction Gateway (hereafter referred to as RTG) in June 2023. The RTG may be configured to not cascade if a transaction response is a hard decline. UltraCart does not define what a hard decline is. That definition is left to the merchant based on the transaction gateway in use. UltraCart provides two fields: name and values. When populated, any response field with a matching name will be examined and if the value matches any values in the provided list, the failed transaction processing stops and does not cascade to the remaining configured gateways. The section is called Prevent Cascade and is located near the bottom of the gateway configuration screen. Below is a screenshot as of June 2023:
Enter the name of the response field in the Response Field Name and the hard decline values in the next field. For example, with Authorize.net, you may wish to add the field responseCode and values of 165 and 202. These are just examples. Review your previous orders transaction details to ensure you have the correct field name and values.
Frequently Asked Questions
Q: We presently have the checkout setting to capture the order after 3 failed attempts, however we just had an order go into A/R that ended up with 6 transaction, why did it contain 3 extra declines?
A: The three overall attempts going into the "rotating gateway" are what will appear in the orders transaction history, when reviewing the order. If you have cascade on decline configured, you can end up with six actual attempts. The higher level code that manages the three attempt counter before capture of order to A/R, does not include the subsequent cascade attempts. However, the cascaded transaction attempt does get stored in the order transaction history. The secondary attempt happens inside of the rotating gateway itself.
Which transactions get recorded into the review order transaction history:
- It returns the original failure if the secondary attempt fails.
- It returns the original attempt if the first one succeeds.
- It returns the secondary attempt if the secondary succeeds.
- Operations -> Reporting -> Rotating Transaction Gateway History (please contact UltraCart if you do not see this report in your reporting area.)
- BigQuery: uc_rotating_transaction_gateway_history (see BigQuery documentation for details.)
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 Authorize.net, 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".
Q: We have two active gateways, we have configured then each with 100% traffic, what will happen in this situation?
A: The total traffic percentage among all configured gateways should in most cases equal 100%. However, UltraCart will normalize the sum of the traffic percentages for the RTGs being considered based upon all the other restrictions that can be applied. So in the scenario where two active gateways are configured with 100%, and both are valid gateways and no other restrictions are configured on the RTG, Ultracart normalizes to 50/50 traffic percentage between the two gateways.