ravelinjs Reference

ravelinjs is our open-source javascript library built to help you send Ravelin information about your customers’ activity while using your site. This includes determining deviceIds, tracking session activity, fingerprinting devices and providing client-side encryption functionality for acquiring encrypted card details.

ravelinjs.setPublicAPIKey(apiKey)

setPublicAPIKey sets the API Key used to authenticate with Ravelin. It should be called before anything else. You can find your publishable API key inside the Ravelin dashboard.

Parameters

Name Type Description
apiKey String Your publishable API key  

Examples

ravelinjs.setPublicAPIKey('live_publishable_key_abc123');

Returns

  • Void

ravelinjs.setRSAKey(rawPubKey)

setRSAKey configures ravelinjs with the given public encryption key, in the format that Ravelin provides it. You can find your public RSA key inside the Ravelin dashboard.

Parameters

Name Type Description
rawPubKey String The public RSA key provided by Ravelin, used to encrypt card details.  

Examples

ravelinjs.setRSAKey('10010|abc123...xyz789');

Returns

  • Void

ravelinjs.setCustomerId(customerId)

setCustomerId sets the customerId for all requests submitted by ravelinjs. This is needed to associate device activity with a specific user. This value should be the same that you are providing to Ravelin in your server-side API requests. If this value is not yet know, perhaps because the customer has not yet logged in or provided any user details, please refer to setTempCustomerId instead.

Parameters

Name Type Description
customerId String customerId unique to the current user  

Examples

ravelinjs.setCustomerId('123321');

Returns

  • Void

ravelinjs.setTempCustomerId(tempCustomerId)

setTempCustomerId sets the tempCustomerId for all requests submitted by ravelinjs. This is used as a temporary association between device/ session data and a user, and should be followed with a v2/login request to Ravelin as soon as a customerId is available.

Parameters

Name Type Description
tempCustomerId String A placeholder id for when customerId is not known  

Examples

ravelinjs.setTempCustomerId('session_abcdef1234567'); // a session id is often a good temporary customerId

Returns

  • Void

ravelinjs.encrypt(details)

encrypt performs the encrypt process for the provided card details and prepares them to be sent to Ravelin, with the resulting payload returned as a string.

Parameters

Name Type Description
details Object An object containing properties pan, month, year and nameOnCard (optional).  

Examples

var encrypted = ravelinjs.encrypt({pan: "4111 1111 1111 1111", month: 1, year: 18});
console.log(encrypted);
> '{"methodType":"paymentMethodCipher","cardCiphertext":"abc.....xyz==","aesKeyCiphertext":"def....tuv==","algorithm":"RSA_WITH_AES_256_GCM","ravelinSDKVersion": "0.0.1-ravelinjs"}'

Returns

  • String The encrypted payload to be sent to Ravelin.

ravelinjs.encryptAsObject(details)

encryptAsObject performs the encrypt process for the provided card details and prepares them to be sent to Ravelin, with the resulting payload returned as an object.

Parameters

Name Type Description
details Object An object containing properties pan, month, year and nameOnCard (optional).  

Examples

var encrypted = ravelinjs.encryptAsObject({pan: "4111 1111 1111 1111", month: 1, year: 18});
console.log(encrypted);
> {
>  methodType: "paymentMethodCipher",
>  cardCiphertext: "abc.....xyz==",
>  aesKeyCiphertext: "def....tuv==",
>  algorithm: "RSA_WITH_AES_256_GCM",
>  ravelinSDKVersion: "0.0.1-ravelinjs",
> }

Returns

  • Object The encrypted payload to be sent to Ravelin.

ravelinjs.track(eventName, meta)

track invokes the Ravelin client-side tracking script. You must have set the public API key in advance of calling track, so that it can submit the data directly to Ravelin. Its execution is asynchronous.

Parameters

Name Type Description
eventName String A description of what has occurred.  
meta Object Any additional metadata you wish to use to describe the page.  

Examples

// track when a customer uses search functionality
ravelinjs.track('CUSTOMER_SEARCHED', { searchType: 'product' });

// track without any additional metadata
ravelinjs.track('CUSTOMER_SEARCHED');

Returns

  • Void

ravelinjs.trackPage(meta)

trackPage logs the page view. Call this from as many pages as possible.

Parameters

Name Type Description
meta Object Any additional metadata you wish to use to describe the page.  

Examples

// Call from landing page after page load
ravelinjs.trackPage(); // www.ravelintest.com

// Identical calls should be made on all subsequent page loads
ravelinjs.trackPage(); // www.ravelintest.com/page-1
...
ravelinjs.trackPage(); // www.ravelintest.com/page-2
...
...
ravelinjs.trackPage(); // www.ravelintest.com/page-3
..
ravelinjs.trackPage(); // www.ravelintest.com/page-2

Returns

  • Void

ravelinjs.trackLogout(meta)

trackLogout informs Ravelin of logout events and resets the associated customerId and tempCustomerId. Call this function immediately before your own logout logic is executed.

Parameters

Name Type Description
meta Object Any additional metadata you wish to use to describe the event.  

Examples

ravelinjs.trackLogout(); // Called before you begin your logout process

Returns

  • Void

ravelinjs.trackFingerprint(customerId, callback)

trackFingerprint sends device information back to Ravelin. Invoke from the checkout page of your payment flow.

Parameters

Name Type Description
customerId String The customerId to set for this device fingerprint. Optional if setCustomerId called in advance.  
callback Function Optional callback to check the fingerprint has completed. Prefer calling trackFingerprint on page load.  

Examples

// if setCustomerId was already called
ravelinjs.trackFingerprint();
// else, you must inform Ravelin of the customerId explicitly
ravelinjs.trackFingerprint('customer123');

Returns

  • Void

ravelinjs.setCookieDomain(domain)

setCookieDomain configures where Ravelin will store any cookies on your domain. Set as high as possible, e.g. “.mysite.com” rather than “.www.uk.mysite.com”.

Parameters

Name Type Description
domain String Domain under which Ravelin generated cookies should be stored  

Examples

ravelinjs.setCookieDomain('.mysite.com');

Returns

  • Void

ravelinjs.setOrderId(orderId)

Set the orderId submitted with requests. This is used to associate session-activity with a specific user.

Parameters

Name Type Description
orderId String Current orderId for the order  

Examples

ravelinjs.setOrderId('order123');

Returns

  • Void