CardSecure is the CardPointe Gateway's sensitive data encryption and tokenization service. CardSecure allows you to securely accept and tokenize payment card, ACH (eCheck), and mobile wallet data to ensure the safety of your customers' sensitive payment data.
This guide provides information for developers looking to integrate CardSecure's tokenization and encryption methods using the CardSecure API. For information on integrating CardSecure with your iOS or Android mobile application, see Tokenizing Using the CardPointe Mobile SDKs.
What's New?
Visit Statuspage and click subscribe to updates to receive important release and status notifications.
Date Updated: 9/23/2023
An update to CardSecure was released to the UAT environment on 9/19/2023, and to the Production environment on 9/23/2023.
This update includes backend improvements and enhancements.
Date Updated: 7/24/2021
An update to CardSecure was deployed to the UAT environment on 7/19/2021 and to the production environment on 7/24/2021.
This release includes internal fixes and updates to CardSecure, including the following enhancement:
Enhanced Apple Pay Support
When tokenizing an Apple Pay payload, CardSecure no longer requires a specific order for the Apple Pay parameters in the devicedata string, with the exception of the data value, which must be the first parameter in the string. Previously, CardSecure required a specific sequence for all Apple Pay parameters in the devicedata string to correctly parse the string.
The CardSecure RESTful web service uses the JSON (JavaScript Object Notation) method of encoding data for transmission via the HTTP network protocol. Most programming languages have libraries to convert an arbitrary object to and from a JSON data transfer encoding.
The CardSecure API provides a library of POST operations used to submit HTTP requests to the web service. Responses are returned in JSON objects. See CardSecure API Service Endpoints for detailed information on the supported request types and corresponding responses.
Tokenizing and Encrypting PAN Data
You should only use CardSecure to programmatically handle and tokenize clear payment account numbers (PANs) if your business is a registered PCI Level 1 or Level 2 certified merchant. If you are not already certified for compliance with the Payment Card Industry's standards and guidelines for handling sensitive account data, see https://www.pcisecuritystandards.org/ for more information.
Additionally, you can integrate the Hosted iFrame Tokenizer with your solution to safely handle and tokenize clear PANs without increasing your business' scope of PCI compliance.
CardSecure provides encryption and tokenization services with a secure data vault typically used to store payment card Primary Account Numbers (aka PANs) in a PCI-DSS compliant manner. CardSecure generates a unique and random token value to be used by your application instead of a clear or encrypted PAN, potentially reducing PCI scope considerably.
If your application is using a database with sufficient encryption, CardSecure can tokenize data without additional encryption.
When a credit card is swiped or inserted at a supported terminal, the extracted encrypted data can be submitted to CardSecure for direct tokenization.
CardSecure does not support passing unencrypted track data. The encrypted data extracted from the device must be produced from a device pre-injected with the required Security Key. If testing is required using non-encrypted track, the data can be tokenized via the CardPointe Gateway (as part of an authorization), or the Personal Account Number (PAN) must be parsed and sent directly with a tokenization request.
CardSecure decrypts the encrypted swipe data and generates a token for the card number. CardSecure also stores the card’s encrypted track data for a short period of time, after which it is discarded.
If the token is used in an authorization request to the CardPointe Gateway during this retention period, the stored track data associated with the token is sent to the processor; this potentially allows the transaction to run as a "card present" transaction. The track data is discarded after the authorization request, and can only be used in a single request.
Encrypting and Tokenizing Payment Account Data
CardSecure allows clients to encrypt the account data (PAN or ACH) sent in a tokenization request using a client-specific RSA public key. CardPointe support can generate a unique RSA key pair, provide the public key (in X.509 format) to you, and retain the private key.
Data must be encrypted using RSA encryption in ECB mode with PKCS1 padding. The encrypted data must be Base64-encoded when sent to CardSecure in a tokenization request.
CardSecure uses the corresponding private key to decrypt the data. The decrypted data is temporarily stored in CardSecure's vault, and the token (generated from the encrypted data) is returned to your application for use in an authorization request to the CardPointe Gateway. Note that the token itself is not encrypted.
Note the following restrictions:
CardSecure only supports encrypted Personal Account Number (PAN) or ACH (eCheck) data. Track data is not supported in an encryption request.
CardSecure encryption is not supported for use with CardPointe Retail Terminal or CardPointe Integrated Terminal devices due to the encryption key already configured within the terminals.
Developer Resources
The following resources are available to simplify your integration.
Developer Guides
Our Developer Guides provide additional information for integrating CardPointe products and services.
To help you get started with your integration, we created a sample Postman Collection that includes a template of the CardSecure API service endpoints.
The CardSecure API Integration collection includes an API reference document as well as a sample Environment, to simplify your integration.
Click the button below to download the CardSecure API Integration collection:
Configuring Your Postman Environment
Environment variables allow you to autofill select fields with pre-configured values. Set the {{site}} variable to your specific site value provided during your account creation.
CardSecure API Service Endpoints
The following table lists the CardSecure API service endpoints and their functions. These endpoints are described in greater detail in the following sections.
Complete List of CardSecure API Service Endpoints
Service
API Version
Description
tokenize
v1
Tokenizes sensitive data provided in the request, and returns a CardSecure token.
echo
v1
Sends a ping command to the CardSecure server to verify the connection.
tokenize
Tokenize Request Example (Unencrypted Manual Card Entry)
POST /cardsecure/api/v1/ccn/tokenize HTTP/1.1
Content-Type: application/json
{
"account" : "4444333322221111"
}
Tokenize Request Example (CardPointe Integrated Terminal Entry)
HTTP/1.1 200 OK
Content-Type: application/json
{
"message" : "No Error",
"errorcode" : 0,
"token" : "9417119164771111"
}
A request to the tokenize endpoint returns a CardSecure token generated from the data provided in the request.
A tokenize request includes payment account data in either the account or devicedata field.
Use the account field to provide a clear or encrypted payment account number (PAN) or ACH account number (in the format <routing>/<account>).
If the account data is encrypted, include the encryptionhandler parameter to instruct CardSecure to decrypt the data using the private key for your site.
Use the devicedata field to provide track data received from a terminal device for an MSR (swipe), EMV (chip), or NFC (contactless) transaction, or a digital wallet payload (for example for a Google Pay transaction).
The tokenize response includes a token generated from the account data. You can then use this token to submit an authorization request to the CardPointe Gateway.
The following key/value pair is required in the request header:
Key
Value
Content-Type
application/json
Request Parameters
Fields in bold are required.
Either account or devicedata are required. Use account when manually entering encrypted or clear PANs. Use devicedata when capturing card data from a card reader or terminal device.
Field
Description
account
One of the following:
A clear or encrypted payment account number (PAN)
An ACH routing and account number string in the format <routing>/<account> for eCheck transactions
If encryptionhandler is provided, the account is treated as an encrypted PAN.
devicedata
One of the following:
Encrypted track data retrieved using a card reader or terminal device (MSR/EMV/NFC)
A call to the echo service endpoint sends a ping command to the CardSecure server to verify the application's connection. You can include a message in the request, which is returned in the response if the request is successful. If the request fails, an error message is returned with a corresponding error code.
The CardSecure server generates error messages to its log file for various conditions. If a request encounters an error, an error code and corresponding message are returned in a response to the calling application.
The following table lists all errors generated by CardSecure.
All error codes contain four digits. Two zeros precede the codes listed below.