¶ Overview
The Next-Gen payment profile allows much more flexibility and customization that the original Basic payment profile. However, if you do not require an advanced iteration of the payment profile, we recommend using the Basic payment profile type, found here.
¶ Why Use A Next-Gen Payment Profile?
- You are already familiar with payment profiles in RevCent and require more customization.
- You require advanced filtering and routing capabilities when processing payments that the Basic payment profile does not offer.
- You understand that the slightest mistake in your flow design will cause major problems with your payment routing.
¶ Payment Flow Builder
The payment flow builder is the visual editor, allowing you to insert, drag, drop and connect nodes. Each node has a specific purpose, either as an action or a filter.
¶ Nodes
The flow builder is built around nodes, which are able to be connected by selecting a node output and dragging to another nodes' input.
¶ Node Types
There are three node types and each type has a sub type.
- Start Node
- Filter Node
- Action Node
¶ Node Inputs
All nodes have a single input, except for the Payment Request start node.
¶ Node Outputs
Depending on the node type, there can be zero, one, two or three outputs. The node sub type determines the node output.
¶ Connecting Nodes
Connect nodes by selecting a nodes' output and dragging to another nodes' input.
¶ Start Nodes
There is a single start node type, the Payment Request node.
¶ Payment Request
The only start node available is the Payment Request node type. Every Next-Gen profile must begin with a start node in the visual builder. Drag and drop the start node to begin building your payment flow.
Only one start node is allowed, and is the starting point for the remainder of the flow.
¶ Filter Nodes
All filter nodes have a green and red output. The green output is if the filter passed, the red output is if the filter failed.
¶ Attempt Count
The attempt count filter allows you to filter based on the number of attempts specific to the entity being processed. You have the option to filter whether the attempt count is less than or equal to, or greater than or equal to. Note: Applies to initial sale (not pending sale recovery), and subscription renewal request types only. Request types and attempt calculations explained below.
- Initial Sale: An attempt is the previous completion of a payment flow for the same sale. I.e., customer previously clicked to purchase, for the same sale, and was declined after the flow request ended.
- Subscription Renew: An attempt is the number of subscription renewals, which includes the current one being processed. I.e., if there were 2 prior renewals, then the attempt count is 3. If there were no prior renewals, then the attempt count is 1.
Example Node
In the example above, we are filtering based on the number of attempts being greater than or equal to 4. If the number of attempts is greater than or equal to 4 (passed), the green output would be followed. If the number of attempts is less than 4 (failed), the red output would be followed.
¶ BIN Profile
The BIN profile filter allows you to filter based on the first 6 of the current credit card being used for the payment request via BIN profile. You have the option to filter on whether a card BIN is within a BIN profile, not within a BIN profile, or both.
Example Node
In the example above, we are filtering based on the first 6 digits of the credit card being used to process payment. We previously created BIN profiles, with one more BIN's in each. If the card first 6 is in BIN Profile 42 and not in BIN Profile 49, then the green output would be followed, else the red output.
¶ Campaign
The campaign filter allows you to filter based on the campaign associated with the request. You have the option to filter on whether the request is associated with a campaign, not associated with a campaign, or both.
Example Node
In the example above, we are filtering based on the campaign being one and not the other. If the campaign associated with the request is Adwords Campaign, and is not the Facebook Campaign, then the green output would be followed, else the red output.
¶ Card Type
The card type filter allows you to filter based on the card type being used to process payment. You have the option to filter on whether the card type is one or more types, is not one or more types, or both.
Example Node
In the example above, we are filtering based on the card type being Maestro. If the card type is Maestro then the green output would be followed, else the red output.
¶ Currency
The currency filter allows you to filter based on the currency associated with the request. You have the option to filter on whether the currency is, is not, or both.
Example Node
In the example above, we are filtering based on the currency being one and not the other. If the currency associated with the request is USD, and is not EUR, then the green output would be followed, else the red output.
¶ Customer Group
The customer group filter allows you to filter based on the customer group(s) of the customer associated with the request. You have the option to filter based on whether a customer is in a customer group, not in a customer group, or both.
Important: This should be used as a historical filter for pre-existing customers. Customer groups do not apply to customers instantly. Please read the list of caveats below carefully.
Caveats
- It may take up to 15 minutes after the customers' most recent action for the applicable customer group(s) to be applied/removed.
- If a customer recently attempted to purchase, recently received a refund, etc., qualifying customer group(s) may not be applied or removed for at least 15 minutes.
- If you recently changed one or more customer groups' settings, all past customers are not refreshed to reflect updates to any of their customer group(s) until 2:00am EST each day.
Example Node
In the example above, we are filtering based on the customer associated to the request not being in a specific group. If the customer associated with the request is not in the Lifetime value under 100 customer group, then the green output would be followed, else the red output.
¶ Gateway Response
The gateway response filter allows you to filter based on the most recent response received from a gateway in the current payment request. Enter one or more terms, each separated by a new line, which must be contained in the gateways response in order for the filter to pass. Useful for determining whether to continue and/or perform further actions.
Note: The profiles' settings for kill terms and max attempts, if enabled, will still apply.
Example Node
In the example above, we are filtering based on either of two specific terms/phrases being found within the most recent gateway response. If either insufficient funds or pick up card are found in the gateways' response, then the green output would be followed, else the red output.
¶ Metadata
The metadata filter allows you to filter based on the metadata contained within one or more sources. Select the metadata source, i.e. where to search for metadata entries. Payment Request is any metadata contained in a current Initial Sale API call. You have the option to filter on whether the source has or does not have specific metadata names and values.
Metadata Sources
- Customer: Any metadata contained in the customer related to the entity being processed.
- Current Chosen Gateway: The current gateway chosen, prior to processing payment, if one has been chosen.
- Payment Request: Applies to initial sale request type only, with the metadata contained in a current Initial Sale API call.
- Sale: Any metadata contained in the sale related to the entity being processed.
- Subscription: Applies to subscription renew request type only.
- Trial: Applies to trial expire request type only.
Example Node
In the example above, we are filtering based on the initial sale request having the is_upsell metadata name having a value of true. If the metadata matches, i.e. [{"name": “is_upsell”, “value”: “true”}] then the green output would be followed, else the red output.
¶ Payment Amount
The payment amount filter allows you to filter based on the payment amount that is to be processed. You have the option to filter whether the amount is less than or equal to, or greater than or equal to a certain amount.
Example Node
In the example above, we are filtering based on the request payment amount being less than or equal to $300.00. If the request is less than or equal to $300.00 the green output would be followed, else the red output.
¶ Process Payment Count
The process payment count filter allows you to filter based on the number of Process Payment nodes executed in the current flow request. I.e. the number of times that payment was attempted already in the request. You have the option to filter whether the process payment count is less than or equal to, or greater than or equal to a certain number.
Example Node
In the example above, we are filtering based on the number of payment nodes executed in the current flow request. If the number of process payment nodes executed is less than or equal to 3, the green output would be followed. If the number of process payment nodes executed is greater than 3, the red output would be followed.
¶ Product Group
The product group filter allows you to filter based on the product(s) contained in a product group associated with the request. You have the option to filter on whether a product is in a product group, not in a product group, or both.
Example Node
In the example above, we are filtering based on the requests' product being within the Subscription Group. If one or more request products are in the Subscription Group, the green output would be followed, else the red output.
¶ Request Type
The request type filter allows you to filter based on the request type associated with the request. You have the option to filter on whether the request type is, is not, or both.
Request Types
- Initial Sale
- Pending Sale Profile Recovery
- Subscription Renew
- Trial Expire
Example Node
In the example above, we are filtering based on the request type being Subscription Renew. If the request type is Subscription Renew, the green output would be followed, else the red output.
¶ Merge Filters
The merge filters node allows you to combine multiple filters. Connect the grey output (third output) of a Merge Filters node to the input of one or more filter nodes to merge all connected as one. All filters connected (merged) to the grey output must pass in order for the merge filter to pass.
Node Outputs:
- Green: All merged filters passed.
- Red: One or more merged filters failed.
- Grey: Connect to other filters to merge together as one.
Example Node
In the example above, we are merging multiple filters into a single filter. We used the grey output node to connect the Request Type and Campaign filters. If the request type is Initial Sale and the request is associated with the Facebook Campaign, the merge filters green output would be followed, else the red output.
¶ Filter Node Priority
You may wish to have multiple filters checked separately, with certain ones checked before others, when at the same point in a flow. The same point being the part of the flow where multiple filters coincide at the same time. Every filter has a filter priority, allowing you to tell RevCent which filter to check before others when at the same point.
¶ Priority Value
Important: The lower the number, the higher up the list, i.e. checked first. For example, a filter with priority 0 will be checked before a filter with priority 1. Filters with the same priority are checked in random order at time of processing.
| Filter | Priority Value | Explained |
|---|---|---|
| Filter A | 0 | The filter priority value is 0. Therefore it will be checked before the other filters with a higher priority value. |
| Filter D | 3 | The filter priority value is 3. Therefore it will be checked after Filter A, but before Filter U. |
| Filter U | 4 | The filter priority value is 4. Therefore it will be checked after Filter A and Filter D. However, since it has the same priority as Filter B, either Filter U or Filter B will be checked at random after Filter D. |
| Filter B | 4 | The filter priority value is 4. Therefore it will be checked after Filter A and Filter D. However, since it has the same priority as Filter U, either Filter U or Filter B will be checked at random after Filter D. |
¶ Action Nodes
The following action nodes are available.
¶ Abort Flow
Payment flow will be aborted. Use this node if you want to stop the flow and return an error for a specific campaign, gateway response, failed filter, etc. If a payment has been attempted, the decline results will be returned, else an error will be returned. Note: The payment profiles' settings for kill terms and max attempts, if enabled, will still apply.
¶ Choose A Gateway
The Choose a Gateway node determines the gateway to be used to process a payment request. Several settings and options are available.
¶ Selection Source
Select the source, either from a list of gateways, or a list of gateway groups.
Options:
- Gateways: If selected, a list of gateways will appear. This will allow you to sort as well.
- Gateway Groups: If selected, the gateway group selected will appear.
- Last Approved Gateway: If selected, RevCent will choose the gateway last approved for the customer, ignoring all revenue rules and time rules. Note: If none exists, RevCent will defer to the failsafe gateway.
- Last Declined Gateway: If selected, RevCent will choose the gateway last declined for the customer, ignoring all revenue rules and time rules. Note: If none exists, RevCent will defer to the failsafe gateway.
¶ Selection Source - Gateway Group(s)
Select one or more gateway groups. All gateways within selected gateway groups will be merged, ignoring each gateway groups' choice method and gateway sort order. The merge will create a single list of unique gateways, sorted randomly. The Selection Method setting will determine the final gateway.
¶ Selection Source - Gateway(s)
When selecting Gateways as the selection source, two boxes will appear. The first box is for choosing gateways, the second is for sorting chosen gateways.
You choose the gateway(s) you want by clicking the blue down arrow.
When you click the blue down arrow in the Select Gateways box, this will add the gateway to the Gateway(s) Selected list. This is the list of gateways that RevCent will choose from. You can also sort them by dragging up or down.
¶ Selection Method
Select the method in which a gateway will be chosen from the list of gateways from selected gateways/gateway groups.
Options:
- Evenly Distribute: Process valid gateways by even distribution of total captured payment volume within the past 24 hours. 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. This is the recommended method when using Gateway Group(s) as the Selection Source.
- Random: Will pick a random gateway from the list of gateways from selected gateways/gateway groups.
- Round Robin: Process gateways in the sort order, beginning with the next gateway after the last transaction gateway used in the sort 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. Applies to Gateway source only. You can sort gateways by dragging up or down in the Gateway(s) Selected box.
- Sort Order: Process valid gateways in the sort order within the list of selected gateways, always starting with gateway 1. I.e. if gateway 1 is valid, then it will be used, else gateway 2 if valid, and so on. Applies to Gateway source only. You can sort gateways by dragging up or down in the Gateway(s) Selected box.
¶ Prefer Gateway If
Select one or more conditions in which a gateway should be preferred. CVV Bonus is if a gateway was used in an initial sale where the CVV was passed.
Note: Any subscription profile prefer or trial prefer settings outside of this profile take precedence, i.e. override this setting.
Options:
- Previously Approved for Entity: Give a gateway preference if it has already been successful for the current sale, subscription or trial.
- Previously Approved for Customer (CVV Bonus): Give a gateway preference if it has already been successful for the current customer. In addition, give the gateway a greater preference if it was previously successful when including CVV.
- Previously Declined for Entity: Give a gateway preference if it has already been declined for the current sale, subscription or trial. Useful for retrying declined MID's when the customer needs to contact their bank.
- Previously Declined for Customer (CVV Bonus): Give a gateway preference if it has already been declined for the current customer. In addition, give the gateway a greater preference if it was previously declined when including CVV.
Terminology:
- Entity: The current sale, subscription, or trial being processed according to the request type.
- Customer: The customer related to the current request.
¶ Do not choose gateway if
Select one or more conditions in which a gateway should not be chosen.
Options:
- Previously Declined In Current Request: If the gateway has been declined in the current flow request, do not choose it.
- Previously Declined For Entity: If the gateway has been declined at any point in the entity's history do not choose it.
- Previously Declined for Customer: If the gateway has been declined at any point in the customers' history, do not choose it.
- Previously Approved For Entity: If the gateway has been approved at any point in the entity's history do not choose it.
- Previously Approved for Customer: If the gateway has been approved at any point in the customers' history, do not choose it.
Terminology:
- Current Request: The current flow request.
- Entity: The current sale, subscription, or trial being processed according to the request type.
- Customer: The customer related to the current request.
¶ Once Declined Gateway Group(s)
Select one or more gateway groups in which once a decline has occurred for any gateways within the group, no gateways in the same group can be chosen.
¶ Once Approved Gateway Group(s)
Select one or more gateway groups in which once an approval has occurred for any gateways within the group, no gateways in the same group can be chosen.
¶ Do not choose gateway in Gateway Group(s)
Select one or more gateway groups in which a chosen gateway cannot not be in. This is meant to be used as a block list via gateway groups.
¶ Failsafe Gateway(s)
Select one or more gateways to use as a failsafe, in case no gateways could be chosen. A gateway will be selected randomly and used regardless of any revenue or time rules.
¶ Decrease Amount
Do you want to decrease the payment amount before processing? Will only apply to additional payment attempts during a payment request, i.e. will be ignored for the first payment attempt.
¶ Decrease Amount - Percentage
Modify the original transaction amount by a percentage decrease.
¶ Decrease Amount - Fixed
Modify the original transaction amount by a fixed dollar amount decrease.
¶ Swap Card
Do you want to swap to another card if one is available? Will only apply to additional payment attempts during a payment request, i.e. will be ignored for the first payment attempt. Note: Only implemented for subscription renewal and trial expiration requests, not sale requests.
¶ Insert Metadata
Select the entity(s) to insert the metadata entries into. The insert metadata node is unique in that it does not have an output. It is a side action meant to be conducted along with the execution of other filter or action nodes.
¶ Available Entities:
- Sale
- Customer
- Subscription
- Subscription Renewal
- Trial
¶ Available Shortcodes
Use shortcodes for dynamic text. Must follow the same format as shown, i.e. surrounded by hashtags #shortcode#
#gateway_id#The ID of most recent gateway chosen.#gateway_name#The name of the most recent gateway chosen.
Example Node
In the example above, we are inserting two separate metadata entries into the sale related to the request. Notice the second entry using a shortcode, which is dynamic.
¶ Process Payment
If a gateway has been chosen in a prior node, you can officially process the payment. This is a static node that will send a payment request to the chosen gateway. If the payment is successful, the flow will automatically end and the success response returned. If unsuccessful you can use the red output to connect to further nodes, else the flow will end and the decline response will be returned.
¶ Run Function
You can choose to run a function when processing a payment request. The function can return a specific response, or can run separately without interrupting the payment flow.
Important: This is a highly advanced feature and is only recommended to use if you have an experienced developer and fully understand the Next-Gen flow process.
¶ Select Function
Select the function you have created.
¶ Run Method
Select the run method. This determines whether the payment request will wait for a response, or continue and run the function separately.
Options:
- Queue And Continue: The function will run separately without waiting for a response from the function, i.e. wont pause the flow. The green output of the current function node will be followed.
- Wait For Response: The function will run and RevCent will wait for the response. The response can determine the next node. Please read the warnings below.
Warning when using the “Wait For Response” method:
- It is always recommended to route the red output as a backup in case the function fails or times out. The red output is treated as a function failure/timeout output.
- A function is given a max 8 second time to respond within the flow before a timeout error occurs, in which the red output will be followed.
- Bad function code can result in payments never being processed.
- Functions cause latency, which will result in having to wait longer for a payment response.
¶ Function Event Data
When the function is executed, it will receive the following event.data object which contains the details of the current flow request. The item details of the flow request is contained in the event.data.item_details object.
{
"item_type": "sale",
"item_id": "KnZaE2AZ85SoEX5g5ZbY",
"item_event": "payment_request",
"item_details": {
"request": {
"type": "sale",
"method": "create",
"metadata": [
{
"name": "landing_page",
"value": "v1",
"entry_date": "2023-10-17"
}
]
},
"entity": {
"item_type": "sale",
"item_id": "KnZaE2AZ85SoEX5g5ZbY",
"metadata": [
{
"name": "landing_page",
"value": "v1",
"entry_date": "2023-10-17"
}
]
},
"customer": {
"id": "qZoyanPoLBI10GlLloaz",
"first_name": "George",
"last_name": "Washington",
"address_line_1": "1600 Pennsylvania Ave",
"address_line_2": "",
"city": "Washington",
"state": "DC",
"zip": "20500",
"email": "george@whitehouse.gov",
"phone": "1234567890"
},
"customer_card": {
"id": "pgdl8NydEOurjPYoYdmy",
"first_6": "424242",
"card_type": "visa",
"bin_details": {
"bin_bank": "CAPITAL ONE N.A.",
"bin_phone": "1-800-227-4825"
}
},
"campaign": {
"id": "JN0Zpj7RGJiwKqAnRoy6",
"name": "Twitter Campaign"
},
"payment_profile": {
"id": "1rzGgRKJ90UGM9kZMbKY",
"name": "Flow Profile"
},
"payment_amount": 10.7,
"products": [
{
"id": "LYE26YQPv5f5VbJmlpRR",
"name": "AV 2017",
"sku": "av_2017",
"internal_id": "av_2017",
"quantity": 1,
"price": 29.99,
"amount": 29.99,
"is_trial": true,
"metadata": []
}
],
"shipping": [
{
"amount": 10,
"provider": "ups",
"provider_method": "ups_standard"
}
],
"tax": [
{
"name": "Tax Profile",
"amount": 0.7
}
],
"gateway_history": {
"current": {
"declined": [
"8rNnkY45R4Hw1ZBg1yYB"
]
},
"customer": {
"approved": [],
"approved_cvv": [],
"declined": [
"8rNnkY45R4Hw1ZBg1yYB"
],
"declined_cvv": []
},
"entity": {
"approved": [],
"approved_cvv": [],
"declined": [
"8rNnkY45R4Hw1ZBg1yYB"
],
"declined_cvv": []
},
"gateway_group": {
"approved": [],
"approved_cvv": [],
"declined": [
"GOGaPRql9oUAAkrm5Ll9"
],
"declined_cvv": []
}
},
"node_id": "837cabc6-46d3-46e5-869d-9819e6af8464",
"next_nodes": {
"actions": [
{
"id": "43965f05-887a-4e70-8646-0410440a3494",
"name": "action_process_payment",
"node_type": "action",
"node_note": "node note"
}
],
"filters": []
},
"current_step": 2,
"step_array": [
{
"step_action": "initial",
"step_amount": 10.7,
"step_card": "pgdl8NydEOurjPYoYdmy",
"step_gateway": "NMI",
"step_gateway_id": "8rNnkY45R4Hw1ZBg1yYB",
"step_gateway_response": "",
"step_modifier": "",
"step_num": 1,
"step_result": "Declined",
"step_setting": "initial",
"step_source": "flow",
"step_transaction": "JN7nVvo0PdtRr2bkbN1X",
"swap_card": false
},
{
"step_action": "next",
"step_amount": 10.7,
"step_modifier": "",
"step_num": 2,
"step_setting": "",
"step_source": "flow",
"swap_card": false
}
],
"flow_path": [
{
"order": 1,
"id": "8f6d288f-697e-4c99-92c5-7551ba43c547",
"node_type": "start",
"name": "start_payment_request",
"step_num": 1,
"result": {
"code": 1,
"message": "Processed"
}
},
{
"order": 2,
"id": "91da1872-0511-4847-8a1b-a33c603e748b",
"node_type": "filter",
"name": "filter_request_type",
"step_num": 1,
"result": {
"code": 1,
"message": "Filter passed."
}
},
{
"order": 3,
"id": "628ee271-cbe2-45a0-8d68-48d0ab8bdf9c",
"node_type": "action",
"name": "action_choose_gateway",
"step_num": 1,
"result": {
"code": 1,
"message": "Gateway chosen.",
"failsafe_gateway": false,
"gateway_id": "8rNnkY45R4Hw1ZBg1yYB",
"gateway_name": "NMI"
}
},
{
"order": 4,
"id": "0b8a520e-a74e-4516-8a5b-807337687847",
"node_type": "action",
"name": "action_process_payment",
"step_num": 1,
"result": {
"code": 2,
"message": "Payment declined."
}
},
{
"order": 5,
"id": "837cabc6-46d3-46e5-869d-9819e6af8464",
"node_type": "action",
"name": "action_custom_function",
"step_num": 2,
"result": {}
}
]
}
}
The event.data.item_details properties:
| Property | Explained | Format |
|---|---|---|
| request | Contains details about the request being processed. For initial sale requests, any metadata sent in the API call is included. | Object |
| entity | Contains details regarding the entity related to the request. For example, the entity for an initial sale request would be the specific sale, the entity for a subscription renewal request would be the related subscription. | Object |
| customer | Contains details regarding the customer related to the request. | Object |
| customer_card | Contains details regarding the customer card related to the request. | Object |
| campaign | Contains details regarding the campaign related to the request. | Object |
| payment_profile | Contains details regarding the payment profile related to the request. | Object |
| payment_amount | The payment amount to be processed for the flow request. | Float |
| products | An array of product objects specific to the flow request. | Array |
| shipping | An array of shipping objects specific to the flow request. | Array |
| tax | An array of tax objects specific to the flow request. | Array |
| gateway_history | The gateway and gateway group history specific to the request, entity and customer. Useful for determining the next gateway or gateway group to use to process payment, or deciding action to take based on history. | Object |
| gateway_history.current |
An array of declined transaction gateway IDs specific to the current request. This is all gateways that declined a payment during the current flow request being processed.
|
Object |
| gateway_history.customer |
Multiple arrays of transaction gateway IDs specific to the customer related to the request, for both current and past transactions.
|
Object |
| gateway_history.entity |
Multiple arrays of transaction gateway IDs specific to the entity related to the request, for both current and past transactions.
|
Object |
| gateway_history.gateway_group |
Multiple arrays of transaction gateway group IDs specific to the customer related to the request, for both current and past transactions. Only applicable if using gateway groups with gateways associated within.
|
Object |
| node_id | The current Run Function node ID. | String |
| next_nodes | The nodes, with node type, connected to the outputs of the Run Function node. Useful when parsing and then providing the next_node_id property in your response object. | Array |
| current_step | The current step being processed in the step array. | Integer |
| step_array | The step array, containing the current step object any past steps in which payment was attempted. Useful for determining future actions based on past payment attempts during the request. | Array |
| flow_path | The current flow path taken leading up to the execution of the Run Function node. Contains an ordered list of nodes processed with individual results. You can parse the flow path to determine any filters passed/failed, prior payments, etc. | Array |
¶ Your Response Object
If you are using the Wait For Response run method, you must return a response object. Not all properties are required. If no properties are provided, RevCent will consider the node as having “passed", without taking any action, and will follow the green output. If you do not need to have the response take action within the flow, then use the Queue And Continue run method instead of Wait For Response.
Important: Only provide the properties specific to what you want to do when the Run Function node receives the response.
{
"next_node_id": "43965f05-887a-4e70-8646-0410440a3494",
"next_output": "1",
"set_gateway_id": "bOLjn0yvKpUp10qK298R",
"selection_method": "evenly_distribute",
"choose_gateways": ["2r7zOBMldVIomKNdKZoG"],
"choose_gateway_groups": ["GOGaPRql9oUAAkrm5Ll9"],
"custom_error": "Card CVV Invalid"
}
| Property | Explained | Format |
|---|---|---|
| next_node_id | If you want to designate a specific next node connected to the output of the Run Function action node. View available output nodes via the event.data.next_nodes actions array and/or filters array. | String |
| next_output | If you want to designate the output of the Run Function action node. 1 is the green output, 2 is the red output. Possible values: 1, 2. | String |
| set_gateway_id | If you want to set a specific gateway as the current step gateway for payment processing. Note: a Process Payment node needs to be in the output of the current function node in order to process payment. | String |
| select_method | If providing either choose_gateways or choose_gateway_groups, optionally set the selection method, which will override the next Choose Gateway nodes' selection method. Note: a Choose Gateway node needs to be in the output of the current function nodes' flow in order to override the selection method. Possible values: evenly_distribute, round_robin, random. | String |
| choose_gateways | Provide an array of gateway ID's which will override a next Choose Gateway nodes' gateway selections. Note: a Choose Gateway node needs to be in the output of the current function nodes' flow in order to override the gateways. | Array |
| choose_gateway_groups | Provide an array of gateway group ID's which will override a next Choose Gateway nodes' gateway group selections. Note: a Choose Gateway node needs to be in the output of the current function nodes' flow in order to override the gateway groups. | Array |
| custom_error | Provide a custom error response, which will be passed to a following abort flow node. The abort flow node will respond to the API request with either a message property or a custom_error property. Please read the Custom Error Message section thoroughly to understand how to parse and potentially display custom errors and messages to customers. Important: the function response must also return a next_node_id property, with the next_node_id being a following abort flow node. Ex. function response: {"next_node_id": “0b8a520e-a74e…”, “custom_error”: “Card CVV Invalid”} |
String |
¶ Flow Process In Action
Below describes how the Next-Gen profile flow is processed by RevCent when a payment request is received.
¶ Flow Starts
A payment request is received and is to be processed by the Next-Gen profile flow. The Payment Request start node is the beginning of the flow. RevCent begins at the Payment Request node output and continues to other nodes.
¶ Output To Other Nodes
RevCent will follow the output of a current node to any additional nodes connected. The next node to be processed is determined using abort flow, filter first passed, filter first failed, then action, in that order.
¶ Next Node Determination
You can output from one node to multiple nodes, however there is node type and outcome to consider. Below is the node type order.
| Order | Node Type | Explained |
|---|---|---|
| 1 | Abort Flow | If an Abort Flow node is present in the output of a node, it will take precedence over all other output nodes. |
| 2 | Filter Node Passed | Filter nodes are checked first. You can set a priority for each individual filter to ensure that certain filters are checked before others when at the same point in the flow. The first passing filter with a green output connection is followed to the next node. Important: Filters are given first priority as the success or failure of a filter may be intended for further processing the flow and not conducting immediate action. |
| 3 | Filter Node Failed | If no filters pass, RevCent will then check any filter nodes for red outputs with connection(s) to other nodes, following filter priority. If any of the failed filter nodes have a connecting red output, then the red connection is followed to the next node. Important: Filters are given first priority as the success or failure of a filter may be intended for further processing the flow and not conducting immediate action. |
| 4 | Action Node | If no filters passed and none of the failed filters have red outputs connecting to further nodes, then the first available action node is considered the next node. |
| 5 | No Next Node | If RevCent does not find a next node, the payment flow ends and any failed payment attempt(s) are returned to the API caller. If payments have been attempted and declined, a decline response will be returned. If no payment attempts have been made, a generic error will be returned. |
¶ Flow Process Scenarios
Below are scenarios with explanations of how nodes would be processed. Of course there are different business needs and requirements users may have, and the payment flow builder may be confusing. If you need help building your flow, feel free to contact us.
¶ Filter Output Routing
Below shows an example in which you want to:
- Route USD payments and a specific BIN to one pair of gateways.
- Route EUR payments to another pair of gateways
- If not USD + BIN, and not EUR, then route to another pair of gateways.
- The Request Type Filter, if passed, connects to a further two filters at the same point in the flow.
- The next point are the two filters: 1. Merge Filters, which combines Currency Filter (USD) and BIN Profile Filter (BIN Profile 42), along with 2. Currency Filter (EUR).
- Notice how both the Merge Filters and Currency Filter (EUR) have a filter priority of zero. This means both will be checked in random order.
- If the Merge Filters passes, i.e. the currency is USD and the BIN of the card being process is contained in BIN Profile 42, then the next node is the Choose Gateway node for Braintree and Checkout.com.
- If the Currency Filter (EUR) filter passes then the next node is the Choose Gateway node for Adyen and Worldpay.
- If both the Merge Filter and Currency Filter (EUR) fail, which means it is neither USD+BIN Profile 42 nor EUR, the red output for the Merge filter will be followed, as there is a red output connection. In this case the next node is the Choose Gateway node for Authorize.net and Stripe.
- All three Choose Gateway nodes output to a single process payment node.
¶ Multiple Filters With Priority
Below is an example if you wanted to route to different gateways depending on the number of payment attempts for a sale. You want to:
- Send the first payment attempt to Authorize.net.
- Send the second payment attempt to Adyen.
- Send the third and any additional payment attempts to Braintree.
- The Request Type Filter, if passed, connects to a further three filters at the same point in the flow.
- The next point in the flow are the three attempt count filters. There is a priority set for each attempt count filter. The lowest number priority is checked first.
- The less than or equal to 1, with a priority of 0, is checked first, which is telling RevCent that the very first payment attempt should be sent to Authorize.net.
- The greater than or equal to 3, with a priority of 1, is checked second, which is telling RevCent that for the third and any additional payment attempts, send to Braintree.
- The greater than or equal to 2, with a priority of 2, is checked last, which is telling RevCent that only for attempt two send to Adyen.
- Notice how we prioritized the order to ensure that the greater than or equal to 2 filter node is checked last, ensuring that only attempt two would succeed for that last node. The greater than or equal to 3 filter node would catch attempt three and above thus never having attempt three hit the greater than or equal to 2 filter node in the filter priority.
¶ Filter Decline Routing
Below is an example if you wanted to take to different actions when a payment is declined, depending on the decline response, utilizing filters to parse a gateways' response.
- If declined with a response containing “insufficient funds” or “stolen card”, then abort the flow and return the decline.
- If declined with a response containing “3DS required”, send to Authorize.net.
- If the decline response does not contain any of the terms, send to Braintree.
- The first process payment node has a red output for routing if declined. If the first payment node was successful, then the success response would be immediately returned. For this example we are assuming that the payment was declined.
- We first want to check if the gateway response contained either “insufficient funds” or “stolen card”. We use the Gateway Response filter to check both terms separately, if any match we route the green output for that node to the Abort Flow node. The abort flow node will send back the original decline response from the first process payment node.
- Next we check if the response contained “3DS required”, and if there is a match we route to a Choose A Gateway node with a single gateway of Authorize.net.
- If none of the terms “insufficient funds”, “stolen card” or “3DS required” are in the response then RevCent will follow the first red output in the filter list. In this case the only red filter output goes to a Choose A Gateway node with a single gateway of Braintree.
- RevCent always checks for any passed filters first, then checks if any failed filters have a red output connected to further nodes. Read the Next Node Determination section for more detail on how RevCent determines the next node to follow.
¶ Function Decline Routing
Below is an example if you wanted to take to different actions when a payment is declined, utilizing a function to parse a gateways' decline response. The proceeding output to be taken is determined by a Run Function nodes' function response. The flow will send a request to a specific function, waiting for the function to return and proceeding according to the function response. Read more about the Run Function node, including the event data a function will receive as well as the proper function output required.
For brevity, we will assume the function code parses the event data, and will determine one of three possible outcomes:
- The flow should be aborted.
- A specific gateway should be set and then payment processed.
- In case of an error, a gateway should be chosen by the flow.
- The first process payment node has a red output for routing if declined. If the first payment node was successful, then the success response would be immediately returned. For this example we are assuming that the payment was declined.
- We want to trigger a function and use the functions response to determine the next action to take.
- If the functions' response object is
{"next_node_id": “43965f05-887a-4e70-8646-0410440a3494”}then the flow will know to route to the next node matching that ID. In this case it would be the Abort Flow node. - If the functions' response object is
{"set_gateway_id": “bOLjn0yvKpUp10qK298R”, "next_node_id": “f96f16ba-2cab-4ae5-9932-4f548cd479ba”}then the flow will know to set the current steps' gateway to the gateway ID returned, and then route to the next node matching that ID. In this case it would be the Process Payment node. - If the functions' response object is
{"next_output": “2”}then the flow will know to proceed using the second (red) output and choose any qualifying nodes along the output_2 path. - As a failsafe in case of an error or function timeout, we always want to have the nodes' error output set to continue on an acceptable path. In this case we have the error output proceeding to the Choose Gateway node, which ensures a gateway will be selected and payment retried.
¶ Additional Profile Settings
There are additional settings within the Next-Gen payment profile. These additional settings are given precedence over the payment flow. I.e. if these settings are triggered, the payment flow either stops or does not begin at all.
¶ Kill Terms
You have the ability to cancel the payment profile flow if a declined transaction has specific terms/phrases/words in a step gateways' decline response. This will also cancel/void the related sale being attempted. Note: Only applies to initial sale attempts, not renewals or trial expirations.
For example, if a gateway declines a transaction, and the gateways' decline response contains the words “pick up card”, you can add the term “pick up card” to your list of kill terms, which will stop the payment flow, kill the sale, and prevent any future purchase attempts for the specific sale.
RevCent does not remember a customers history related to kill terms. For example, if a customer attempts Sale #1, gets declined with a matching kill term, Sale #1 will be cancelled/voided. If the same customer creates a completely new sale, i.e. Sale #2, previous sale cancellations such as Sale #1, will not carry over and automatically cancel Sale #2.
Important: Any kill terms entered that match a term within a gateways' decline response will immediately stop the payment profile flow and cancel/void the related sale. Kill terms are meant to match specific decline reasons, thus preventing further payment attempts and pending sale recovery. If you enter a basic kill term, such as “the” or “and”, you will most likely kill all declined sales.
¶ Max Attempts
You have the ability to cancel/void a sale if the number of declined payment profile attempts reaches a certain number. Only applies to initial sale attempts, not renewals or trial expirations.
Note: A payment profile attempt is the considered to be the completion of all steps within a payment flow and not an individual step within a flow. I.e. an attempt is the entire flow itself.
Example: If you have 3 steps within a flow, and you set max attempts to 3, then it will take 9 declines for the max attempts to be reached.
¶ For Developers
The Next-Gen payment profile offers custom error responses as well the ability to process decline responses. This section is intended to help developers integrate error messages and display specific messages to visitors attempting to check out.
Please make sure that the shopping cart server is able to process the Custom Error Message scenario below.
¶ Custom Error Message
When a RevCent user is processing a payment using a Next-Gen profile, they have the option to abort payments attempts and return a custom response of their own. Depending on whether a payment was declined, or not attempted at all, there are two types of custom errors that may exist in the API response. These custom error types do not always exist, so please validate and check if exists or not.
There are two types of custom errors:
- Where code is not 1 and a non-empty
custom_erroris present. Payment was declined. - Where code is not 1,
“error_code”: “E0690”exists and a non-emptymessageproperty is also present. No payment was attempted
¶ Custom Error - Payment Declined
It is recommended that in cases where code is not 1 and a RevCent API response has a non-empty custom_error property, display the customer the custom_error.
Example API Response:
{
"api_call_date": "2023-10-19T23:58:08+00:00",
"api_call_id": "k6wEkpq5GLHLJBV6JQvk",
"api_call_unix": 1697759888,
"code": 2,
"payment_profile_results": [...],
"custom_error": "This is a non-E0690 custom error message returned by the Next-Gen profile."
}Notice:
- Response code is not 1.
- The “custom_error” property is present and non-empty.
In the case above where both are true, the contents of the custom_error should be displayed to the customer.
¶ Custom Error - E0690 - Payment Not Attempted
It is recommended that in cases where code is not 1, the API response has “error_code”: “E0690” and a non-empty message property, display the customer the message property.
Example API Response:
{
"api_call_date": "2023-10-19T23:58:08+00:00",
"api_call_id": "k6wEkpq5GLHLJBV6JQvk",
"api_call_unix": 1697759888,
"code": 0,
"error_code": "E0690",
"message": "This is a custom error message returned by the Next-Gen profile."
}Notice:
- Response code is not 1.
- The “error_code” property equals “E0690”.
- The “message” property is present and non-empty.
In the case above where all are true, the contents of the message property should be displayed to the customer.