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.
- Client browser sends sensitive card data to ChargeItPro server
- ChargeItPro creates initial token
- ChargeItPro returns token to client browser
- Client browser sends payment data and token to Developer server
- Developer server submits payment data and token back to ChargeItPro server
- ChargeItPro processes transaction and returns results (approve/decline) back to Developer server
- 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
| MerchantName | Merchant1_23f1984001644e1ba7b4ca9506077e81 |
|---|---|
| MerchantKey | e5932e4dd41742cd81768c6ace7bedc9 |
Test Card Information
| Card Number | 4000200011112222 |
| Card Expiration Month | 05 |
| Card Expiration Year | 25 |
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
| 200 | OK | Successful HTTP Request |
| 401 | Unauthorized | Unauthorized HTTP Request. Invalid credentials. |
| 404 | Not Found | Transaction 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
| 200 | OK | Successful HTTP Request |
| 401 | Unauthorized | Unauthorized HTTP Request. Invalid credentials |
| 404 | Not Found | Merchant and/or Token not found |
| 500 | Internal Server Error | Credit 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
| 200 | OK | Successful HTTP Request |
| 401 | Unauthorized | Unauthorized HTTP Request. Invalid credentials |
{
"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"}}