Overview

The CardConnect BOLT P2PE API serves to streamline the integration of our P2PE validated card-present solution and your software system.

The Bolt Terminal Application is EMV pre-certified and included within CardConnect's PCI Point-to-Point Encryption (P2PE) Solution. This allows our partners to quickly achieve EMV acceptance and PCI scope reduction by using this P2PE Solution within a software application.

Integrating with the BOLT P2PE solution will require an application to implement a REST client that connects to the services within this guide and an Ingenico device provisioned by CardConnect.

EMV acceptance requires the merchant account to be on a CardConnect & EMV supported processing platform. More details and specific requirements may be requested by sending an email to isvintegrations@cardconnect.com.

Please visit the CardConnect Support Site for more details on the BOLT P2PE device integration solution and sample applications.

Application Workflow

Tokenization

Connect to a Terminal

Once a Bolt terminal is provisioned and delivered to a client, it will need to be connected to a network port with the ingenico Ethernet cable.

The terminal will display either Bolted or Unbolted depending on whether it has established an internet connection and made contact with the BOLT P2PE servers.

Once the terminal has established a Bolted status, it will be able to receive requests from an application.

Confirm Terminal Connectivity

A ping request can be sent from the application to confirm that a terminal is connected to the Bolt service.

Get a Token

In order to initiate either a swiped/inserted or manually entered tokenization request, an application calls that respective service.

Environment Service
Card Present readCard
Card Not Present readManual

Encrypted data will be retrieved from the terminal and sent to CardSecure for tokenization. The client application will receive a token in response.

Payments

The token retrieved can be used as the Account parameter within an Authorization request to the CardConnect Gateway.

For more information on the required fields and other payment/reporting services, please visit the CardConnect Gateway API.

REST Implementation

REST Web Services utilize the HTTP Verbs GET, POST, PUT and DELETE to implement CRUD (Create / Replace / Update / Delete) functions.

POST operations are required for all Bolt P2PE service endpoints.

JSON

This web service utilizes the JSON (JavaScript Object Notation) method of encoding data for transmission via the HTTP network protocol. JSON is a rich but lightweight data definition language, considerably simpler than XML but with similar functionality, such as nested data structures and arrays. Most programming languages have libraries to convert an arbitrary object to and from a JSON data transfer encoding. CardConnect provides a sample client application in the JAVA language implementing all functions described herein.

The REST Service expects ALL properties encoded as US ASCII Strings.

CardConnect reserves the right to add new key/value pairs within the JSON response.

Connecting to the Server

The BOLT P2PE REST Web Service base URL includes a protocol, host, port and servlet specification, such as:

https://<subdomain>.cardpointe.com:<port>/api/v2

An API key is required as the HTTP Authorization Header in each REST request. The API key will be provided by a CardConnect Integrated Solutions specialist and can be used for one, or a group of Merchant ID(s). If not provided or not correct in the request, an HTTP Exception "401:Unauthorized" is returned to the caller. An example is below:

Authorization: QWxhZGluOnNlc2FtIG9wZW4sjajlkHJApa=

CardConnect validates various parameters of a BOLT P2PE request. Please review the Response Codes within this page to understand the information conveyed by each.

In the case of invalid message format or missing data, the message may be re-sent. However, most errors indicate a persistent problem and will require operator action to correct.

Run in Postman

For those who have received a Bolt terminal and API key from CardConnect, click below to get a template for all of the available Bolt API endpoints.

Run in Postman

Service Endpoints

The following table details each service of the Bolt P2PE API, its associated resource name, and which version it's supported in. The service name and intended version is appended to the base URL.

Example URL:https://<subdomain>.cardpointe.com:<port>/api/v2/display

Details about the REST implementation for each endpoint follow this section.

Service Resource Name Supported Version(s) Requires Session Key
listTerminals listTerminals v1 + v2 false
ping ping v1 + v2 v1: false
v2: true
display display v1 + v2 v1: false
v2: true
cancel cancel v1 + v2 v1: false
v2: true
compositeReadCard compositeReadCard v1 + v2 false
compositeReadManual compositeReadManual v1 + v2 false
getPanPadVersion getPanPadVersion v2 true
dateTime dateTime v2 true
preconnect preconnect v2 false
connect connect v2 false
disconnect disconnect v2 true
readCard readCard v2 true
readManual readManual v2 true
readConfirmation readConfirmation v2 true
readInput readInput v2 true
readSignature readSignature v2 true
readCard readCard v2 true
readManual readManual v2 true
authCard authCard v3 true
authManual authManual v3 true

