Online security is important!

Overview

This documentation serves as a reference guide for online shopping cart developers looking to use the Cayan Checkout E-Commerce solution with Kount fraud risk assessment integration. Cayan Checkout makes it easy for shopping cart developers to quickly and securely accept online payments, while maintining their site's look and feel. Just import a single Javascript library, add a few annotations to your web form, and you're ready to start accepting payments.

To begin using the Cayan Checkout E-Commerce library, create a checkout page with a form that includes inputs for a credit card number, a CVV code, an expiration date month, and an expiration date year. You can use any HTML name or ID attributes you'd like for these fields.

A Kount session is created using the one-time token and a 1x1 pixel iframe is injected into the webpage for the Kount device data-collector.

3 Perform a Sale with the Token

Use the token to perform a sale or pre-authorization.

Kount Fraud Scoring

The Cayan Checkout API provides fraud scoring feedback for your transactions based upon the cardholders email address. This feature can provide critical information as to whether a merchant should complete a transaction or not due to a higher risk of fraud.
Use of this additional feature could result in additional fees for a merchant who wishes to support it. However, the same API can be used either way. If a merchant's account does not have Kount Fraud Scoring enabled, the API will simply respond as though that feature was not being used.

1 Setting up the Payment Form

On each of the relevant form elements, add a special data-cayan attribute that is used to identify the purpose of the element to the library. You can see a full list of the attributes supported in the reference section of this document.

The last element required in setting up your form is to set your Web API Key. This is a number that is generated specifically for an account to use, and should be enabled for use with Kount. This Key is only able to generate a Single-Use Token. The CayanCheckoutPlus.setWebApiKey() JavaScript method is used to accomplish this.

2 Create a Single Use Token

You are now ready to begin the process of turning the payment data into a single-use token. The token expires two minutes after its creation. To do this, you will need to intercept the click event of a button, or the submit action of a form. For this example, we are going to use the latest version of jQuery but you can use any framework you wish.

When submitButton is clicked by the user, the button is first disabled to prevent them from submitting multiple times. Then the CayanCheckoutPlus.createPaymentToken() function is called. The function takes an object with two fields, “success” and “error”, which are callbacks that handle the responses from the JavaScript library.

The success callback receives an object containing information about the token that looks something like this:

The error callback receives an array of error objects, which represent one or more errors.

[{ error_code: "VALIDATION", reason": "cardnumber" }]

In this example, the error code describes the type of error, while the reason represents the reason the error was triggered. For validation or required field errors, the callback function should alert the user as to the fields which have problems. You can use HTML to display these errors, like out example does, or JavaScript.

Once the token information is returned, you can proceed to submit the form to your server. Any sensitive cardholder information such as the PAN and CVV values are removed automatically by the library for security reasons so they are never submitted to the server.

Here is an example of a very simple success callback function in JavaScript:

function successCallback(tokenResponse) {
// Populate a hidden field with the single-use token
$("input[name='paymentToken'").val(tokenResponse.token);
// Submit the form
$('#paymentForm').submit();
}

3 Perform a Sale with the Token

Now that the server has submitted the form, you can retrieve the single-use token from the form data and process the transaction. The token is stored in the Cayan Vault allowing you to use the token with the standard Vault-based Authorize or Sale transactions.

You will need to use Sale or Authorize depending on the nature of the goods being purchased. In the event that the good or service being sold is virtual or requires no delivery, Sale is the appropriate method to use . However, in the event of an item that needs to be shipped, you cannot finalize the sale until the goods have shipped. In this case, you can perform a Pre-Authorization on the card, and capture the funds using a Post-Authorization when the goods have shipped.

Cayan Checkout uses the MerchantWare 4.5 API. You will need to follow that documentation to run transactions and read responses.

The code block shows a simple example of how to perform a Sale transaction.

Note: The response will contain fraud scoring data when a call to Kount is attempted.

The FraudScoring section of the response may include the following values:

FraudScoring Property

Value

ExternalReference

The Kount transaction ID number. Note: This is different from the ID used by Cayan to identify a transaction.

Recommendation

The suggested action as assessed by Kount. Responses are Approve, Decline, Escalate, and Review.

Score

The risk assessment score returned by Kount.

Status

The overall status of the Kount risk inquiry request. If the request failed or returned errors, the status will be Error otherwise it will be Success.

These values can be taken into consideration when deciding whether or not to honor the transaction. You could simple take the value of the Kount Recommendation field and react based upon that, leaving the transaction alone for an Approve recommendation or perhaps running a Void on it for a Decline recommendation. Or if you would like more control, the Score value can be used instead. Decisions could also be made programmatically for transactions of different amounts, a higher value transaction may warrant higher scrutiny.

Similarly, E-Commerce shopping cart implementors are also responsible for implementing business logic to handle AVS and CVV response codes that their merchants would prefer to decline (eg. by issuing a Void or Refund). Full documentation on our AVS and CVV response codes can be found here.

Objects

HandlersA set of key/value pairs used to configure the behavior for the CayanCheckoutPlus.createPaymentToken() function. Both the success and the error functions are required.

Field

Type

Description

success

Function

Function (TokenResponse data)
A function that is called when the payment information was successfully converted into a single-use token. The data contains basic information about the token including when it was created, and when it expires.
This is a required field.

error

Function

Function (ErrorResponse[] error)
A Function that is called when there was an error creating the single-use token from the payment data. The error response contains a list of error codes and responses related to that error code.
This is a required field.

TokenResponseThe token response object is returned by the success callback of the CayanCheckoutPlus.createPaymentToken() method.

Field

Type

Description

token

String

A single-use token that can be used to perform a transaction using Cayan's gateway.

created

Date(UTC)

A value that represents the date the token was created by the server. A function that is called when there was an error creating the single-use token from the payment data. The error response contains a list of error codes and responses related to that error code.

expires

Date(UTC)

A value that represents the date the token will expire on the server and no longer be available to process a transaction. A single-use token will expire two minutes from the creation time.