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 connect to the services described within this guide via HTTPS 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

Physical Device Connection

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.

Create a Session

Most V2 endpoints require the use of a session key. A session is created between a client and a specific Bolt terminal by calling connect.

The session key returned will be used in all subsequent requests (readCard, getInput, ping) to the terminal and any requests without the current session key will be blocked.

It's recommended to call disconnect once the interaction is complete, but if not, the session will eventually expire.

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.

Run a Payment

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

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

As an alternative to submitting the authorization request outside of the interface with the Bolt API, the authCard and authManual endpoints offer convenience methods to submit payments on the CardConnect Gateway via the Bolt API.

REST Implementation

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 JSON.

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 (aka readCard) v1 + v2 false
compositeReadManual compositeReadManual (aka readManual) v1 + v2 false
getPanPadVersion getPanPadVersion v2 true
dateTime dateTime v2 true
preconnect preconnect v2 false
connect connect v2 false
disconnect disconnect 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 to the right:

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. 

  • v1: ping requests do not require a session key.
  • v2: ping requests require a session key. 

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 requests to a specific terminal. 
Response Header Returned:
X-CardConnect-SessionKey →f4fb39ff5c9c4299b3d7b34ca7ce2348;expires=2018-09-25T16:26:48.482Z

Subsequent Request Header must be in the following format:
X-CardConnect-SessionKey: f4fb39ff5c9c4299b3d7b34ca7ce2348
  • Once the interaction is complete, call disconnect to end the session; otherwise the session will expire at the the ISO 8601 time stamp provided in the initial connect response.
  • Optionally pass an auth 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.

clearDisplay

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

Sends a display command to the PanPad with an empty string as the prompt

    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

    FieldDescription
    signatureFormat
    - 'bmp' (default if omitted)
    - 'jpg'
    - 'png'
    gzipSignature
    If 'false', signature property in response will contain uncompressed BMP in base64 encoding. 

    Defaults to 'true' if not provided. 
    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.
    confirmAmountControls if the amount confirmation screen is displayed prior to prompting to "insert/swipe/tap" card.

    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' if not provided. 
    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' if not provided. 
    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) by default.
    gzipSignatureIf 'false', signature property in response will contain uncompressed BMP in base64 encoding. 

    Defaults to 'true' if not provided.
    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)
    If 'true', prompts user to enter zip code.

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

    Defaults to 'false' if not provided.
    capture
    (optional - true/false)
    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.

    Defaults to 'true' if not provided.
    gzipSignatureIf 'false', signature property in response will contain uncompressed BMP in base64 encoding.

    Defaults to 'true' if not provided.
    userFields
    (optional)
    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.
    orderId
    (optional)
    Source system order number. Strongly encouraged to populate this field with a unique value that can identify the sales order.
    Alphanumeric, max length = 19
    clearDisplayDelay
    (optional)
    Number of milliseconds to wait after an authCard request completes before clearing the auth status from the terminal display.
    • Set to 0 to disable clearing of the display after authCard
    • If not provided (null), the default delay configured in Bolt will be used

    Response Parameters 

    See Authorization Response for details.

    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.

    authManual (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 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)
    Controls if the amount of the transaction is prompted to the user for confirmation and then displayed to the end user.

    Defaults to true if not provided. 
    beep Enables beeping sound during keypress
    amount The amount of the transaction
    includeAVS
    (optional - true/false)
    If true, prompts user to enter zip code.

    Defaults to false if not provided.
    includeCVV
    (optional - true/false)
    If true, prompts user to enter CVV.

    Defaults to false if not provided. 
    capture
    (optional - true/false)
    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.

    Defaults to true if not provided. 
    orderId
    (optional)
    Source system order number. Strongly encouraged to populate this field with a unique value that can identify the sales order.
    Alphanumeric, max length = 19
    clearDisplayDelay (optional)Number of milliseconds to wait after an authManual request completes before clearing the auth status from the terminal display.
    • Set to 0 to disable clearing of the display after authManual response is received. 
    • If not provided (null), the default delay configured in Bolt will be used.

    Response Parameters 

    See Authorization Response for details.

    General 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
    400 PIN Debit not supported compositeReadCard/authCard
    500 Generic 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
    700Signature capture not supported by deviceSignature

    API Release Notes

    Release Date: 8/23/18

    • New clearDisplay endpoint
    • Add orderId request parameter to authCard and authManual
    • Add beep request parameter to readInput and readConfirmation
    • Trim whitespace off of request properties
    • Support for EMV tags through authCard and readCard see Authorization Response | EMV Tags

    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.