listTerminals

The URL for the listTerminals service is: https://<subdomain>.cardpointe.com:<port>/api/v2/listTerminals

hsn: Hardware Serial Number of an individual terminal
merchantId: Merchant Account Identifier

A request to listTerminals returns an array of all HSN's for a particular merchant ID, as shown in the sample below:

List Terminals

This array can be graphically presented to a user prompting a selection. The user's selection of the HSN could be sent back to the web/application server and stored. 

dateTime

The URL for the dateTime service is: https://<subdomain>.cardpointe.com:<port>/api/v2/dateTime

Sends a dateTime request to the terminal to set the terminal's system time. The dateTime field should be an ISO-8601 local date time (i.e. no timezone offset). Hyphens(-) for dates and colons(:) for times are required.

Examples: 2016-11-29T11:30:45 or 2016-11-29T18:30

getPanPadVersion

The URL for the getPanPadVersion service is: https://<subdomain>.cardpointe.com:<port>/api/v2/getPanPadVersion

Retrieves the version of PanPad/bolt terminal application running on the provided HSN.

getPanPadVersion requires a CardConnect session key.

ping

The URL for the ping service is:

https://<subdomain>.cardpointe.com:<port>/api/v2/ping

Sends a ping command to terminal. Returns a true response if communication with the terminal is successful.

Confirm Terminal Connectivity

A ping request can be sent from the application to confirm that a terminal is connected to the Bolt service. It is recommended to call ping as the initial step during a terminal interaction and often throughout the lifetime of a user's session.

preconnect

Initiates dual factor authentication between a Bolt terminal and that POS user. Will display a 6 char alpha/num token on terminal for 60 (configurable) seconds. Client must pass that token on the connect call in order to establish a session.

Dual-factor authentication must be enabled for each merchantId, and it will be required when enabled.

If the preconnect request is successful (i.e. a 200 response is returned), the terminal should display an authentication token:

Preconnect Token

preconnect does not have the 'force' property that connect has. Inflight transactions will not be cancelled as a part of the /preconnect API and "terminal in use" errors will be returned if there is an inflight transaction.

This token will be displayed for up to 60 seconds (configurable duration) or until a successful connect call is made. The token can then be used as a parameter of the subsequent connect request

The authentication token value is not case-sensitive.

connect

The URL for the connect service is: https://<subdomain>.cardpointe.com:<port>/api/v2/connect

Create a Session

  • Retrieve a CardConnect Session Key to use in subsequent bolt terminal [hsn] requests during an interaction. Then [disconnect] to end the session
  • Optionally pass a "token" which is retrieved through the client application after calling preconnect
  • If "force" is set to true, any existing sessions will be destroyed and all in-flight operations on the terminal will be cancelled.
    • "force" is optional and defaults to false.
  • A session will only be created if the bolt terminal successfully authenticates against TMS and the bolt application checksum is valid.

disconnect

The URL for the disconnect service is: https://<subdomain>.cardpointe.com:<port>/api/v2/disconnect

Close a Session

Release the session key provided in request header.

disconnect requires a CardConnect Session Key.

display

The URL for the display service is: https://<subdomain>.cardpointe.com:<port>/api/v2/display

Sends a text string to be displayed on screen of the terminal. May either be displayed as a single line, multi-line, or none to clear any existing prompt.

The text string that displays on the terminal is limited to 1000 characters.

readConfirmation

The URL for the readConfirmation service is: https://<subdomain>.cardpointe.com:<port>/api/v2/readConfirmation

Gets a confirmation response (true/false) from bolt terminal

readConfirmation requires a CardConnect Session Key.

readInput

The URL for the readInput service is: https://<subdomain>.cardpointe.com:<port>/api/v2/readInput

  • Prompt parameter is displayed on PanPad (1000 Character Limit)
  • Reads data from bolt terminal keypad in the specified format.
  • Format parameter must predefined getInput format (see below) in request.

