Overview
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.
CardSecure provides the following application interfaces:
While the format is slightly different between the interfaces, all functions are supported for each interface.
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.
action=CE
.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. |
CR | Decrypts 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. |
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.
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. |
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. |
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. |
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. |
Action Code | Purpose |
---|---|
HI | Echo request (must send any 8 data characters) returns “CardSecure Server OK”. |
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 |
---|---|
00 | No 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. |
24 | Decryption 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. |
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 provides three interfaces for tokenizing credit card data:
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.
An example HTTPS request to CardSecure is:
https://fts.cardconnect.com:6443/cardsecure/cs?action=CE&data=1234123412341234&type=json
Sample JSON Response
processToken( { "action" : "CE", "data" : "9124334659621234" } )
Sample XML Response
<cardsecure><action>CE</action><data>9124334659621234</data></cardsecure>
Sample Undefined Type Response
action=CE&data=9124334659621234
An example HTTPS request to CardSecure with ABA/Account Number formatting:
https://fts.cardconnect.com:6443/cardsecure/cs?action=CE&data=123456789/1234123412341234
Sample JSON Response
processToken( { "action" : "CE", "data" : "9123247477421234" } )
Sample XML Response
<cardsecure><action>CE</action><data>9123247477421234</data></cardsecure>
Sample Undefined Type Response
action=CE&data=9123247477421234
For Personal Information token functions, printable characters are the allowed character set, thus requiring URL encoding of the request and response.
https://fts.cardconnect.com:6443/cardsecure/cs?action=PE&data=CardConnect Payment Processing
https://fts.cardconnect.com:6443/cardsecure/cs?action=PE&data=CardConnect%20Payment%20Processing
Sample JSON Response
processToken( { "action" : "CE", "data" : "RE0smitS" } )`
Sample XML Response
<cardsecure><action>CE</action><data>RE0smitS</data></cardsecure>
Sample Undefined Type Response
action=PE&data=RE0smitS
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
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 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:
data
parameter of the token request.CZ
action.Response
action=CZ&data=9408230797904440
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.
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:
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:
5820c73daa9bd1b388070e4423d9f47b89fa3d4bed5d24466cf30043a9c6124f
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.
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.
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.
https://fts.cardconnect.com:6443/cardsecure/cs
POST
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 |
Triple-click to select all.
action=CR&data=6gPONejyRUnSopAAfh%2B%2B58n8B32groXzpqbNG8hsr9fz2l8Cpo7PW6I0ur5ZbcfTUa8j85d2OWn1ihLC0lD7cZBUPfvq24Y8aVJs7B2xYDJqnkYqQO77VSq%2FQNODsGyrkVwhw%2Br2HLntNhvRxkSDfKIJKuNwd0zPH%2F%2B78IszbYmmeeCJ11OAFHePcFKN6Ye1fBVtwKE41qRZWJkfbQBbIxf%2BWESOvOXv1Tq2hrVFcjLBwXeAgeSmGoal9kua1d44vK49I6cNtuk3QfNha6eOMbfZS4kac6CELpawVX95tQXoZ56PGE0kEIaOWaWiJ4hNBepWQP1b1g%2F5B%2BLRlb6YuHixQI%2FHChPqTPiJSvJL1W41DNaxzcV2%2BWdZNd3Yz69r04tprE2AadKgaffP&ectype=apple&ecsig=MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O%2F0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22%2FVdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB%2FwQCMAAwHwYDVR0jBBgwFoAUI%2FJJxE%2BT5O8n5sT2KGw%2Forv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB%2FjCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB%2FwQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw%2BSoyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6%2BW5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS%2B%2FOpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou%2Fee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT%2FVEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk%2BTvJ%2BbE9ihsP6K7%2FS5LMA8GA1UdEwEB%2FwQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH%2FBAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr%2F0F%2B3ZD3VNoo6%2B8ZyBXkK3ifiY95tZn5jVQQ2PnenC%2FgIwMi3VRCGwowV3bF3zODuQZ%2F0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggGLMIIBhwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoIGVMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTE3MDcxODE4MjQzOVowKgYJKoZIhvcNAQk0MR0wGzANBglghkgBZQMEAgEFAKEKBggqhkjOPQQDAjAvBgkqhkiG9w0BCQQxIgQgTq8L0dWa9YROmIC9xQFXWHoSPAZBq1Yu%2F6Y4S6d3keUwCgYIKoZIzj0EAwIERjBEAiAUloVnCk6nG4EXPFxTiEk7gVgVcvXnqdqWn9RMrHNFfgIgF%2FObI%2FMqvgAe5cLeWfcZT4lQ1cOVBcBqqTQn%2Bs28zAcAAAAAAAA%3D&eckey=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEu4QmOj9%2Br3vzR9fae%2B3c00uwaQpCUM3GDODgUC74aTDEI7RJG%2Bw6VQOABvdvUq0EkKiIc%2F%2B%2BE2BojyGRxr%2Bo0Q%3D%3D&ectid=745c61b5653902cc50925549c6f79e756b22b948dd99aa643ebfadf44c27bc3f
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.