E-Commerce

Cayan Checkout

This documentation serves as a reference guide for online shopping cart developers looking to use the Cayan Checkout E-Commerce solution. 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.


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.
3 Perform a Sale with the Token Use the token to perform a sale or pre-authorization.

 

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/CayanCheckout.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. This Key is only able to generate a Single-Use Token. The CayanCheckout.setWebApiKey() JavaScript method is used to accomplish this.
<script type="text/javascript">
   CayanCheckout.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.
 

 
 
When submitButton is clicked by the user, the button is first disabled to prevent them from submitting multiple times. Then the CayanCheckout.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. 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 Pre-Authorization, Sale, or Level 2 Sale transactions.

You will need to use Sale or Pre-Authorization depending on that 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.

Below are some simple examples of how to perform a Sale transaction using various popular programming languages:

.Net

 

The full C#/.NET example can be found at https://github.com/merchantwarehouse/ecommerce/tree/master/examples/dotnet/webforms

Java

 

The full Java example can be found at https://github.com/merchantwarehouse/ecommerce/tree/master/examples/java

PHP

 

The full PHP example can be found at https://github.com/merchantwarehouse/ecommerce/tree/master/examples/php

Javascript API Reference

Functions

CayanCheckout.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:
CayanCheckout.setWebApiKey("ABCDEF0123456789");

CayanCheckout.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:
CayanCheckout.createPaymentToken({
   success: successCallback,
   error: failureCallback
});


Objects

Handlers
A set of key/value pairs used to configure the behavior for the CayanCheckout.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 CayanCheckout.createPaymentToken() method.
Field Type Description
token String A single-use token that can be used to perform a transaction using Cayan'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 CayanCheckout.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.

Additional Resources

There are several detailed samples available in a variety of languages and frameworks on GitHub. Please see https://github.com/merchantwarehouse/ecommerce/ for details.

Source code for a fully functional sample can be found here: https://github.com/Cayan-LLC/ecommerce/tree/master/examples/dotnet/CayanCheckoutSample/CayanCheckoutSample

This sample has also been hosted for demonstration purposes here: https://checkout.cayan.com/demo
 

Certification Script

The following Certification Script must be completed and sent to integrations@cayan.com along with any required screenshots for review.
E-CommerceCertificationScript