This guide provides information for integrating the legacy CardSecure API. 

The methods described in this guide are deprecated, and no feature updates are planned for these APIs. If possible, we recommend that you migrate to the CardSecure JSON API to receive future updates and enhancements.

CardSecure provides several methods for protection of credit card data and other sensitive information. Credit Card Numbers (CCNs) can be encrypted and returned to the calling application for storage. Other types of data (PII, SSN, ACH) can also be encrypted and stored within CardSecure, returning a token to the calling application. Several token formats are available (alpha-numeric, numeric, hyphenated). There is also an option to tokenize without encrypting, if using a database that is already suitably encrypted.

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 in the calling system instead of a clear or encrypted PAN, potentially reducing PCI scope considerably.

Available Interfaces

CardSecure provides the following application interfaces:

  • HTTP(s) Interface - Either clear text or SSL (recommended).
  • SOCKET Interface - Either clear text or SSL (recommended).
  • SAP RFC Interface - Originally developed for SAP using the Remote Functional Call (RFC) interface

While the format is slightly different between the interfaces, all functions are supported for each interface.

API Action Codes

The CardSecure API is defined around a series of action codes that represent the specific actions for handling token requests. These codes are listed within the Payment Processing Tokenization Actions section.

You can pass any of these actions codes directly to CardSecure to generate a token.

For example, the following URL:

  • https://fts.cardconnect.com:6443/cardsecure/cs?action=CE&data=4444333322221111

returns the following result:

  • action=CE&data=9441149619831111

Generally, the CardConnect gateway is configured to support Credit Card and ACH (Bank Account) data tokenization. If you require additional tokenization actions (PII, Social Security), please ensure that you explicitly request the tokenization feature.

About CardConnect Tokens

  • Tokens generated for transaction processing must be created using action=CE.
  • Tokens never expire.
  • Tokens can be alpha-numeric. The format of the token is driven by the specific key format used.
  • Credit card tokens are generally 16 digit numeric tokens.
    • The token begins with a 9.
    • The second and third digits of a token represent the first and second digits of the card.
    • The last 4 digits of the token represent the last 4 digits of the card.

Payment Processing Tokenization Actions

Payment Credit Card or ACH Tokenize/Detokenize

Tokenized data within this section is used for transaction processing.

Action Code Purpose
CE Encrypts and stores a payment card, returning a token.
CV Searches for a token and returns either “Token Found” or “Token Not Found”.
CP Purges encrypted payment card data from a token while retaining the token.
CRDecrypts and stores a mobile wallet (Apple Pay or Google Pay) payload, returning a token.
CT Retrieves and decrypts a token but returns only the first 6 digits or “BIN”, padded with zeros and a valid check digit.
CZ Used to encrypt and store swiped card data. Data passed must be Base64-URL encoded string format.

Tokenize Data Actions

The following tokenization actions provide a way to tokenize data via CardSecure. These options are not used for tokenizing data that is submitted for transaction processing.

ACH Account Number Tokenize

Tokenized data within this section cannot be used for transaction processing.

Action Code Purpose
AE Encrypts and stores account data, returning a token.
AV Searches for a token and returns either “Token Found” or “Token Not Found”.
AP Purges encrypted account data from a token while retaining the token.

PII Personal Data Tokenize

Tokenized data within this section cannot be used for transaction processing.

Action Code Purpose
PE Encrypts and stores personal data, returning a token.
PV Searches for a token and returns either “Token Found” or “Token Not Found”.
PP Purges encrypted personal data from a token while retaining the token.

Social Security Number Tokenize

Tokenized data within this section cannot be used for transaction processing.

Action Code Purpose
SE Encrypts and stores a social security number, returning a token.
SV Searches for a token and returns either “Token Found” or “Token Not Found”.
SP Purges an encrypted social security number from a token while retaining the token.

Payment Card Raw Encryption

Tokenized data within this section cannot be used for transaction processing.

Action Code Purpose
EC Encrypts a payment card with a current Data Encrypting Key.
EC Encrypts a payment card with a prior Data Encrypting Key.

Echo Request