readInput requires a CardConnect Session Key.

readInput Supported Formats:

MMYY - Date Entry
Nx[,y] - Numeric Entry
  • x = minimum number of digits (if y not specified, user input length must match x)
  • y = maximum number of digits (optional, max 32)
ANx[,y] - Alpha Numeric Entry
  • x = minimum number of characters (if y not specified, user input length must match x)
  • y = maximum number of characters (optional, max 32)
PHONE - Phone Number Format
PHONE - Phone Number Format

Display shows decimal, however amount is returned w/ implied decimal:

readSignature

readSignature is an optional endpoint that displays a request to the user for a signature.  As of April 2018, major card brands no longer require signatures. You will want to assess your business needs to determine whether to implement signature verification. Refer to Updated Signature Requirements for more information.  

Reads a signature from an iSC250 device

The URL for the readSignature service is: https://<subdomain>.cardpointe.com:<port>/api/v2/readSignature

Request Parameters

signatureFormat
- 'bmp' (default if omitted)
- 'jpg'
- 'png'
gzipSignature
If false, signature property in response will contain uncompressed BMP in base64 encoding - (defaults to true)
signatureDimensions Customized width and height of signature image. Format of 'x,y'. Maximum value is '999,999'
signatureImageType This property controls whether the image has a 1-bit color depth vs. 24-bit color depth.
Defaults to 'binary' (1-bit) for bmp and png. jpg will always be 24-bit.
- 'binary' (bmp)
- 'rgb' (png & jpg)

readSignature requires a CardConnect Session Key

cancel

Sends a cancel command to the terminal to cancel the current operation.

The URL for the cancel service is: https://<subdomain>.cardpointe.com:<port>/api/v2/cancel

readCard

A request to the readCard service will initiate the following sequence:

  1. The Bolt service reaches out to the device (hsn)
  2. Ping request is automatically sent and followed by a readcard command with the option to capture signature.

The connection/disconnection made during this request is not related to or creating a session with the terminal.

The URL for the readCard service is: https://<subdomain>.cardpointe.com:<port>/api/v2/readCard

  • readCard is an alias for compositeReadCard (v1)
  • readCard (v2) requires a CardConnect session key
  • compositeReadCard (v1) does not require a CardConnect session key

Request Parameters

Field Description
includeAmountDisplay Controls display of the transaction amount to the end user during an MSR or EMV (card-present) transaction.

Defaults to 'true' if not provided.
includeSignature Controls if the user is prompted to sign when using a signature supporting device.

Defaults to 'true' if not provided.

The signature data returned is a JSON escaped, Base64 encoded, Gzipped, Bitmap (BMP).
signatureFormat
- 'bmp' (default if omitted)
- 'jpg'
- 'png'
gzipSignature
If false, signature property in response will contain uncompressed BMP in base64 encoding - (defaults to true)
signatureDimensions Customized width and height of signature image. Format of 'x,y'. Maximum value is '999,999'
signatureImageType This property controls whether the image has a 1-bit color depth vs. 24-bit color depth.
Defaults to 'binary' (1-bit) for bmp and png. jpg will always be 24-bit.
- 'binary' (bmp)
- 'rgb' (png & jpg)
beep Enables beeping sound to:
- prompt user to swipe/dip card
- if dipping EMV card, when to remove
- key presses during PIN entry if debit card is used
aid Sets the default EMV application ID. Supported values are:
- credit (default if omitted)


Response Parameters

FieldDescription
tokenCardSecure Token
expiryMMYY
nameName on Card
*Not returned if Card/Wallet is read through NFC
singleUseTokentrue/false
*True if Card/Wallet is read through NFC
signatureBase 64 encoded gzipped BMP or format otherwise specified in request

readManual

A request to the readManual service will reach out to the device (hsn), ping, and send a manual entry command with the option to capture signature and/or expiration date. The connection/disconnection made during this request is not related to or creating a session with the terminal.

The URL for the readManual service is: https://<subdomain>.cardpointe.com:<port>/api/v2/readManual
readCard is an alias for compositeReadManual (v1)

Request Parameters

