¶ Overview
You can group multiple gateways into a gateway group. This is useful when you have numerous gateways and wish to utilize them within payment profile cascades. Also enables you to use the same gateway multiple times within a payment profile cascade.
¶ View Gateway Groups
View all gateways by clicking the Payments > Credit Card > Gateway Groups link on the sidebar or going to https://revcent.com/user/gateway-groups
¶ Create A Gateway Group
Create a new gateway group by clicking the Create New Gateway Group button when viewing all gateway groups or go to https://revcent.com/user/new-gateway-group
¶ Name
Enter a name for the gateway group. Required and must be unique.
¶ Description
Enter a description for the gateway group.
¶ Status
Set the status of the gateway group.
¶ Edit A Gateway Group
Edit an existing gateway group by clicking the edit button when viewing all gateway groups.
¶ Name
Enter a name for the gateway group. Required and must be unique.
¶ Description
Enter a description for the gateway group.
¶ Status
Set the status of the gateway group.
¶ Choice Method
Select how RevCent will choose a gateway within the group when processing a transaction.
Options:
- Sort Order: Process valid gateways in the sort order within the group, beginning with gateway 1 in the group list. I.e. if gateway 1 is valid, then it will be used, else gateway 2 if valid, and so on.
- Round Robin: Process gateways in the sort order within the group list, beginning with the next gateway after the last transaction gateway used in the group list order. I.e. if gateway 1 was last used, then gateway 2 will be used if valid. If gateway 3 is last used, and is the last gateway in the rotation, then the rotation resets and gateway 1 will be used if valid.
- Evenly Distribute: Process valid gateways by even distribution of total captured payment volume within the past 24 hours. Sort order in the group list is ignored. Instead, least captured payment volume is what determines which gateway will be used. I.e. If gateway X has total captured payment volume of $210, gateway Y has total captured payment volume of $200 and gateway Z has total captured payment volume of $230, then gateway Y will be used as it has the least total captured payment volume.
¶ Grouping Method
You have the ability to group gateways by simply selecting from a list, or dynamically based on rules.
Options:
- Gateway: A list of all gateways in your account are shown in the left box (available list). To include a gateway in the group, click the blue arrow pointing to the right. The box on the right side (active list) is gateways which are active in the group. Remove a group by clicking the red arrow pointing to the left. Gateways in the active list are sortable, which enables you to move gateways according to the order you wish to process. The choice method is also dependent on the order of gateways. To sort/move a gateway simply click, hold and drag. The order is displayed on the right of each gateway in the active list.
- Dynamic: RevCent will build the group dynamically when transactions occur in your account. This is a highly advanced feature and it is recommended to read the Dynamic Gateway Group section below.
¶ Dynamic Gateway Group
You can set specific rules which will determine the gateways that enter or leave a group. This is a highly advanced feature and we recommend you read thoroughly or contact RevCent for help building your rules JSON.
¶ How It Works
RevCent will traverse the rules JSON, determine whether a gateway passes or fails, and rebuild the gateway group. This is done automatically when a transaction is created or modified as well as when you save a dynamic gateway group.
- Your Source Gateway Groups are extracted and all gateways within said groups are combined into an allow gateway list.
- Your Deny Gateway Groups are extracted and all gateways within said groups are combined into a deny gateway list.
- Any gateways in the allow gateway list which are also in the deny gateway list are removed, forming a final gateway list.
- The final gateway list is processed, each gateway within the list is analyzed and either passes or fails based on the rules JSON.
- The gateway group is rebuilt using the gateways which individually passed the rules JSON.
When rebuilding occurs:
- RevCent will automatically rebuild the gateway group when transactions are created or modified.
- If you make changes to a dynamic gateway group and save, the rebuild is done immediately.
¶ Using Other Groups
Instead of choosing gateways individually, you instead choose other gateway groups as either your Source Groups, Deny Groups or Failsafe Groups.
¶ Source Groups
Select gateway groups containing the gateways to individually analyze and insert if the gateway passes all rules. These will be the gateways you plan on potentially entering the group if each passes according to the rules JSON.
¶ Deny Groups
Select gateway groups containing gateways that should never be inserted regardless of rules or in source groups. I.e. a blacklist.
¶ Failsafe Groups
If the gateway group does not have any gateways after processing rules, then all gateways within selected failsafe groups will be automatically inserted.
¶ Rules JSON
The rules JSON is the most important part when creating a dynamic group. The JSON contains both an “and” array as well as an “or” array. This is to allow conditional logic with nesting. The array must contain one or more rule objects. RevCent will go through all arrays, parse each rule object to determine a pass or fail, and ultimately determine whether the gateway it is analyzing has passed.
Note: The rule JSON must always start with a single “and” array.
¶ and Array
The “and” array is a conditional statement which allows you to group rule objects that must all pass in order for the condition to pass.
¶ or Array
The “or” array is a conditional statement which allows you to group rule objects that at least one must pass in order for the condition to pass.
¶ Rule Object
The rule object is an individual rule which either passes or fails. It must be contained within either an “and” array or an “or” array.
{
"parameter": "percent_declined",
"comparison": "less_than",
"comparison_value": 70,
"date_start": "12 hours",
"date_end": "now",
"transaction_type": [
"sale_create"
],
"if_no_result": "fail"
}
¶ parameter
The parameter is the aggregate value you want calculated, then analyzed. It will be calculated using the time values, then compared using the comparison and comparison_value.
options:
- percent_approved: The percentage of approved transactions compared to all transactions during the date range.
- percent_declined: The percentage of declined transactions compared to all transactions during the date range.
- percent_chargeback: The percentage of transactions with a chargeback compared to all transactions during the date range.
- sum_approved: The sum amount of approved transactions during the date range.
- sum_declined: The sum amount of declined transactions during the date range.
- sum_chargeback: The sum amount of transactions with a chargeback during the date range.
- sum_amount: The sum amount of all transactions, either approved, declined or chargeback, during the date range.
¶ comparison
The parameter is the aggregate value you want analyzed. It will be calculated using the time values, then compared using the comparison values.
options:
- less_than: The calculated parameter value is less than the comparison_value.
- greater_than: The calculated parameter value is greater than the comparison_value.
- equal_to: The calculated parameter value is equal to the comparison_value.
¶ comparison_value
The set value to compare to the parameter using the comparison property.
¶ date_x
The date_start and date_end properties determine the date range to be used when calculated the parameter. Both date_start and date_end are strings, either equals “now” or formatted as “[time_value] [time_unit] [relative] [relative_unit]”.
When using the later formatted time, there must be a space in between each partition (the parts in brackets) or parsing will fail. Formatted time always subtracts from the current time to derive the date. i.e. if “5 hours” then subtracts five hours from current time. If “1 months” then subtracts one month. Do not include brackets when creating formatted time.
If not using “now” as date_x, below are the formatted time partitions:
- time_value: The value of X time_unit to subtract from the current time. Required.
- time_unit: Can be either: hours, days, weeks, months. Required.
- relative: You have the ability to use the start of end of a given time. Can be either: start_of, end_of. Optional.
- relative_unit: The start of the time unit. Can be either: hour, day, week, month. Optional.
Examples:
"date_end": "now" // Will use the current time.
"date_start": "5 hours" // Will subtract 5 hours from current time.
"date_end": "4 weeks" // Will subtract 4 weeks from current time.
"date_start": "1 months start_of month" // Will subtract 1 month from current time, and use the start of the month.
"date_end": "1 days end_of day" //Will subtract 1 day from current time and use the end of the day.
¶ transaction_type
You can limit the calculations to only transactions that are of a certain type. Provide one or more values to limit the transactions to a certain type or types. If transaction_type array is empty, then only sale_create transactions are calculated.
options:
- sale_create: Initial sale transactions.
- subscription_renew: Subscription renewal transactions.
- trial_expire: Trial expiration transactions.
¶ if_no_result
When RevCent runs the calculation and does not receive a result, you can specify whether the lack of result is a pass or fail. For example, if a gateway does not have any transactions for a specific date range, then there will be no result.
options:
- pass: If there is not result for a gateway for a calculation, then the rule automatically passes.
- fail: If there is not result for a gateway for a calculation, then the rule automatically fails.
¶ Example Rule Objects
Below are individual rule objects, explaining whether the individual rule passes or fails. Rule objects are not used as the rule JSON itself, they are contained within either an “and” array or an “or” array within the final rule JSON.
¶ Example 1
The rule passes if the percentage of declined transactions within the past 6 hours for only initial sales is less than 50%. If the percentage of declined transactions for initial sales was greater than 50% then the rule would fail.
{
"parameter": "percent_declined",
"comparison": "less_than",
"comparison_value": 50,
"date_start": "4 hours",
"date_end": "now",
"transaction_type": [
"sale_create"
],
"if_no_result": "pass"
}
- parameter: The percent_declined value indicates we will calculate the percentage of declined transactions. This value is calculated based on the date range values of date start 6 hours prior and date end of current time.
- comparison: Using the less_than comparison combined with the comparison_value of 50. I.e. if parameter calculation is less than 50 then pass, else fail.
- comparison_value: The value of 50 is combined with the comparison value of less_than, then compared to the parameter calculation. I.e. if parameter calculation is less than 50 then pass, else fail.
- date_start: The 4 hours, [time_value] [time_unit], means we will be subtracting 4 hours from the current time as the start of the date range.
- date_end: Using now indicates that we will use the current time as the end of the date range.
- transaction_type: The only value present is sale_create, indicating we only want to calculate transactions from initial sales.
- if_no_result: The pass value indicates that if there is no result, i.e. no initial sale transactions within the past 6 hours, then we automatically pass the rule.
¶ Example 2
The rule passes if the percentage of transactions for the entire month prior with a chargeback is less than 4.5%. If the chargeback percentage is greater then 4.5% then the rule would fail.
{
"parameter": "percent_chargeback",
"comparison": "less_than",
"comparison_value": 4.5,
"date_start": "1 months start_of month",
"date_end": "1 months end_of month",
"transaction_type": [
"sale_create",
"trial_expire",
"subscription_renew"
],
"if_no_result": "pass"
}
- parameter: The percent_chargeback value indicates we will calculate the percentage of transactions with a chargeback.
- comparison: Using the less_than comparison combined with the comparison_value of 4.5. I.e. if parameter calculation is less than 4.5 then pass, else fail.
- comparison_value: The value of 4.5 is combined with the comparison value of less_than, then compared to the parameter calculation. I.e. if parameter calculation is less than 4.5 then pass, else fail.
- date_start: The 1 months start_of month, [time_value] [time_unit] [relative] [relative_unit], means we will be subtracting 1 month from the current time, and using the start of the month, as the start of the date range.
- date_end: The 1 months end_of month, [time_value] [time_unit] [relative] [relative_unit], means we will be subtracting 1 month from the current time, and using the end of the month, as the end of the date range.
- transaction_type: The sale_create, trial_expire and subscription_renew values indicate we want to calculate all transactions from initial sales, trial expirations and subscription renewals.
- if_no_result: The pass value indicates that if there is no result, i.e. no chargebacks in the prior month, then we automatically pass the rule.
¶ Example 3
The rule passes if the sum amount of approved transactions for initial sales, during the current day is less than $400. If the sum amount of approved transactions for initial sales is greater then $400 then the rule would fail.
{
"parameter": "sum_approved",
"comparison": "less_than",
"comparison_value": 400,
"date_start": "0 days start_of day",
"date_end": "now",
"transaction_type": [
"sale_create"
],
"if_no_result": "pass"
}
- parameter: The sum_approved value indicates we will calculate the total amount of approved transactions.
- comparison: Using the less_than comparison combined with the comparison_value of 400. I.e. if parameter calculation is less than 400 then pass, else fail.
- comparison_value: The value of 400 is combined with the comparison value of less_than, then compared to the parameter calculation. I.e. if parameter calculation is less than 400 then pass, else fail.
- date_start: The 0 days start_of day, [time_value] [time_unit] [relative] [relative_unit], means we will be subtracting 0 days, i.e. current day, and using the start of the current day as the start of the date range.
- date_end: Using now indicates that we will use the current time as the end of the date range.
- transaction_type: The only value present is sale_create, indicating we only want to calculate approved transactions from initial sales.
- if_no_result: The pass value indicates that if there is no result, i.e. no approved transactions during the current day, then we automatically pass the rule.
¶ Example Rule JSON
Below is an example of a final rule JSON. In the example we want to have a gateway enter a group if it has low declines or hasn't been used, but definitely does not have high chargebacks.
Either:
- The percentage of declined initial sale transaction is less than 50% in the past 4 hours.
- The sum amount of approved transactions for initial sales is less than $400 for the current day.
And:
- The percentage of chargebacks is below 4.5% for the prior month.
{
"and": [
{
"or": [
{
"parameter": "percent_declined",
"comparison": "less_than",
"comparison_value": 50,
"date_start": "4 hours",
"date_end": "now",
"transaction_type": [
"sale_create"
],
"if_no_result": "pass"
},
{
"parameter": "sum_approved",
"comparison": "less_than",
"comparison_value": 400,
"date_start": "0 days start_of day",
"date_end": "now",
"transaction_type": [
"sale_create"
],
"if_no_result": "pass"
}
]
},
{
"parameter": "percent_chargeback",
"comparison": "less_than",
"comparison_value": 4.5,
"date_start": "1 months start_of month",
"date_end": "1 months end_of month",
"transaction_type": [
"sale_create",
"trial_expire",
"subscription_renew"
],
"if_no_result": "pass"
}
]
}
There are three rule objects, contained in different conditions, each condition being an array.
- The rule JSON must always start with an “and” array, meaning any direct child arrays or direct child objects contained within the starting “and” must all pass.
- The “and” array contains two items: an “or” array and a percent_chargeback rule object .
- The “or” array contains both the percent_decline rule object and the sum_approved rule object. Since it is an “or” condition, if either rule object passes then the condition passes.
- The percent_chargeback rule is contained within the starting “and” array, meaning it must pass in order for the overall rule JSON to pass.
- If both the percent_chargeback rule object passes and either rule objects in the “or” array passes, then the gateway will have passed the rule JSON and will be entered into the group.