Action Code Purpose
HI Echo request (must send any 8 data characters) returns “CardSecure Server OK”.

Error Codes and Messages

The CardSecure server generates error messages to its log file for various conditions. The table below lists all errors generated by CardSecure. The error code and a text description are returned to the caller.

All error codes contain four digits. Two zeros precede the codes listed below.

Error Code Reason
00No error.
03 Wrong version number.
07 Invalid action.
08 Data is not decimal digits.
12 Key ID is not found.
13 Data is too long.
14 Data is empty.
16 Unknown algorithm.
17 Encryption failure.
19 Base 64 decode failure.
20 Crypto data is the wrong length.
21 Data is too short.
22 CCN wrong length on decryption.
24Decryption failure.
25 Bad PKCS 5 padding.
26 Bad decrypted length field.
27 Keystore not initialized.
33 Application not initialized.
35 Buffer too short.
38 Illegal characters.
39 Wrong message length.
43 Server failed.
44 Config item is bad.
46 Token database problem.
47 Unauthorized host.
48 Token purged.
49 Data not found.
50 Error hashing the value.
53 Token or data duplicate.
54 Card number check (Luhn formula) failed.
55 Missing or unknown site name.
56 Token format is bad.
57 Request signature is invalid.
58 Request signature timestamp expired.
59 Request signature mismatch.
60 Request signature failure.
61 PIN translation failure.
63 Keystore import failure.
64 Keystore userstore failure.
65 Keystore invalid processor.
66 Unauthorized terminal.
68 Keystore rollback failure.
71 Unauthorized decrypt.
72 Invalid EMV tag data.
73 EMV tag data empty.
74 Missing required parameter.
75 Invalid elliptic curve type parameter.
76 JSON serialization error.
77 JSON deserialization error.
78 Invalid swipe data.

Request Data Encryption with RSA

CardSecure allows clients to encrypt the data sent in the 'data' parameter over HTTP via the CR, AR, PR and SR function codes. The behavior of the CR function code is equivalent to CE, AR is equivalent to AE, PR is equivalent to PE, and SR is equivalent to SE. However, the value of the data in all *R requests must be encrypted using a RSA public key specific to the client's site. This RSA key is provided to clients by CardConnect on a per request basis. 

Each client will have a unique public/private RSA key pair generated for use of this feature and CardConnect retains the private key. The RSA public key that is provided to you is in X.509 format. 

Depending on the encryption utility used, the encrypted data might be Base64-encoded. In this case, the string can be URL-encoded and sent to CS for tokenization. Otherwise, you must Base64-encode the data before URL-encoding and submitting the tokenization request.

The data returned from the *R actions will be a tokenized version of the unencrypted data. The token itself will not be RSA encrypted.

The RSA features only accepts Personal Account Number (PAN) or Apple Pay data. It does not support the passing of track data.

This feature cannot be implemented when using CardConnect P2PE devices (Ingenico or IDTECH) due to the encryption key already configured within the terminals.

CardSecure Interfaces

CardSecure provides three interfaces for tokenizing credit card data:

HTTPS Interface

CardSecure provides a standard HTTPS POST interface for the tokenization of data. Access to the user interface is restricted by IP address and user credentials.

The HTTPS interface URL is defined as follows:

Object Definition
Protocol https://
Hostname Hostname or IP address
Port 6443 (or other if configured). This port does not need to be specified when submitting a token request in the production environment. Please use the standard SSL port 443.
Servlet /cardsecure/cs
Function "action" + the two character code from the API Action Code list !!!cross-link!!!
Data “data=” + the value to be acted upon
Type Optional property to indicate a response format. Currently XML and JSON are defined.

API actions are case sensitive. CardSecure runs on JBOSS/Java in a Linux environment.

Encrypting a Credit Card via HTTPS

An example HTTPS request to CardSecure is:


Sample JSON Response

processToken( { "action" : "CE", "data" : "9124334659621234" } )

Sample XML Response


Sample Undefined Type Response


Encrypting ACH/Bank Data via HTTPS

An example HTTPS request to CardSecure with ABA/Account Number formatting:


Sample JSON Response

