Cayan Checkout

Home/Developers / Cayan CheckoutQuick Links

Online security is important!

Please be sure to check out our Web Development Best Practices Guide

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.

For a demo of Cayan Checkout, see http://checkout.cayan.com/

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.

For some additional guidance, take a look at our Best Practices guide on Cloud Based Point of Sale and E-Commerce Best Practices.


Transaction-Process-Flow.png

 


Transaction Flow

1 Setting up the Payment Form a. Create a form with all the required elements to generate a token.

b. Include a reference to the JavaScript library.

c. Set the Web API Key for the Merchant account being used.
2 Create a Single-Use Token Sumbit your form and receive a single use token for the transaction.

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.

There are four required elements:
  • The card number
  • The CVV code
  • The card's expiration month and year
 

Form Parameters

Name Type Size Required Cayan Attribute Description
Card Number String 13-19 data-cayan="cardnumber" The PAN of the card being used for payment.
CVV String 3-4 data-cayan="cvv" The CVV number of the card being used for payment.
Expiration Month String 2 data-cayan="expirationmonth" The numeric expiration month of the card being used for payment.
Expiration Year String 2 data-cayan="expirationyear" The numeric expiration year of the card being used for payment.
HTML Form Example:
view raw PaymentForm.html hosted with ❤ by GitHub
 
 
This form is meant to serve as a simple reference, and you may choose to configure it to use a drop-down menu instead of text boxes for the expiration month and year.
The JavaScript Library will import the functions needed to complete the transaction. You will need to include a reference to it in your code.
<script type="text/javascript" src="https://ecommerce.merchantware.net/v1/CayanCheckoutPlus.js"></script>
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.
<script type="text/javascript">
   CayanCheckoutPlus.setWebApiKey("ABCDEF0123456789");
</script>

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.
$(document).ready(function () {
 
    $('#submitPayment').click(function () {
 
        // Prevent the user from double-clicking
        $(this).prop('disabled', true);
 
        // Create the payment token
        CayanCheckoutPlus.createPaymentToken({
            success: successCallback,
            error: failureCallback
        })
 
    });
});

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:
{
   token: "OTT_LT1KSFBNOZB381037S",
   created: " 2015-09-02T00:08:38.8686925Z",
   expires: " 2015-09-02T00:10:38.8686925Z"
}

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.
CreditSoapClient mwClient = new CreditSoapClient();
using (new OperationContextScope(mwClient.InnerChannel))
{
    MerchantCredentials cred = new MerchantCredentials();
    cred.MerchantName = "TEST";
    cred.MerchantSiteId = "XXXXXXXX";
    cred.MerchantKey = "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX";
 
    PaymentData pay = new PaymentData();
    pay.Source = "Vault";
    pay.VaultToken = token;
    //The email address is optional, but required for Kount FraudScoring
    pay.CustomerEmailAddress = "customer@email.com";
 
    SaleRequest sale = new SaleRequest();
    sale.Amount = this.Amount;
    sale.InvoiceNumber = "123456";
 
    TransactionResponse45 response = mwClient.Sale(cred, pay, sale);
  
    string extRefId;
    string recommendation;
    string score;
    string status;
    if (response.FraudScoring != null)                    
    {                                         
        // Use the response object to retrieve FraudScoring data          
        extRefId = response.FraudScoring.ExternalReference;                    
        recommendation = response.FraudScoring.Recommendation;                    
        score = response.FraudScoring.Score;                    
        status = response.FraudScoring.Status;
    }
}
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.

The full C#/.NET example can be found at https://github.com/Cayan-LLC/developer-docs/tree/master/examples/ecommerce/dotnet/CayanCheckoutPlusSample. Examples for other programming languages can be found at https://github.com/Cayan-LLC/developer-docs/tree/master/examples/ecommerce

Javascript API Reference

Functions

CayanCheckoutPlus.setWebApiKey(apiKey)
This function is used to set the merchant account used to tokenize the payment information.
Parameter Type Description
apiKey String A string containing the Web API key used to identify the merchant account.
Example:
CayanCheckoutPlus.setWebApiKey("ABCDEF0123456789");

CayanCheckoutPlus.createPaymentToken(handlers)
This function is used to create a single-use token from the payment information on the current HTML page.
Parameter Type Description
handlers Object (handlers) A set of key/value pairs used to configure the behavior of the method creating the single-use tokens.
Example:
CayanCheckoutPlus.createPaymentToken({
   success: successCallback,
   error: failureCallback
});


Objects

Handlers
A 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.

TokenResponse
The 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.
Example:
{
   token: "OTT_LT1KSFBNOZB381037S",
   created: " 2015-09-02T00:08:38.8686925Z",
   expires: " 2015-09-02T00:10:38.8686925Z"
}

ErrorResponse
The error response object is returned by the error callback of the CayanCheckoutPlus.createPaymentToken() method.
Field Type Description
error_code String A value that contains a unique error code representing the type of error that occurred when processing the payment information.
Example:
[
    {
        error_code: "VALIDATION",
        reason: "cardnumber"
    },
    {
        error_code: "REQUIRED",
        reason: "cvv"
    }
]
   

Error Code Reference

Error_Code Reason Description
NOT_FOUND A required form field is missing from the page and/or could not be found.
REQUIRED A required field contains an empty value.
VALIDATION A field contains data that is invalid
SERVER UNEXPECTED An unexpected error occurred on the server and the request was not processed.
SERVER UNAVAILABLE The server is currently unavailable for tokenizing payment information.
SERVER UNAUTHORIZED The server rejected the Web API key supplied.
SERVER PAYMENT_NOT_SUPPORTED The payment method is not supported by the merchant.
SERVER_REQUIRED The server did not receive a field which is required to create a single-use token.
This should not occur under normal circumstances, as all required fields are validated in the JavaScript library.
SERVER_VALIDATION The server received a field which failed validation.
This should not occur under normal circumstances, as all required fields are validated in the JavaScript library.

Supported Data-Cayan Form Elements

Value Required Description
cardholder No The name of the cardholder as it appears on the front of the card.
cardnumber Yes The credit card number
expirationmonth Yes The two-digit expiration month.
expirationyear Yes The two-digit expiration year.
cvv Yes The three or four digit CVV/CVC code on the card.
streetaddress No The street address for the card used for AVS checks.
zipcode No The zip code associated with the card used for AVS checks.