CIP Token

Charge It Pro Client Side Encryption provides an integrated web-based payment solution that ensures sensitive credit card data is not posted to your server/domain.

CIP tokenizes credit card data in the client browser instance and only posts that token (not credit card data) back to their server form POST handler. The Developer then performs a server-side tokenized transaction using their CIP (private) API key.

Workflow

The following steps explain the process to generate a token, return the token and results using the CIP token method.

  1. Client browser sends sensitive card data to ChargeItPro server
  2. ChargeItPro creates initial token
  3. ChargeItPro returns token to client browser
  4. Client browser sends payment data and token to Developer server
  5. Developer server submits payment data and token back to ChargeItPro server
  6. ChargeItPro processes transaction and returns results (approve/decline) back to Developer server
  7. Optional Developer Feature: Developer server displays results back to client browser (Implementation/Developer feature)

 

Setup

Add a reference to CIP.token.js in the tag of the HTML containing your payment form.

    
    

Add a payment {form} to your HTML page.

Notes on Attributes

Do not add name attributes to the Number or Expiration fields (ie the fields that will be tokenized). This will ensure these pieces of sensitive data do not get posted with the form submit event. You will use data-cip html5 data attributes to identify the fields to tokenize. The data- attributes are:

  • data-cip=”number”
  • data-cip=”exp-month”
  • data-cip-“exp-year”
    <div>
      <!-- Your Form Data Goes Here -->
    </div>

    <div>
      <div>Card Number</div>
      
    </div>

    <div>
      <div>Expiration Month</div>
      
    </div>

    <div>
      <div>Expiration Year</div>
      
    </div>

    <div>
      <div>Billing Name</div>
      
    </div>
    <!-- Add the following 3 fields only for Keyed Transactions (i.e. non-swipe) -->

    <div>
      <div>CVV Number</div>
      
    </div>

    <div>
      <div>Billing Street Address</div>
      
    </div>

    <div>
      <div>Billing Zip</div>
      
    </div>

    <div>
      <button type="submit">Submit</button>
    </div>

    <div id="payment-errors"></div>

Notes on Card Present

For Card Present (i.e. swipe data), there is no need to include the CVVNumber field in your form; these values will be automatically be parsed from the swipe. For Keyed Transactions, do include the BillingStreetAddress, BillingZip and CVV Number fields in your form.

 

Submitting BillingStreetAddress, BillingZip and CVV Number will ensure you get the lowest rate for manual transactions.

Intercept the form Submit event, create the CIP Token, then post back to your server in the callback.

If you’re using jQuery, make sure to add a reference to:





jQuery(function ($) {

    /* You must set your Merchant Name identifier (Public Key) */
    CIP.token.merchantName = 'Merchant1_23f1984001644e1ba7b4ca9506077e81';

    $('#payment-form').submit(function (event) {

        var $form = $(this);

        /* Create the token and append cipToken as a hidden field on the callback */ 
        CIP.token.create($form, function (status, response) {

            if (response.error)
            {
                $form.find('#payment-errors').text(response.error.message);

            } else {

                var token = response.Token;

                $form.append($('').val(token));

                $form.get(0).submit();
            }
        });

        // Prevent form submission
        return false;
    });
});

Server-side integration

.NET Integration

Download CIP.Token.dll and add a reference to it within your project.

void YourPaymentHandler()
{
    /* Fetch your form post values */
    var cipToken = this.Request.Form["cipToken"].Value;
    var amount = GetYourAmount(); // i.e. 9.99
    var transactionType = GetYourTransactionType(); // i.e. CreditSale

    /* This toggles the environment, default points to Sandbox, set to True when migrating to Production */
    CIP.Token.IsSandbox = false;

    /* Set your Private Key */
    CIP.Token.ApiKey = "e5932e4dd41742cd81768c6ace7bedc9";

    /* Create a Transaction */
    var transaction = new CIP.Transaction()
    {
        Token = cipToken,
        Amount = double.Parse(amount),
        TransactionType = transactionType,
        Invoice = "Invoice Name",
        PONumber = "12345",
        OrderId = "98765",
        Description = "Your description",
        BillingAddress = new BillingAddress()
        { 
            CustomerId = "Your Customer Id",
            FirstName = "John",
            LastName = "Smith",
            Company = "The Billing Company",
            Street = "1 Mockingbird Ln.",
            Street2 = "Apt. 1",
            City = "Eagle",
            State = "ID",
            Zip = "55555-4444",
            Country = "USA",
            Phone = "555-555-5555",
            Email = "email@domain.com"
        },
        ShippingAddress = new ShippingAddress()
        { 
            FirstName = "Sam",
            LastName = "Smith",
            Company = "The Shipping Company",
            Street = "2 Shady Ln.",
            Street2 = "Apt. 2",
            City = "Boise",
            State = "ID",
            Zip = "55555-4444",
            Country = "USA",
            Phone = "555-555-5555",
            Email = "email1@domain.com"
        },
        Comments = "Your comments"
    };

    /* Process the transaction */
    var result = CIP.Token.RunTransaction(transaction);

    /* Save the result to your database and/or render the result values to your receipt view */
}

Test Account

MerchantNameMerchant1_23f1984001644e1ba7b4ca9506077e81
MerchantKeye5932e4dd41742cd81768c6ace7bedc9