Field Description
includeSignature Defaults to 'true' if not provided
signatureFormat
- 'bmp' (default if omitted)
- 'jpg'
- 'png'
gzipSignature
If false, signature property in response will contain uncompressed BMP in base64 encoding - (defaults to true)
signatureDimensions Customized width and height of signature image. Format of 'x,y'. Maximum value is '999,999'
signatureImageType This property controls whether the image has a 1-bit color depth vs. 24-bit color depth.
Defaults to 'binary' (1-bit) for bmp and png. jpg will always be 24-bit.
- 'binary' (bmp)
- 'rgb' (png & jpg)
includeExpirationDate Defaults to 'true' if not provided
beep Enables beeping sound during keypress
  • readManual (v2) requires a CardConnect Session Key
  • compositeReadManual (v1) does not require a CardConnect Session Key

authCard

The URL for the authCard service is: https://<subdomain>.cardpointe.com:<port>/api/v3/authCard

A request to the authCard service will initiate the following sequence:

  1. The Bolt service reaches out to the device (hsn)
  2. A Ping request is automatically sent followed by a readCard command with the option to capture signature
  3. Then an authorization request on the CardConnect Gateway is run returning the authorization response details.
  4. The authorization response text (resptext), e.g. "Approved" will then be displayed on the terminal.

The connection/disconnection made during this request is neither related to the session management (connect/disconnect), nor does it create a session with the terminal.

authCard (v3) requires a CardConnect session key

Request Parameters

Field Description
merchantId Merchant ID that is associated with your Bolt terminals in the CardConnect terminal management system.

The merchantId may be different than the authMerchantId

Advise with CardConnect Integrated Solutions if further clarification is needed.
authMerchantId
(optional)
Only required if authorization merchant ID is different from Bolt/terminal merchant ID.

The merchantID must have setting in CardConnect enabling this feature

The merchantID and authMerchantID must belong to same Customer ID in CardConnect
amount The amount to be authorized (and captured) for payment
includeSignature Controls if the user is prompted to sign when using a signature supporting device.

Defaults to 'true' if not provided.

The signature data returned is a JSON escaped, Base64 encoded, Gzipped, Bitmap (BMP).
includeAmountDisplay Controls if the amount of the transaction is displayed to the end user during an EMV transaction.

Defaults to 'true' if not provided.
beep Enables beeping sound to:
- prompt the user to swipe/dip card
- if dipping EMV card when to remove
- key presses during PIN entry if debit card
aid Sets the default EMV application ID. Supported values are:
- credit (default if omitted)

includeAVS
(optional - true/false)
Defaults to 'false' if not provided.
If true, prompts user to enter zip code.
capture
(optional - true/false)
Defaults to 'true' if not provided.

Captures the amount for settlement within the authorization request. If not set to "true", the authorization (retref/authcode) will need to be captured in order for the merchant to receive funding of transaction.
userFields
Include additional data in the authorization request for future retrieval by using optional userFields.
The value of the userFields object (or array) is a series of name-value pairs that are meaningful to the merchant. 
The name and value may be any string and the total length of user defined fields, URL/JSON encoded is limited to 4000 bytes.

authManual

The URL for the authManual service is: https://<subdomain>.cardpointe.com:<port>/api/v3/authManual

A request to the authManual service will initiate the following sequence:

  1. The Bolt service reaches out to the device (hsn)
  2. Ping is automatically sent followed by a readManual command, obtaining the card number and expiration date with the option to capture signature
  3. Then an authorization request on the CardConnect Gateway is run returning the authorization response details.
  4. The authorization response text (resptext), e.g. "Approved" will then be displayed on the terminal.

The connection/disconnection made during this request is neither related to the session management (connect/disconnect), nor does it create a session with the terminal.

Request Parameters

Field Description
merchantId Merchant ID that is associated with your Bolt terminals in the CardConnect terminal management system.

The merchantId may be different than the authMerchantId

Advise with CardConnect Integrated Solutions if further clarification is needed.
authMerchantId
(optional)
Only required if authorization merchant ID is different from Bolt/terminal merchant ID.

The merchantID must have BillFlag setting in CardConnect enabling this feature.

