Fraud Prevention

Supported Implementations

There are two types of integration that Alacrity can support with our Fraud Prevention API.

- Single Page Integration

This is our standard integration. You will need to add our JavaScript to your payment page and capture the token you receive on page submission. Please follow the guidelines below for integrating:

Step-by-step Guidelines

1. Implement the following JavaScript onto your payment page. This will typically be the page were the PIN is entered.
2. Retrieve the token once your payment page has been submitted.
3. Check the token with our Check Transaction API and ensure the token is valid to continue.
4. Pass the valid token as fraud_token into our Create API or One Off Charge API depending on what type of service you are integrating.

📘

Note

In step 1 for Libyana & Almadar, the JavaScript required to load in the first page before triggering our PIN API. This will typically be the page were the MSISDN is entered.

A valid token should be passed into both of our PIN API and Create API.

- Dual Page Integration

📘

Note

This integration is currently is only supported for Mobily KSA, Yettel Bulgaria, Yettel Serbia services, and subscription services for Ireland operators, and is a requirement for those operators.

Please follow Single Page Integration if this does not apply to your service.

You will need to add our JavaScript to two of your pages, and capture the token on page submission of each page. You will be required to add the token you received from the first page, into the JavaScript of the second page. Please follow the guidelines below for integrating:

Step-by-step Guidelines

1. Implement the following JavaScript onto your page before your payment page. This will typically be the page MSISDN is captured.
2. Retrieve the token once your pre-payment page has been submitted.
3. Pass the token as fraud_token into our PIN API
4. Implement the JavaScript onto your payment page, ensuring to include the token retrieved from the previous page. This will typically be the page were the PIN is entered.
5. Check the token with our Check Transaction API and ensure the token is valid to continue.
6. Pass the valid token as fraud_token into our Create API or One Off Charge API depending on what type of service you are integrating.

Implementing our JavaScript

You can use the following JavaScript for both Single Page Integration and Dual Page Integration.

Add the JavaScript to the head section of your page.

JavaScript

<script src="https://fd.sla-alacrity.com/d513e9e03227.js"></script>

You then need to retrieve a token that is associated with this visitor and checkout. You do this by calling Detector(ids, partner, service, token) once the page has loaded.

Our JavaScript will insert an HTML element with the id fraudDetectorIsLoaded so that you can check that everything has loaded before submitting your form. Once loaded our JavaScript will also add a hidden input to your form with the name token and the value equal to the returned token. This token will be used within subsequent API calls, and if this is a dual page integration, must be included in the JavaScript when loading your next page.

Below is a full example using vanilla JavaScript of initialising the Detector, adding a listener to your form, checking that fraudDetectorIsLoaded*, and then submitting your form (with the hidden token field).

Example Script

window.onload = function () {
    var ids = {
      form: 'purchase_form',
      confirm_button: 'form_submit_btn',
      cancel_button: 'form_cancel_btn',
      pin_input: 'pin_input',
      msisdn_input: 'msisdn_input' //  Note: This input will only apply to dual page integrations
    };
    var partner = 'partner:h7j9w4n8-97a4-4eb7-9ec1-4333131805cb';
    var service = 'campaign:2a73f22ed63c1f8e40925632b7n10w6fed611779';
  
    // For Dual Page Integrations only
    // Ensure to put the value of fraudToken in from the token retrieved from your pre-payment page 
    var fraudToken = null;
  
    var optionals = {
    	correlator: 'ABC123',
    	env: 'production'
     }

    const detector = new Detector(ids, partner, service, fraudToken, optionals);
    detector.setup();

    var form = document.getElementById(ids['form']);
    form.addEventListener("submit", function(e) {
      e.preventDefault();

      function fraudDetectorLoaded() {
        var loaded = document.getElementById('fraudDetectorIsLoaded');
        if (loaded && loaded.value === 'yes') {
          form.submit();
        } else if ('requestIdleCallback' in window) {
          requestIdleCallback(fraudDetectorLoaded);
        } else {
          setTimeout(fraudDetectorLoaded, 100);
        }
      }
      fraudDetectorLoaded();
    });
  }

📘

Note

For Mobily KSA services, it is required for you to remove the "window.onload = function () { }" event.

As it is a requirement for the script to be loaded before the rest of the page has loaded.

Check Transaction API

Once the user has submitted your payment form you need to check the token with our Check Transaction API.

This API will check the token and return whether the user/purchase is valid or not.

HTTP Request

POST /v1/check_transaction?token={token}

Sample Request

POST /v1/check_transaction?
token=2e056a61-18d0-41c7-93d1-94f07bf9cf0a
Host: fd.sla-alacrity.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

curl -X POST \
https://fd.sla-alacrity.com/v1/check_transaction?token=2e056a61-18d0-41c7-93d1-94f07bf9cf0a \
--header 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='

Response

The response is returned as JSON and also uses HTTP status codes.

When the status code is 200 the response will contain the key is_valid which is a boolean and indicates whether or not the transaction is valid and if the purchase should be allowed.

{
  "is_valid": true
}

200

If a transaction is blocked for being suspicious is_valid will be false and there will be a reason returned.

{
  "is_valid": false,
  "reason": "BOT_ACTIVITY"
}

200

It's also possible to receive other errors via the HTTP status codes such as 400, 401, and 404. In this case there will be a JSON response returned in the body with the key message.

{
  "message": "auth error: invalid credentials"
}

401

Unless you receive a HTTP status of 200 and is_valid is true the purchase should not be allowed to continue.