processToken( { "action" : "CE", "data" : "9123247477421234" } )

Sample XML Response


Sample Undefined Type Response


Encrypting Personal PII Data

For Personal Information token functions, printable characters are the allowed character set, thus requiring URL encoding of the request and response.

Example HTTPS Request to CardSecure

https://fts.cardconnect.com:6443/cardsecure/cs?action=PE&data=CardConnect Payment Processing

Automatic URL Encoded Request


Sample JSON Response

processToken( { "action" : "CE", "data" : "RE0smitS" } )`

Sample XML Response


Sample Undefined Type Response


SOCKET Interface

CardSecure provides a generic TCP/IP socket interface for persistent application connections. The server side socket is installation specific and defined by the server configuration file. The default is either 1443 or 4944 for an unencrypted connection in development and testing, and 1444 or 4945 for a SSL encrypted connection in production. Multiple socket listeners can be configured on different ports for different user groups or applications.

The protocol is a synchronous request/response over each socket. Additional sockets may be opened up to the listen depth server configuration parameter. A server side thread is created to handle the processing for each socket.

The socket message format is as follows:

Length4-digit zero-padded payload length
FunctionAny of the two character API Function Codes
Trace4 character user field, default “;;;;”
Key ID3 character key field, used only for DE, default “ ”
DataThe data to be encrypted or tokened, or the token to retrieve

The response message follows the same format, with the response in the Data field. The returned function code is either the request code or ER if an error occurred.

For error responses, the Data field contains a four digit error number (first two digits always zero) followed by two colons and a text description of the error, as follows:

FF0031ER01;;;; 0049::Data not found

Tokenize Card Swipe Data

CardSecure supports tokenization of card swiped data using a supported encrypted credit card swipe reader. For a list of supported terminal devices, please visit https://support.cardconnect.com/device-integration.

When a credit card is swiped with a supported terminal, the extracted encrypted data can be submitted to CardSecure for direct tokenization. Once the data bas been extracted, it will need to be URL encoded and submitted to CardSecure using the CZ API action.

CardSecure does not support passing unencrypted track/swiped data. The encrypted data extracted from the device must be produced from a device pre-injected with a CardConnect Security Key. If testing is required using non-encrypted track, the data can be tokenized via the CardConnect gateway (as part of an authorization), or the Personal Account Number (PAN) must be parsed and sent directly with a tokenization request.

Example of Card Swipe Data

Example card swipe data is listed below. Note that the format may vary between readers.

02E801801F4A2800839B%*4005********4440^FDMS TEST CARD   /VISA^1812**************************?*;4005********4440=1812****************?*91F960A74D24E5B2762B56844DA0814A89BBC0D90ED5D5A49951D8D752A20CB1E5631FA65FEA3433D95956FCFD576CF9C6B8C230C8A8EE148017773824CFAF7802F39EFE82D388AC0155A940FC41E8D9485C998DE23D984935A65032417F0CD133C456FB43E8D3F12E0242D96376C80E9FD8E6254D604ED60000000000000000000000000000000000000000000000000000000000000000000000000000000035323054383230323334CDCDCD070121090000AA61C503

To tokenize encrypted track data extracted from a terminal device:

  • URL encode the swipe data prior to placing it in the data parameter of the token request.
  • Create a call to CardSecure using the CZ action.

Tokenization Example with Encrypted Data




CardSecure decrypts this 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. If an authorization is run through CardConnect using this token within the permitted time period, the track data is sent to the processor, possibly allowing the transaction to be run as a ‘card present’ transaction. The default retention period for track data stored after passing encrypted track and requesting a token is 24 hours. If the token is used with an authorization during this time window, the track data is discarded. It can only be used once per authorization.

HTTP Request Signing

CardSecure supports an optional feature which allows clients to digitally sign HTTP/HTTPS requests to CardSecure to ensure data integrity. Request signing helps ensure that the request was not tampered while in transit from the client to CardSecure. It is also used to prevent replay attacks by having each request expire after a short time period.

Please contact CardConnect to enable this feature. CardConnect will provide a unique key for signature use. Once a site is configured to use HTTP request signing all requests from that site must be signed using the method outlined below. All unsigned requests will be rejected.

Signing a HTTP request involves using the provided shared with the HMAC-SHA-256 hashing algorithm and the parameters used to construct the request. The following request parameters must be in order when creating the message signature:

Parameter NameDescription
actionCardSecure function code
dataData payload of the request
refClient-generated reference or random number
timeTime of the request in GMT (yyyy-MM-dd'T' HH:mm:ss'Z')

These parameters must be assembled into a URL string format prior to signing. For example the following is a valid string for signature generation:


Order is important. All parameter names must be in alphabetical order and in all lowercase in order for CardSecure to be able to verify the message signature.

A generated signature will loosely resemble the following:


Once a signature has been generated, the signature along with all of the parameters used to generate the signature must be included in the request to CardSecure. The message signature must be provided to CardSecure using the ‘sig’ parameter. For example:

https://fts.cardconnect.com:6443/cardsecure/cs? action=CE&data=4444333322221111&ref=1234&time= 2014-01-01T+00%3A00%3A01Z&sig=5820c73daa9bd1b388070e4423d9f47b89fa3d4bed5d24466cf30043a9c6124f

Note: Please refer to error messages 57-60 within "Error Codes and Messages" for all request message signature errors.

Tokenize Apple Pay Data

CardSecure supports the ability to generate a token from data retrieved by Apple Pay. Clients will need to provision their own Apple Pay Merchant ID (with appropriate Identifier and Profile), and Certificate prior to submitting tokenization requests.

Merchants must be boarded on the First Data Rapid Connect platform in order to utilize tokens created with Apple Pay.

Apple Pay Merchant Configuration

Creating a Merchant ID
  1. Log in to https://developer.apple.com/account
  2. Select Certificates, Identifiers & Profiles link on lefthand navigation bar
  3. Select Merchant IDs link under Identifiers on lefthand navigation bar
  4. Select + icon on the top right to create a new Merchant ID
  5. Enter a description and identifier and click Continue
  6. Select Register button
Creating an Apple Pay Certificate and Uploading the CSR
  1. Log in to https://developer.apple.com/account
  2. Select Certificates, Identifiers & Profiles link on lefthand nav bar
  3. Select All link under Certificates on lefthand nav bar
  4. Select + icon on the top right to create a new certificate
  5. Select Apple Pay Certificate radio button and hit Continue button
  6. Select the Merchant ID that was created from steps in "Creating a Merchant ID" above
  7. Click Create Certificate button in the Payment Processing Certificate section
  8. Answer questions and/or hit Continue button until the "Generate Certificate" page is reached
  9. Select the Choose File... button, select the CSR provided by CardConnect ('apple-pay-.csr' from step 1 above), then hit the "Continue" button
  10. Select the Download button to download the signed public key and hit the "Done" button
  11. Send the 'apple_pay.cer' file that was downloaded to CardConnect

Apple Pay Data Retrieval/Tokenization

Please review the following Apple Pay documentation: Payment Token Format Reference

Apple Pay Tokenization makes use of the same RSA Encryption functionalities of CardSecure. A similar decryption process has been implemented by CardConnect in order to handle the encrypted data returned from Apple.

You must tokenize the Apple Pay payload within 2 minutes of retrieval. Attempting to tokenize an expired Apple Pay payload results in a action=ER&data=0024%3A%3ADecryption+failure response from CardSecure.

Additionally, you must retrieve a new Apple Pay payload for each tokenization attempt.






The following parameters are required in the URL string submitted to CardSecure.

All fields should be URL encoded.

Property Value
action CR
data Encrypted payment data payload
ectype apple
eckey ephemeralPublicKey from Header keys of Payment Token
ecsig Signature of the payment and header data
ectid Transaction ID from Header keys of Payment Token
echash Hash of the applicationData property of the original PKPaymentRequest object.
ecpublickeyhash publicKeyHash

Sample Request

Triple-click to select all.


Due to the time sensitivity of the 'ecsig' parameter, the below request will not provide a token. Request also does not contain the 'echash' parameter/value. It should be used as an example of the required format.

Tokenization Code Examples