The merchantID and authMerchantID must belong to same CustomerID in CardConnect merchant table.
includeSignature Defaults to 'true' if not provided
includeAmountDisplay
(optional - true/false)
Defaults to 'true' if not provided.

Controls if the amount of the transaction is prompted to the user for confirmation and then displayed to the end user.
beep Enables beeping sound during keypress
amount The amount of the transaction
includeAVS
(optional - true/false)
Defaults to 'false' if not provided. If true, prompts user to enter zip code.
includeCVV
(optional - true/false)
Defaults to 'false' if not provided. If true, prompts user to enter CVV.
capture
(optional - true/false)
Defaults to 'true' if not provided.

captures the amount for settlement within the authorization request. If not set to "true", the authorization (retref/authcode) will need to be captured in order for the merchant to receive funding of transaction.

authManual (v3) requires a CardConnect Session Key

Response Codes

All operations will return one of the following HTTP response codes

Response Description
200 Success
400 Bad Request
401 Unauthorized
403 Invalid HSN for MerchantID
500 Bolt Client or Server Error

200: Success

"Success" Response
HTTP/1.1 200 OK
{ 
  "terminals" : [ "12145SC70108037", 
                  "14012PP20131409", 
                  "12155SC70113974",
                  "12150SC70110741" ] 
}

400: Bad Request

Request body does not match expected format, required headers other than Authorization are not included

"Bad Request" Response
HTTP/1.1 400 Bad Request
{ 
    "errorCode" : 12345, 
    "errorMessage" : "'merchantId' expected"
}

401: Unauthorized

API key is invalid or missing, API key does not match merchantId, merchantid omitted

  • Terminal authentication/TMS error
"Unauthorized" Response
HTTP/1.1 401 Unauthorized
(no body)

403: Invalid HSN for MerchantID

"Invalid HSN for MerchantID" Response
HTTP/1.1 403
(no body)

500: Bolt Client or Server Error

The following HTTP/1.1 500 Internal Server Error errors will be thrown for any of the following reasons:

Terminal request timed out

{ "errorCode" : 1, "errorMessage" : "Terminal request timed out" }

Terminal already in use

{ "errorCode": 7, "errorMessage" : "Terminal 15128SC80547978 is already in use" }

Command Cancelled

{ "errorCode" : 8, "errorMessage": "Command Cancelled" }

Request method not supported

{ "errorCode": 1, "errorMessage": "Request method 'GET' not supported" }

Invalid content type

{ "errorCode": 1, "errorMessage": "Content type 'aplication/json' not supported" }

Error Codes

Error Code Description Type
000 No error/OK response Generic
001 Generic catch all error - Server failed Generic
003 Invalid Request Generic
004 Missing required parameter(s) Generic
006 Terminal not connected Generic
007 Terminal in use Generic
008 Command canceled by terminal/User Generic
100 Internal Server Error if no terminals found for merchant listTerminals
200 .... ping
300 .... display
400 .... compositeReadCard
500 .... compositeReadManual
624 Decryption failure CardSecure
627 Keystore not initialized CardSecure
638 Illegal Characters CardSecure
643 Server failed CardSecure
646 Database problem CardSecure
655 Missing or unknown sitename CardSecure
666 Unauthorized terminal CardSecure

Release Notes

Bolt v3

Release Date: 5/15/17

  • authCard and authManual
    • In V1 and V2 (readCard/readManual), Bolt servers would simply return a token that could be used in a separate call to the CardConnect Gateway's authorization service.
    • These new endpoints will consume additional payment details and run the authorization automatically, returning not only the token but the entire authorization response via Bolt.
  • New "AMOUNT" format option available for readInput service endpoint will allow users to enter a dollar amount on the Bolt terminal.

Bolt v2

Release Date: 4/24/17

  • Card Read and Manual Entry
    • Simplifies and extends capabilities to interact with card-present and manual entry functions
    • Token responses will contain expiration date (expiry), name on card, and signature data
  • Sessioning
    • Maintain control of one device during an interaction/session. Especially helpful if multiple clients/workstations are attempting to use the same device.
    • Call connect to retrieve a key, and use it during the terminal (hsn) session until it is disconnected.
    • Optionally display an auth token on the device, prompting the user to authenticate with it on the POS
  • Retrieve data and interact with terminal users.