Optimizing Payments
Payment Processing Rules Overview
PaymentsOS provides an extensive list of rule criteria to select from. Rules may, for instance, route payments to a specific provider depending on the currency in which the payment was made, direct payments to yet another provider based on the customer’s card brand, block a payment based on the country where the card was issued, and so forth.
To configure payment processing rules, login to the PaymentsOS Control Center, choose Decision Engine from the left menu and select a business unit. Then scroll down to Optimise your payment flow and choose a rule policy. A rule policy represents the type of rule you can configure:
-
Payments Routing: Allows you to configure rules that route payments to specific providers based on the conditions specified.
-
Block Payments: Allows you to configure rules that prevent unwanted transactions from reaching providers, blocking payments based on the conditions specified.
-
Instant Retry: Allows you to configure rules that reroute a payment to another provider, in the event that a provider receiving a transaction request failed to process the payment.
Notes
-
You can create up to 75 payment processing rules (the total number of routing, block and instant retry rules combined).
-
You should not implement instant retry rules for transaction flows that involve 3DS authentication. 3DS is a step introduced to authenticate the user, so it should occur only once.
PaymentsOS combines the rules you configured to form a decision flow (you can configure one decision flow per business unit). Under the hood, PaymentsOS uses its Decision Engine to evaluate the rules in the decision flow and process each payment accordingly. This introduces some additional considerations that you need to be aware of.
Rules for Alternative Payment Methods
By default, rules for handling payments are only applied to card payments. If you want to apply a rule to transactions using alternative (non-card) payment methods, then make sure to apply an Alternative Payment Method condition and select the alternative payment method for which to apply the rule. Of course, you need to make sure that the rule’s target provider supports the alternative payment method that you select.
Not all alternative payment methods are currently supported
We currently do not support routing for all types of alternative payment methods (though we are continuously extending support for additional ones). If the alternative payment method for which you want to configure a rule is not available for selection in the Alternative Payment Method condition, then you will need to create a separate business unit with a default provider dedicated to handling the payment method used in the transaction.Constructing a “One Size Fits All” Request Body
The outcome of a rule may result in a payment being routed to any of the providers configured to be used in the decision flow. When constructing a request body, you must thus ensure that you include all fields required by the providers to which a payment may be routed. This may seem like a daunting task, but do not despair! Hop over to our Bodybuilder, select the providers of your choice and generate a “one size fits all” request body with just a single click of the mouse.
Creating Policy Rules based on Custom Data
While PaymentsOS covers a range of rule conditions designed to meet the most common decision flow scenarios, you may also want to define rules based on information you provided to enrich your customers' transaction data. This is where rule conditions based on additional details come into play. It offers you the ability to create custom-fit decision rules, using virtually any type of data available to you.
Configuring Rules based on Additional Details
When adding a new rule to your rule policy, choose Add Condition > Additional Details.If you are familiar with our APIs, you may recall that you can enrich transaction data by passing additional information in the additional_details
object of some of our API requests. Here’s an example of additional information passed in the request body of a Create Customer request.
...
{
"customer_reference": "cust_john",
"first_name": "John",
"last_name": "Taylor",
"email": "John.Taylor@gmail.com",
"additional_details": {
"user_status": "banned_user"
},
...
Notice the key (user_status
) and value (banned_user
) passed in the example above. Use these in the key and value fields respectively, when configuring your rule:
When creating a condition using the custom data you provided, you can select from the following additional details:
-
Customer Additional Details: Additional information passed in a Create Customer request.
-
Payment Additional Details: Additional information passed in a Create Payment request.
-
Payment Method Additional Details: Additional information passed in a Create Payment Method request.
-
Transaction Additional Details: Additional information passed in a Create Authorization or Create Charge request.
Routing Transactions Coming from the Virtual Terminal
The Virtual Terminal allows you to initiate a payment on behalf of a customer and charge your customer on-the-fly.
Transactions coming from the Virtual Terminal are treated as any other transaction and may thus be routed to any of the providers defined in your business rules. However, some providers require customers to authenticate themselves, or require that you submit specific information (provider-specific data) for the transaction to go through. In this case, the Virtual Terminal will return a message indicating that the transaction could not be completed. You can prevent this from occurring, by creating a route rule that directs payments coming from the Virtual Terminal to a provider that does not require user authentication or provider-specific data.
To route transactions initiated from the Virtual Terminal, create a Payments Routing rule based on Transaction Additional Details. Set the key to vt and the String value to true.
Routing Transactions to a Provider Supporting External 3DS
If you use an external MPI (merchant plug-in) to authorize a card using 3D Secure, then you can pass the 3DS data returned from the MPI in the three_d_secure_attributes.external
object of a Create Authorization or Create Charge request. However, not all the providers you transact against may be able to receive this data. You should thus configure a route rule to direct the request to a provider that can process data received from an external 3DS service.
Finding a provider that supports external 3DS
See Finding a Provider to find a provider that supports external 3DS (choose a payment method type of Cards and apply an additional filter by choosing a 3DS External version from the Features list). Make sure to review the provider’s setup procedures in the relevant provider topic, since some additional configuration may be required.To route a transaction to a provider that supports data from an external 3DS service, you must first pass a custom key-value pair in the additional_details
object of a Create Authorization or Create Charge request. Note that you can choose any key-value pair of your liking (in the example below, we pass a key of external_mpi_3ds_results
with a value of true
):
{
"payment_method": {
...
},
...
"three_d_secure_attributes": {
"external": {
"three_d_secure_version": "1.0.0",
"cavv": "Unqiue CAVV",
"eci_flag": "ECI associated with the transaction.",
"encoding": "BASE64",
"xid": "transaction ID"
},
"additional_details": {
"external_mpi_3ds_results": "true"
}
}
}
You can now create a Payments Routing rule based on Transaction Additional Details. Set the key to your custom key (external_mpi_3ds_results
in the example above) and the String value to your custom value (true
in the example above).
Routing Transactions to the Next Provider if the Target Provider is not Available
If PaymentsOS detects that the target provider is not available, then you can instruct the Decision Engine to skip the current rule and move on to the next rule in line. To do so, simply switch the Skip to next rule if target provider is down toggle.
Disclaimer
Under the hood, PaymentsOS invokes the Retrieve Health Status API request to determine the availability status of your providers. The status is a representation of the availability of your providers and is calculated by PaymentsOS based on various parameters, such as the frequency of transaction requests invoked through PaymentsOS and the number of provider responses received within a given time frame. The status therefore only reflects the availability status of your providers within the scope of PaymentsOS and is not indicative of their availability outside that scope.Understanding the decision_engine_execution
Resource
If policy rules have been configured, the response of a Create Authorization or Create Charge request will also include a decision_engine_execution
object. This object contains information about the decision flow and the rules that were evaluated as payments pass through the flow:
{
...
"decision_engine_execution": {
"id": "a66d524c-aca6-4218-9170-f7d2c2051d1e-462f-40b3-a1f3-ee4b768f338e",
"created": "1533737775251",
"flow_id": "8db806df-fd3f-42a4-a710-81f8a777df18",
"status": "InProgress",
"policy_results": [
{
"type": "BlockPolicy",
"name": "my-block-policy",
"execution_time": "2018-08-08T14:16:15.249Z",
"result": "Hit"
}
]
}
Note
Refer to to the REST API Reference for an explanation of the fields in thedecision_engine_execution
object.
As each rule is evaluated, a corresponding policy result object is created in the policy_results
array. This object summarizes the evaluation of the rule. The policy result object’s type
field indicates the policy to which the rule belongs. Notice that the type
corresponds to the policy that can be selected when configuring a rule in the PaymentsOS Control Center. The only exception is the target_policy
type. This type is created by the Decision Engine the moment the payment is passed on to a provider (the “target” of the rule).
The example below shows a policy_results
array with result objects of multiple types.
"policy_results": [
{
"name": "My Block Policy Rule",
"execution_time": "2018-08-14T08:09:07.525Z",
"result": "Hit",
"type": "BlockPolicy"
},
{
"name": "My Route Policy",
"execution_time": "2018-08-14T08:20:06.527Z",
"result": "Hit",
"provider_name": "CyberSource",
"provider_configuration": "https://api.paymentsos.com/accounts/my_app_1534320543208/providers-configurations/eba3accc-0f82-48c2-9a3c-10de48a322bb",
"transaction": "https://api.paymentsos.com/payments/e8847624-9b2e-4eb6-bc3c-33b946d48502/charges/63f56afb-b612-4bdf-8f87-638b56cfd5e1"
},
{
"name": "TargetPolicy",
"execution_time": "2018-08-14T08:21:00.522Z",
"result": "Hit",
"provider_name": "CyberSource",
"provider_configuration": "https://api.paymentsos.com/accounts/my_app_1534320543208/providers-configurations/eba3accc-0f82-48c2-9a3c-10de48a322bb",
"transaction": "https://api.paymentsos.com/payments/e8847624-9b2e-4eb6-bc3c-33b946d48502/charges/63f56afb-b612-4bdf-8f87-638b56cfd5e1"
}
]
Interpreting the Request Status when a Block Rule is Applied
A block rule blocks payments based on the conditions specified. When a payment is blocked on an Authorization or Charge request, the request will return a result
object that includes a status
field with a value of cancelled
and a category
field with a value of blocked_by_decision_engine
. Here’s a sample result
object returned by a Retrieve Authorization request:
...
"result": {
"status": "Cancelled",
"category": "blocked_by_decision_engine",
"description": "A Block Rule was applied to this transaction. You can view and modify your Block configuration in the Control Center."
},
...
Configuring Instant Retry Rules
Instant retry rules are rules that reroute a transaction to another provider to reattempt the transaction, in the event that a provider receiving the transaction request failed to process the payment. In the most basic configuration, all you need to trigger an instant retry rule is to setup a source provider and a target provider. The source provider is the provider receiving the initial transaction request; the target provider is the provider to which the transaction will be rerouted.
Important Note
- Instant retry is not available for transaction flows involving 3DS authentication, as 3DS is a step introduced to authenticate the user, so it should occur only once.
- Transactions conducted with alternative payment methods and payments made on PayU’s hosted page cannot utilize instant retry either.
When will my rule trigger?
That depends on your configuration. If you define just a source and target provider, PaymentsOS will trigger your rule when a technical error (such as an authentication error) occurs at the source provider. You can also instruct PaymentsOS to trigger a rule if the transactions was declined for financial reasons (such as decline by the acquiring bank); and you can add conditions filters to further refine the conditions for a rule to trigger.
Notes
We recommend you define condition filters to refine the reasons for a rule to trigger. Relying only on a configuration of a source and target provider may result in unnecessary retry attempts and a higher number of declines, causing a drop in approval rates (and a frown on the face of the card schemes) in return.Bear in mind that whether a rule will trigger does not solely depend on each of the available configuration options separately; how you combine the options is important as well. The following table lists the options available to you and explains how they work together in determining the reason for a rule to fire off.
With this configuration: | The rule will trigger: |
---|---|
Source and Target Provider only | When a technical error (such as an authentication error) occurs at the source provider. |
The Retry on financial declines toggle is switched on | When either a technical error or a financial decline occurs at the source provider. A technical error includes, for example, an authentication error. A financial decline includes, for example, a rejection of the payment by the card holder's issuing bank. Note that PaymentsOS will only reattempt to process the transaction with another provider if it makes sense to do so. For instance, PaymentsOS will not reroute the transaction request if the transaction was declined due to insufficient funds, or if the card was identified as lost or stolen. |
A condition filter is applied | When the payment is rejected due to either a technical error or a financial decline (see the explanation above) and the specified condition is met. Beware that different considerations apply if you add an error category or error subcategory condition filter (both are explained below). |
An error category condition filter is applied | When an error occurs that PaymentsOS identifies as belonging to the specified category, but for which the exact reason was not provided. For example, the payment method may have been declined but the details are not available. Important note: If you add an error category filter and PaymentsOS identifies a more specific decline error, then the rule will not trigger. |
An error subcategory condition filter is applied | When an error occurs that PaymentsOS identifies as belonging to the specified subcategory. This condition filter is more specific than the error category filter. Important note: This rule will only trigger if the specific decline error (such as a declined_by_issuing bank) occurred. The rule will thus not trigger if the error is more generic (such as payment_method_declined). |
You cannot combine all
You can add either an error category filter or an error subcategory filter to the same rule; you cannot add both. If you want the rule to trigger in both the event of a more general decline reason (error category), as well as in the event of a more specific decline reason (error subcategory), then you’ll need to add two separate rules: one with an error category filter and another one with the more detailed error subcategory filter.
You may also notice that you cannot toggle the Retry on financial declines option when you apply an error category or error subcategory filter. By adding an error category or error subcategory filter, you actually indicate that you want to be more specific about the error that should trigger the rule. We thus disable the Retry on financial declines option accordingly.
Error Category and Error Subcategory Rule Examples
Let’s take a look at some examples.
Example 1: Generic Condition with Specific Response
Your configuration:
- source and target provider
- Condition filter: error category. Condition: payment_method_declined
Response received from the source provider: declined_by_issuing bank
Trigger result: The rule will not trigger, as PaymentsOS received a response from the provider that is more specific than the generic condition filter.
Example 2: Specific Condition and Specific Response
Your configuration:
- source and target provider
- Condition filter: error subcategory. Condition: declined_by_issuing bank
Response received from the source provider: declined by issuing bank
Trigger result: The rule will trigger, as PaymentsOS received a response from the provider matches the more specific condition specified in the error subcategory.
Example 3: Specific Condition with Generic Response
Your configuration:
- source and target provider
- Condition filter: error subcategory. Condition: declined_by_acquiring_bank
Response received from the source provider: payment method declined (note: the provider did not return a more detailed response).
Trigger result: The rule will not trigger, as the condition you specified is more specific then the response received from the provider.
Interpreting the Request Status when an Instant Retry Rule is Applied
There are several considerations you must bear in mind when interpreting the status of the transaction request, if you applied an instant retry rule.
Instant Retry Rules with Synchronous Transaction Flows
In the case of a synchronous transaction flow, instant retry rules may result in a delay (of up to 60 seconds) in receiving a response with the status of the request. If you registered webhooks with a synchronous flow, you should also bear in mind that you will receive multiple webhook create
events when instant retry rules are executed:
{
"created": "2018-09-05T06:44:35.484Z", // I tried with the first provider.
"account_id": "961c2dee-d531-4b5f-8550-3de73570e982",
"app_id": "com.zooz.docapp",
"payment_id": "8d3f9e6a-d89b-48bd-9d68-07e1bb582687",
"data": {
"id": "557a4e32-d2e9-495a-9a0b-f2a18c39d91b",
"created": "1536129864640",
...
},
"id": "8d3f9e6a-d89b-48bd-9d68-07e1bb582687-2018-09-05T06:44:35.484Z-83233f6e-767f-4f55-9d8f-448019e90fbf"
},
{
"created": "2018-09-05T06:44:45.484Z", // I tried with a second provider, so here's another webhook event.
"account_id": "961c2dee-d531-4b5f-8550-3de73570e982",
"app_id": "com.zooz.docapp",
"payment_id": "8d3f9e6a-d89b-48bd-9d68-07e1bb582687",
"data": {
"id": "557a4e32-d2e9-495a-9a0b-f2a18c39d91b",
"created": "1536129864640",
...
},
"id": "9d3g9e6g-d99b-48be-9d68-17e1bc583686-2018-09-05T06:44:45.484Z-83233f6e-767f-4f55-9d8f-448019e90fbf"
}
Instant Retry Rules with Asynchronous Transaction Flows
If your flow is asynchronous, you’re most likely using webhook events in order to be notified of a change in a request’s status. Recall that the webhook body also returns the full transaction resource that initiated the event, including the status of the transaction. However, if the status of the transaction is Failed
, you cannot assume that this is the final status since a retry rule may still be applied (in which case the transaction may succeed with the next provider in line).
Here’s a sample webhook body. Notice that the status of Failed
may not be final.
{
"id": "13344450-77e9-45b6-9bbe-88fff8c451e5-2018-10-03T04:58:35.385Z-83233f6e-767f-4f55-9d8f-448019e90fbf",
"created": "2018-10-03T04:58:35.385Z",
"account_id": "961c3ded-d539-4b5f-8950-3de93570e988",
"app_id": "com.zooz.docapp",
"payment_id": "13344450-77e9-45b6-9bbe-88fff8c451e5",
"data": {
"id": "cb615c8f-319d-4349-a276-f4ecc7d770d3",
"created": "1538542712789",
"payment_method": {
...
}
},
"result": {
"status": "Failed" // Wait! An instant retry rule may be applied, so the transaction may still succeed.
},
"provider_data": {
...
},
"amount": 4097
}
}
So as a rule of thumb, if the status of the transaction resource is Failed
, always verify that the status of the decision flow is Completed
before checking the final status of the request itself. Remember that you can find the status in the decision_engine_execution
object of an Authorization or Charge resource:
...
"decision_engine_execution": {
"id": "a66d524c-aca6-4218-9170-f7d2c2051d1e",
"flow_id": "8db806df-fd3f-42a4-a710-81f8a777df18",
"flow_owner_type": "Application",
"policy_results": [
{
"type": "FallbackPolicy",
"name": "my-fallback-policy",
"execution_time": "2018-08-08T14:16:15.249Z",
"result": "Hit"
}
],
"status": "Completed" // The Decision Engine completed its work. You can now safely rely on the status returned by the request itself.
}
Notes
If nodecision_engine_execution
resource has been created (which is the case if no business rules have been defined), then a status of Failed
as returned in the webhook body is final.
Configuring Rules for 3D Secure Authentication
The PaymentsOS-handled 3D Secure authentication flow allows you to run 3D Secure authentication within your Create an Authorization or Create a Charge request. Since the flow is a ‘single-click’ flow, you will need to pre-configure rules that will signal PaymentsOS, which transactions require 3DS authentication and which need to be ruled out from authentication. You will also need to set rules based on the 3D Secure authentication result to signal PaymentsOS to proceed with the authorization.
When will my rule trigger?
Your 3D secure rules will activate automatically after you invoke the Create an Authorization or Create a Charge request, and will activate again after receiving the result of the authentication (granted that you set authentication-based rules as well).
Note
Actively configuring 3D Secure based rules allows the flow to be automatic and ‘hands-free’ after you invoke the API request. If you don’t devise rules to enroll compatible transactions in authentication, PaymentsOS will proceed with the authorization or charge request by default. Additionally, PaymentsOS is set to automatically proceed with the authorization or charge request even if the authentication failed, so you will also need to configure blocking rules to ensure that in case the authentication is not successful, the flow won’t proceed to authorization or charge.To set 3D Secure rules and authentication-based blocking rules, head to your Decision Engine and choose the business unit you wish to configure the rules for. Then, add one or more rules via the 3D Secure and Risk Management section. Blocking rules should be configured via the Block Payments section.