Getting Started

Ravelin provides a means of adding cards to Ravelin without having to handle PCI-compliant data. The library is intended to work on web pages where you have access to the PAN that the customer has entered. Passing through the encrypted values provided by this library avoids your servers handling any sensitive data, helping reduce the scope of your PCI compliance.

This is achieved through our publically available ravelinjs library which is responsible for performing the client-side encryption, as well as loading in Ravelin’s device tracking and session tracking functionality.

We recommend using ravelinjs in scenarios for which you are currently using the client-side encryption or client-side tokenisation features provided by your payment gateway. For scenarios in which payment details are captured with in an iframe or a hosted payment form that contains iframe inputs, ravelinjs will not have access to the card details, and no effort should be made to attempt to circumvent the addition security these iframes provide.

Loading ravelinjs

The ravelinjs library can be used as a dependency in AMD modules; imported into scripts bundled using webpack; or by dropping a <script src="ravelin.min.js"> into your web page.

Examples:

Encrypting Cards

The primary goal of ravelinjs is to allow the secure sharing of card information with Ravelin without handling PCI-compliant data. When collecting the card details, encrypt the values to send to Ravelin using ravelinjs.encrypt({pan, month, year, nameOnCard}). pan, month, year are required, while nameOnCard is optional, and no other properties are allowed on the object. Validation is performed, confirming that expiry dates are valid, the PAN is at least 13 characters, and that no addition fields are present. Should any validation checks fail, an exception is raised.

Tracking Page Activity

Using ravelinjs, the setPublicAPIKey (called immediately), track, and trackPage (call on page load) can be used instead of the snippet shown in Device Tracking. See the example below for more information.

Example

In the following form, we collect card details from the customer, encrypt them and send the encrypted values (the cipher) back to your server.

<!-- Browser -->
<form id="form-payment-card">
    Card Number: <input name="pan" />
    CVV: <input name="cvv" />
    Name: <input name="nameOnCard" />
    Month: <input name="month" />
    Year: <input name="year" />
    <input type="hidden" name="ravelinCipherText" />
    <input type="submit" />
</form>

<script src="ravelin.min.js"></script>
<script>
    // Tracking.
    ravelinjs.setPublicAPIKey("pk_live_...");
    ravelinjs.trackPage();

    // Encryption.
    ravelinjs.setRSAKey("..|.....")
    document.getElementById('form-payment-card').onsubmit = function() {

        this.ravelinCipherText.value = ravelinjs.encrypt({
            pan: this.pan.value,
            month: this.month.value,
            year: this.year.value,
            nameOnCard: this.nameOnCard.value,
        });

        // Avoid sending sensitive data to your server.
        this.pan.value = this.cvv.value = this.name.value = '';
    };
</script>

Once the cipher is received by your server, the API request to Ravelin in which a fraud recommendation is requested should use this cipher value:

/* Server-side */

var card = JSON.parse(form.getValue('ravelinCipherText'));
var action = request("https://api.ravelin.com/v2/checkout?score=true", {
    // ...
    "paymentMethod": card,
});

For more detailed information on using ravelinjs, please refer to the ravelinjs github repository or speak to a Ravelin engineer.