CardSecure API Overview

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. Card Secure 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:


returns the following result:

  • action=CE&data=9441149619831111

Note: 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.
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.

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

Error Code Reason
01 The generated message is too long.
02 Each response received from CardConnect to CardSecure has a header with a prefix of "FF". This error indicates that the response received by CardSecure did not come from CardConnect. This error may be related to a user trying to directly access the CardSecure socket.
03 Wrong version number.
04 Non-decimal in length.
05 The message is too small.
06 The message is too large.
07 Invalid action.
08 Data is not decimal digits.
09 Key ID is out of range.
10 Key ID is an invalid encode length.
11 Key ID is an invalid decode length.
12 Key ID is not found.
13 Data is too long.
14 Data is empty.
15 Binary decimal encoding failed.
16 Unknown algorithm.
17 Encryption failure.
18 Base 64 encode failure.
19 Base 64 decode failure.
20 Crypto data is the wrong length.
21 Data is too short.
22 CCN wrong length on decryption.
23 Out of memory.
25 Bad PKCS 5 padding.
26 Bad decrypted length field.
27 Keystore not initialized.
30 Unimplemented action.
31 Open file.
32 Application already initialized.
33 Application not initialized.
34 Null pointer.
35 Buffer too short.
36 File read error.
37 File write error.
38 Illegal characters.
39 Wrong message length.
40 Wrong config item length.
41 Password is too short.
42 Non-hexadecimal character.
43 Server failed.
44 Config item is bad.
45 Hardware crypto problem.
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.

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. The data must be encrypted using RSA encryption in ECB mode with PKCS1 padding. The RSA encrypted data must also be Base64 encoded prior to transmission to CardSecure.

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

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

Note: 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.

Note: 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 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:

Object Definition
Prefix FF
Length 4-digit zero-padded payload length
Function Any of the two character API Function Codes
Version 01
Trace 4 character user field, default “;;;;”
Key ID 3 character key field, used only for DE, default “ ”
Data The 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

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.

Note: 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.

02D201801F472500839B%*4761****0036^VISA ACQUIRER TEST CARD 03^***?*;47610036=*****?*EB92D6AE71C4CAF73431AEEE24BB09CF6024317AA5BD69B5C717BA22D1F62CFFD9D09781D0CFCDD2E09C2C53383236317F582ECB762A8A93AC493FACD6554EFABB2A839A2C13BA8497F687BA5B0B10495F9FC1127AFF3551D022370AD9FE8C0706216C1E29219BE59DA2BB2DCBD57FB90000000000000000000000000000000000000000000000000000000000000000000000000000000054313430313030323730CDCDCD070100026000120D0703

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 02D201801F472500839B%25*4761****0036%5EVISA%20ACQUIRER%20TEST%20CARD%2003%5E***%3F*%3B47610036%3D*****%3F*EB92D6AE71C4CAF73431AEEE24BB09CF6024317AA5BD69B5C717BA22D1F62CFFD9D09781D0CFCDD2E09C2C53383236317F582ECB762A8A93AC493FACD6554EFABB2A839A2C13BA8497F687BA5B0B10495F9FC1127AFF3551D022370AD9FE8C0706216C1E29219BE59DA2BB2DCBD57FB90000000000000000000000000000000000000000000000000000000000000000000000000000000054313430313030323730CDCDCD070100026000120D0703



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.

Extract the signature from the response received:

H4sICAAAAAAC\/1NJRy5CTVAA7NkxstQwDAZgMUPBMSipVXAAeigoOAFn+s\/0brUUsLHjSI5kOzzHK8+8YYbsZv3FlmQ7377\/+klERPT1I9EXInojot9E9IE ERHR5x8ktAc9HvH3un8U7aUbR4sWLVq0aNGmagDWYPASEICXgIDXcfAyDoQjHOMdHI6Z6kc4pnNEwppqQMIRjlgp1gaE1xiQcEy2tVUK5O0ddzxGAUrHbApbfyRH129iPMMGKRztHQGuOBCzlupC28VovQEGLDlKR++ManLgbM8K501ahyN7Glc42O9A2wNFz6PQv\/K8In0CamD\/RaCLMTZAtpvhNJEhmdG2bnSH2GHQ1SVFZbaWCWDLlq2OcgBsjv2z1B429FFGcact7W+ezsl9HrUMrjtw6IvyK0jvPjIH\/G9EhLQA02zfx5RWNSB+JOtmqi\/AM74bHFJ2szm46thGTXFgV1kSu9EBQz4UU0qZq+Ug19I5skvIl+3\/5pY37cq1xu+A25Fn2ef\/pMByOrSSid3VrDf7tUvFIfUdcsrd7lU47NNKrfzbnXfpPJvwKL5vcbDiSLHE6Wc9jsr0STnlec9EEx1aOtAcyM6scKjmrtXVWZV43g4pFrYihfriSV5zQqrlRQLmLGV1Mzifsci2JVlS3IczmxxQHD370urHkMVCvi9Ra7LfAfWsx7V5qDOwiwWkf+XlR2VBUHX0H1DVvy47xLGWAxLVvlen5MiTmEMAeh+e2dHLsF3HWZnocIx45WF18JWO1h24IxdUHBjn6D4pg9PBgxyj3wucO9Q9thEC5RBk\/EGlx4HbOw7bfeMqVO78uzpw2MdN43BBD8cizpPaWRyHK8Z3GRM4ahsTLOOwTSzRweEYnM9WcvACDl7KAUeIhePS5bAx0Fd2\/PcyyC\/gYG8BWcXB6zl4Kgdu4sDrOHgBBxsdeHcHX+NAOK5x4C4OXOPguRy2Dt3A0Tg9wzGVA\/d0IBzD1iWXOG7awuGbOkU7\/eyUj6qhTej4MwDGmp92WFIAAA==

  • Save that to a file (eg: sig.b64)
  • Then run: base64 -d -i sig.b64 > sig.gz
  • Ungzip: gzip -d sig.gz
  • Rename: mv sig sig.bmp
  • View the bitmap image

Note: These steps can be done programmatically.

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 Name Description
action CardSecure function code
data Data payload of the request
ref Client-generated reference or random number
time Time 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:

Note: 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: 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
  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
  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.





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

Note: 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


Note: 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