Test Card Information

Card Number4000200011112222
Card Expiration Month05
Card Expiration Year25

Voids

Save the UniqueTransId value from the result object. Pass the UniqueTransId via the Transaction.UniqueTransRef property (this is the reference id that points to the transaction you wish to Void or Return), then set the TransactionType to Void.

void YourPaymentHandler()
{
...

    /* Create a Transaction */
    var transaction = new CIP.Transaction()
    {
        UniqueTransRef = "1234ABCD", /* This is the UniqueTransId of the transaction you wish to Void */
        TransactionType = "Void",
        ...
    };
}

Card Not Present Returns

This works exactly the same as a Credit Sale, but you set the Transaction.TransactionType to CreditReturn.

This will charge the card identified by a Reference Number without requiring submission of card account details.

void YourPaymentHandler()
{
...

    /* Create a Transaction */
    var transaction = new CIP.Transaction()
    {
        UniqueTransRef = "1234ABCD", /* This is the UniqueTransId of the transaction you wish to Void / Return */
        TransactionType = "CreditSale", /* CreditReturn for returns by Reference Number */
        ...
    };
}

Creating and assigning an External Reference Id

Create a GUID (string) and assign to Transaction.ReferenceId. This will be your ReferenceId from which you can track this transaction. The ReferenceId will also be returned in the JSON Result object.

void YourPaymentHandler()
{
...

    /* Create a Transaction */
    var transaction = new CIP.Transaction()
    {
        Token = cipToken,
        ReferenceId = "006aa7ef-4422-4009-a8ef-9b29eb6b9a88", /* This is your external ReferenceId */
        TransactionType = "Void",
        ...
    };
}

Query for your transaction via ReferenceId

Metadata

URI

HTTP Request Headers

x-apikey : ‘e5932e4dd41742cd81768c6ace7bedc9’

HTTP Status Codes

200OKSuccessful HTTP Request
401UnauthorizedUnauthorized HTTP Request. Invalid credentials.
404Not FoundTransaction not found

Custom Integration (.NET) - if not using CIP.Token.dll

Metadata

URI

HTTP Request Headers

content-type : application/json

x-apikey : ‘e5932e4dd41742cd81768c6ace7bedc9’

Server Code - C# Example

void YourPaymentHandler()
{
    /* Fetch your form values */
    var cipToken = this.Request.Form["cipToken"].Value;
    var amount = this.Request.Form["amount"].Value;
    var transactionType = this.Request.Form["transactionType"].Value;

    /* This toggles the environment, default points to Sandbox, set to True when migrating to Production */
    var isSandbox = true;

    /* Create the Transaction object to submit to the Web Service. Note TransactionType must be "sale". */
    var transaction = new { 
        Amount = amount, TransactionType = transactionType, 
        Token = cipToken, Invoice = "Invoice Name", IsSandbox = isSandbox 
    };

    /* 
    ToDo: Set the x-apikey in the Request header.  Remember this is your Private Key. 
    i.e. HttpRequest.Headers.Add("X-ApiKey", "e5932e4dd41742cd81768c6ace7bedc9")
    */

    /* Invoke the Web Service call */
    var result = YourWebServiceCall();

    /* Access the results */
    var refNum = result.UniqueTransId;
}

HTTP Status Codes

200OKSuccessful HTTP Request
401UnauthorizedUnauthorized HTTP Request. Invalid credentials
404Not FoundMerchant and/or Token not found
500Internal Server ErrorCredit card validation failed

Transaction result codes

When you invoke the ../token/transaction REST Service call you will be returned a JSON Response object.

{"Success":true,"Status":"OK","StatusCode":200,"Result":{"UniqueTransID":"61614252","BatchNumber":"159086","ResultMessage":"014860","ResultStatus":true,"ApprovalNumberResult":"014860","AmountBalance":"0.00","AmountProcessed":"0.01","AVSResponseCode":"YYY","AVSResponseText":"Address: Match & 5 Digit Zip: Match","CVVResponseCode":"M","CVVResponseText":"Match","AccountCardType":"VS","AccountExpiryDate":"0525","TransactionType":"sale","BillingName":"John Q. Public","MaskedAccount":"************2222","AccountEntryMethod":"Keyed","CreatedOn":"\/Date(1423700761447)\/"}}

Errors

Error messages will be returned in the Error Field.

{"Success":false,"Status":"InternalServerError","StatusCode":500,"Error":{"Message":"Credit card has expired. [GW:17]"}}

Credential Validation

Validation of credentials and to determine if you’re pointed to the Sandbox or Live environment.

Metadata

URI

Headers

content-type : application/json

{"MerchantName":"Merchant1_23f1984001644e1ba7b4ca9506077e81","Key":"e5932e4dd41742cd81768c6ace7bedc9"}

HTTP Status Codes

200OKSuccessful HTTP Request
401UnauthorizedUnauthorized HTTP Request. Invalid credentials

Authorization result codes

{
    "Success": true,
    "Status": "OK",
    "StatusCode": 200,
    "Result": {
           "IsValid": true,
           "IsSandbox": true,
    }
}

Errors sample

Error messages will be returned in the Error Field.

{"Success":false,"Status":"Unauthorized","StatusCode":401,"Error":{"Message":"Invalid credentials"}}