Risk Management Service

Reduce your risk of fraud and prevent expensive chargebacks!

Online shopper fraud is on the rise, impacting your bottom line in more than one way. Consider, for instance, the loss of revenue due to chargebacks issued for unauthorized transactions; or the dollars lost to transactions that are wrongly declined due to suspected fraud ("false positives"). Not to mention that exposure to fraud significantly harms your trust and reputation.

Combating online fraud while striking the right balance in doing so, is thus important to your bottom line. The PaymentsOS Risk Management Service allows you to do just that. How you use the service is up to you:

  • As a 'standalone' service. Simply get a risk score for the transaction and use the score in your own business logic.

  • Embedded in your PaymentsOS payment flow. Once you have the score and recommendation, either reject the transaction or proceed to the next step in your payment flow.

Availability Information

The PaymentsOS Risk Management Service is currently available in Latin America only. If you are interested in using the service in other regions, please contact us at support@zooz.com.

Configuring the Fraud Prevention Service

Before you can use the Fraud Prevention Service, you must configure it in your PaymentsOS Control Center account. The first step is to add a new Provider Configuration, dedicated to the Fraud Prevention Service. In the PaymentsOS Control Center, choose Account > Services and search for PayU-Risk to find the service.

Payment Flow

In the Provider Configuration settings, specify the tenant ID you received from your account representative. In the region field, enter latam.

With the Provider Configuration in place, proceed to add a new Business Unit for the configuration you created (as you would do for any other provider configuration). This Business Unit will be dedicated to handling requests submitted to the Fraud Prevention Service API, so make sure to note down the Business Unit's App ID since you will need it when invoking the Risk Analyses API requests in the examples that follow.

Performing a Fraud Risk Analysis

When you perform a fraud risk analysis, the result will be a fraud risk score and a recommendation to either approve or reject the transaction. Regardless of how you use the service (standalone or embedded in your PaymentsOS payment flow), the risk analysis is always performed on an initiated payment request. The first step in getting the risk score is thus a call to the Create Payment API.

Passing Line Items in the Create Payment Request

If you pass an order.line_items object in the Create Payment, the object must also include a unit_price field. You will receive an error when performing a new risk analysis, if the unit_price field was not included.

You can then initiate the risk analysis for the payment that was initiated, by invoking the Perform a Risk Analysis request for the specific payment ID and passing the customer's payment method in the request body. Optionally, you can also include a provider_specific_data object with additional_details about the order. Here's an example:

JavaScript
curl
var request = new XMLHttpRequest();
request.open('POST', 'https://api.paymentsos.com/payments/{payment_id}/risk-analyses');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('api-version', '1.3.0');
request.setRequestHeader('x-payments-os-env', 'test');
request.setRequestHeader('app-id', 'com.zooz.docapp');
request.setRequestHeader('private-key', '0047c4ef-f658-4e6d-a040-5882e2285f34');
request.setRequestHeader('idempotency-key', 'cust-34532-trans-001356-c');
var body = {
    {
        "transaction_type": "charge",
        "payment_method": {
            "holder_name": "John Travolta",
            "card_number":"5105105105105100",
            "type":"untokenized",
            "source_type": "credit card"
        },
          "provider_specific_data": { // Optional object for passing more information about the order
            "payu_risk": {
              "additional_details": {
                "product_desc_extra1": "product_desc_extra1",
                "product_desc_extra2": "product_desc_extra2",
                "product_desc_extra3": "product_desc_extra3",
                "payer_birthday": "1975/06/30"
              }
            }
          }
    }
};
request.send(JSON.stringify(body));
curl --compressed -X POST \
  https://api.paymentsos.com/payments/{payment_id}/risk-analyses \
  -H 'Content-Type: application/json' \
  -H 'api-version: 1.3.0' \
  -H 'x-payments-os-env: test' \
  -H 'app-id: com.zooz.docapp' \
  -H 'private-key: bede7ee5-eaaq-4c9a-bc1f-617ba28256ae' \
  -H 'idempotency-key: cust-34532-trans-001356-p' \
  -d '{
    {
        "transaction_type": "charge",
        "payment_method": {
            "holder_name": "John Travolta",
            "card_number":"5105105105105100",
            "type":"untokenized",
            "source_type": "credit card"
        }
          "provider_specific_data": { // Optional object for passing more information about the order
            "payu_risk": {
              "additional_details": {
                "product_desc_extra1": "product_desc_extra1",
                "product_desc_extra2": "product_desc_extra2",
                "product_desc_extra3": "product_desc_extra3",
                "payer_birthday": "1975/06/30"
              }
            }
          }
      }
}'

Passing Additional Order Details?

If you pass additional_details, make sure the object only includes the fields shown in the example above. Also make sure that additional_details.payer_birthday has the following format: yyyy/mm/dd.

At what stage should you perform the risk analysis?

The stage at which you should perform the risk analysis, depends on how you use the Fraud Prevention Service:

  • If you use the service standalone, then the stage at which you can run the risk analysis depends on your own business logic. For instance, you could first authorize the transaction and run the risk analysis afterwards.

  • If you embed the service in your PaymentsOS payment flow and your flow has separate Authorization and Capture steps, then you can choose to perform the analysis after invoking the Create Authorization request. The Risk Management Service will then take the authorization result into account when assessing the risk of the transaction. If your payment flow uses a Charge request to authorization and capture the payment in a single step, then perform the risk analysis right after calling the Create Payment request.

Interpreting the Risk Analysis Result

The response of the Perform a Risk Analysis request will include a provider_data.risk_analyses_result object, with a score and a decision field. The decision is a recommendation of how to proceed with the transaction and can either be approve, review or decline:

{
  ...  
  "provider_data": {
    "external_id": "string",
    "additional_information": {},
    "risk_analyses_result": {
      "score": 896,
      "decision": "approve"
    }
  }
  ...
}

If the decision is approve, proceed to the next step in the payment flow. Depending on the moment at which you performed the analysis, this step can be a Create Authorization, Create Charge or a Create Capture request.

If the decision is review, we will manually review the transaction request and approve or reject the transaction accordingly. Make sure to be on the lookout for a change in the decision, before proceeding with the next steps in your transaction flow.

results matching ""

    No results matching ""