Overview

The CardConnect Bolt P2PE API streamlines the integration of our Bolt P2PE validated card-present payment acceptance solution with your software system.

The Bolt solution consists of the following components:

  • The Bolt API, which provides your software with access to the Bolt services.
  • The Bolt terminal application, running on pre-provisioned terminals provided by CardConnect. The Bolt terminal application is EMV pre-certified and enables you to quickly achieve EMV acceptance and PCI scope reduction.
  • The CardPointe Gateway, CardConnect's payments gateway, which provides a complete solution for transaction processing and reporting. 
  • CardSecure, which tokenizes payment card information.
  • Your point-of-sale (POS) software, integrated with the Bolt P2PE solution.

The CardPointe Gateway API provides additional capabilities not offered by Bolt, including the ability to void or inquire on past transactions. To take full advantage of these features, you must integrate the CardPointe Gateway API into your payment acceptance solution. See the CardPointe Gateway API documentation for information on integrating these features and other advanced capabilities.

Requirements

Integrating the Bolt API requires: 

  • Your application, which calls the Bolt service endpoints via HTTPS. 
  • A terminal device, pre-provisioned and provided by CardConnect.

Additionally, integrating EMV acceptance requires your merchant account to be on a CardConnect and EMV-supported processing platform. 

For more Information on specific requirements contact integrationdelivery@cardconnect.com.

Additional Resources

Visit the CardConnect Support Site for more details on the Bolt P2PE device integration solution and sample applications.

Review the CardPointe Gateway API Developer Documentation for more information on the additional transaction processing and reporting capabilities offered by the CardPointe Gateway, for example the ability to void and inquire on transactions.

Bolt API Release Notes

The following entries describe the Bolt version history and changes to the Bolt API.

Recent Bolt Updates

Release Date: 11/29/18

The current release of Bolt includes the following enhancements:

  • New tip Endpoint

    The new tip endpoint allows you to prompt a user for a tip. You can specify up to four preset tip percentage amounts, including a custom amount option that allows the user to enter a custom tip amount.

  • Developer Documentation Improvements

    The Bolt P2PE API Developer Documentation has been updated with numerous improvements, including:

    • An updated Postman Collection and additional information for getting started.
    • More detailed and consistent service endpoint descriptions and API documentation.
    • Revised content and improved layout, throughout.

Release Date: 8/23/18

The current release of Bolt includes the following enhancements:

Bolt v3 Release Notes

Release Date: 5/15/17

Bolt v3 includes the following enhancements:

  • One-step authorization and capture

    The Bolt API now provides convenient authorization methods using the authCard and authManual services. 

    In Bolt v1 and v2 the readCard and readManual services provided the ability to retrieve a token that could be used in a separate call to the CardPointe Gateway's Authorization service.

    The new authCard and authManual services consume additional payment details and run the authorization automatically, returning not only the token but the entire authorization response using the Bolt API.

  • Enhanced terminal integration capabilities

    The readInput service now supports the amount request parameter, which allows users to enter a dollar amount on the Bolt terminal.

Bolt v2 Release Notes

Release Date: 4/24/17

Bolt v2 includes the following enhancements:

  • Enhanced card-present capabilities

    The new readCard and readManual services simplify and extend card-present merchant capabilities.

    Requests to these services retrieve tokens which can contain the expiration date, name on card, and signature data. These tokens can then be used in requests to the CardPointe Gateway API Authorization endpoint.

  • Terminal sessions and two-factor authentication

    • The connect service retrieves a session key from Bolt, and uses that key to establish a session between the terminal and Bolt. The session key is then used in each request to the terminal until the session is ended.

      Terminal sessions allow control of a device during an active session. This is especially useful if multiple clients or workstations are attempting to use the same device.

    • Additionally, the new preconnect service can be used to require two-factor authentication to establish a terminal session. A call to this service displays an authorization token on the terminal, which must then be returned to the POS software to establish the terminal session.

      Note that this feature requires the merchant account to be configured to use two-factor authentication, and that once two-factor authentication is enabled for a merchant, it becomes required.

  • Enhanced terminal integration capabilities

    • The readConfirmation and readSignature services are now individual endpoints of the Bolt API.

    • The new readInput service allows the client to prompt the user to enter information at the terminal, and then retrieves that data input from the device.

REST Implementation

You use POST operations to make requests to the Bolt P2PE service endpoints.

JSON

The Bolt P2PE web service utilizes the JSON (JavaScript Object Notation) method of encoding data for transmission via the HTTP network protocol. JSON is simpler than XML but provides 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 that ALL properties are encoded as US ASCII strings.

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

Run in Postman

To help you get started with your integration CardConnect, provides a sample Postman Collection that includes a template of the Bolt API service endpoints. 

Run in Postman

Configuring Your Postman Environment

The Bolt API service templates in this collection use Environment variables to simplify your integration. Environment variables allow you to autofill select fields with pre-configured values. For example, instead of manually specifying your merchant ID in the body of each request, you can set the {{merchantid}} variable to your specific MID. 

Once you have received a Bolt terminal and API key from CardConnect, you can configure the following variables to auto-fill your merchant-specific data in requests to the Bolt API:

  • url - Set this value to the root URL that you received from CardConnect. The {{url}} variable is used to set the base url (host and port) for for the Bolt REST web services.
  • Authorization - Set this value to the API key that you received from CardConnect. The {{Authorization}} variable is used in the header of every request.
  • merchantId - Set this value to your CardConnect MID. The {{merchantid}} variable is used in the body of most requests.
  • hsn - Set this value to the hardware serial number (HSN) for your terminal.  The {{HSN}} variable is used in the body of most requests.
  • X-CardConnect-SessionKey - Set this value to a valid session key. Session keys are returned by successful requests to the connect endpoint. The {{X-CardConnect-SessionKey}} variable is required in the header of some requests. See Complete List of Bolt API Service Endpoints for information on which requests require a session key.

To create environment variables, do the following in Postman:

  1. Click New in the toolbar, then select Environment.
  2. On the Manage Environments screen, enter a name for the new Environment.
  3. Add variables for your merchant-specific data, as follows:
  4. Click Update.

See the Postman user documentation for detailed information on configuring your environment and using variables.

Application Workflow

Connect the Terminal Device

Once a Bolt terminal is provisioned and delivered to a client, it must be connected to the client's network using the provided Ethernet cable, or using Wi-Fi (for Ingenico iSMP4 devices).

The terminal displays 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 can receive requests from an application.

Create a Session

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

The session key returned must be used in all subsequent requests to the terminal (for example, readCard or ping); any requests without the current session key will be blocked.

It is recommended that you call the disconnect service once the interaction is complete. If you do not manually disconnect the session, the session key expires.

Get a Token and Run a Payment

The Bolt P2PE solution is integrated with CardSecure, which encrypts and tokenizes the customer's payment card data. Bolt retrieves the token, which can then be used in an authorization request to the CardPointe Gateway to run a payment. 

The Bolt API provides the following methods for either tokenizing payment card data or getting a token and running a payment: 

  • If you use the Bolt API readCard or readManual endpoint to get a token, you must then pass that token in an authorization request from your client application, using the CardPointe Gateway API
  • If you use the Bolt API authCard or authManual endpoint to get a token, Bolt passes the token in an authorization request to the CardPointe Gateway. 

Regardless of which method you implement, the payment authorization is handled by the CardPointe Gateway. 

In addition to handling payment requests, the CardPointe Gateway also provides methods for voiding and refunding transactions, and for gathering reporting data. Integrate your application using the CardPointe Gateway API to take full advantage of these and other features offered by the CardPointe Gateway. For more information, see the CardPointe Gateway API documentation.

The following table describes the Bolt API tokenization and payment request methods in greater detail:

Environment EndpointDescription
Card Present readCardThis endpoint is used to get a token.

The readCard endpoint requests card input (MSR, EMV, or NFC) and retrieves the encrypted data from the terminal. Encrypted data is sent to CardSecure for tokenization, and the token is returned to the client application to be passed in a subsequent authorization request to the CardPointe Gateway API.
Card PresentauthCardThis endpoint is used to get a token and run a payment.

The authCard endpoint requests card input (MSR, EMV, or NFC), and retrieves the encrypted data from the terminal. Encrypted data is sent to CardSecure for tokenization, and the token is returned to Bolt, which initiates an authorization request to the CardPointe Gateway. 
Card Not Present readManualThis endpoint is used to get a token.

The readManual endpoint requests manually-entered card input and retrieves the encrypted data from the terminal. Encrypted data is sent to CardSecure for tokenization, and the token is returned to the client application to be passed in a subsequent authorization request to the CardPointe Gateway API.
Card Not PresentauthManualThis endpoint is used to get a token and run a payment.

The authManual endpoint requests manually-entered card input, and retrieves the encrypted data from the terminal. Encrypted data is sent to CardSecure for tokenization, and the token is returned to Bolt, which initiates an authorization request to the CardPointe Gateway. 

About CardConnect Tokens

CardConnect tokens never expire.

Payment card tokens are generally 16-digit numeric tokens with the following characteristics:

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

Connecting to the Server

The Bolt P2PE REST Web Service base URL includes a protocol, host, port and servlet specification. For example:

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

An API key is required as the HTTP authorization header in each POST request. The API key is provided by a CardConnect Integrated Solutions specialist and can be used for one Merchant ID (MID) or a group of MIDs. 

The following example shows an API key supplied as a basic authorization header:

Authorization: QWxhZGluOnNlc2FtIG9wZW4sjajlkHJApa=

It is a best practice to maintain your API key on an application server, rather than in the client application to ensure that the key value is secure. This requires that all requests and responses are managed by the server, not the client. 

If the API key is missing or incorrect in the request, an HTTP Exception "401:Unauthorized" is returned to the caller. 

CardConnect validates various parameters of a Bolt P2PE request. Review the HTTP Response Codes to understand the information conveyed by each response.

In the case of an invalid message format or missing data, the message can be resent; however, most errors indicate a persistent problem and will require operator action to correct.

Service Endpoints

The following table details each service of the Bolt P2PE API, its associated resource name, and which version it is supported in. The Bolt API version and endpoint name are 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.

Complete List of Bolt API Service Endpoints

Service Resource Name Supported Version(s) Requires Session Key
listTerminals listTerminals v1 + v2 false
dateTime dateTime v2 true
getPanPadVersion getPanPadVersion v2 true
ping ping v1 + v2 v1: false
v2: true
preconnect preconnect v2 false
connect connect v2 false
disconnect disconnect v2 true
display display v1 + v2 v1: false
v2: true

clearDisplay

clearDisplayv3true
readConfirmation readConfirmation v2 true
readInput readInput v2 true
readSignature readSignature v2 true
cancel cancel v1 + v2 v1: false
v2: true
readCard readCard v2 true
compositeReadCard compositeReadCard (aka readCard) v1 + v2 false
readManual readManual v2 true
compositeReadManual compositeReadManual (aka readManual) v1 + v2 false
authCard authCard v3 true
authManual authManual v3 true
tiptipv3true

listTerminals

The listTerminals endpoint returns an array of Hardware Serial Numbers (HSNs) for each terminal for the specified merchant ID.

This array can be displayed on the terminal, allowing a user to select the HSN, which can then be sent to the calling application.

For example:

Endpoint URL

The URL for the listTerminals endpoint is:

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

Request Header

The following key/value pairs are required in the request header.

KeyValue
Content-Typeapplication/json
AuthorizationThe CardConnect Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

Request Parameters

Fields in bold are required.

Field Description
merchantId CardConnect merchant ID, required for all requests.

dateTime

A call to the dateTime endpoint sends a request to the specified terminal to set the terminal's system time.

Endpoint URL

The URL for the dateTime endpoint is:

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

Request Header

The following key/value pairs are required in the request header.

KeyValue
Content-Typeapplication/json
AuthorizationThe CardConnect Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

Request Parameters

Fields in bold are required.

Field Description
merchantId CardConnect merchant ID, required for all requests.
hsnTerminal hardware serial number.
dateTimeThe dateTime value must be formatted as an ISO-8601 local date time (no timezone offset).

Hyphens (-) for dates and colons (:) for times are required.

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

getPanPadVersion

A call to the getPanPadVersion endpoint returns the version of the PanPad/Bolt terminal application running on the specified terminal.

Endpoint URL

The URL for the getPanPadVersion endpoint is:

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

Request Header

The following key/value pairs are required in the request header.

KeyValue
Content-Typeapplication/json
AuthorizationThe CardConnect Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

Request Parameters

Fields in bold are required.

Field Description
merchantId CardConnect merchant ID, required for all requests.
hsnTerminal hardware serial number.

ping

A call to the ping endpoint sends a ping command to the specified terminal. The response is true if communication with the terminal is successful. 

You might want to send intermittent ping requests to the terminal to monitor the terminal's connection to the Bolt service.

Endpoint URL

The URL for the ping endpoint is:

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

Request Header

The following key/value pairs are required in the request header.

KeyValue
Content-Typeapplication/json
AuthorizationThe CardConnect Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.
  • Bolt v1 ping requests do not require a session key.
  • Bolt v2 ping requests do require a session key. 

Request Parameters

Fields in bold are required.

Field Description
merchantId CardConnect merchant ID, required for all requests.
hsnTerminal hardware serial number.

Response Parameters

Field Description
connected Returns true if the terminal is connected to the Bolt service, or false if the terminal is not connected.

preconnect

The preconnect endpoint initiates a two-factor authentication process between a Bolt terminal and the Bolt service. a successful response displays a 6 character alpha-numeric token on the terminal, which must then be used to make a connect request to establish a session with the Bolt service. The token displays for 60 seconds (configurable), or until a successful connect request is made. 

To use this feature, two-factor authentication must be enabled for the merchant. Note that two-factor authentication is required when it is enabled.

The following example illustrates a successful response displayed on a Bolt terminal:

The authentication token value is not case-sensitive.

Endpoint URL

The URL for the preconnect endpoint is: 

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

Request Header

The following key/value pairs are required in the request header.

KeyValue
Content-Typeapplication/json
AuthorizationThe CardConnect Authorization Key

Unlike the connect endpoint, the preconnect endpoint does not include the force property. Therefore, inflight transactions are not cancelled by a preconnect request. Instead, a "terminal in use" error is returned for an inflight transaction.

Request Parameters

Fields in bold are required.

Field Description
merchantId CardConnect merchant ID, required for all requests.
hsnTerminal hardware serial number.

Response Parameters

Field Description
token The 6-digit token to pass to the connect endpoint when two-factor authentication is enabled. This token is displayed on the terminal.

connect

A call to the connect endpoint establishes a session between the terminal and the Bolt service. The response returns a CardConnect session key to use in subsequent requests to the terminal.

For example, if the response header returns 

X-CardConnect-SessionKey →f4fb39ff5c9c4299b3d7b34ca7ce2348;expires=2018-09-25T16:26:48.482Z

Then each subsequent request header must be:

X-CardConnect-SessionKey: f4fb39ff5c9c4299b3d7b34ca7ce2348

If you use the preconnect endpoint to obtain an authorization token for two-factor authentication, you must also include the token in the connect request.

If force is set to true, any existing sessions will be destroyed and all in-flight operations on the terminal will be cancelled. The force parameter is optional and defaults to false.

Once the interaction is complete, call the disconnect endpoint to end the session. Otherwise, the session key will expire at the the ISO-8601 expiration timestamp included in the initial connect response.

Endpoint URL

The URL for the connect endpoint is: 

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

Request Header

The following key/value pairs are required in the request header.

KeyValue
Content-Typeapplication/json
AuthorizationThe CardConnect Authorization Key

Request Parameters

Fields in bold are required.

Field Description
merchantId CardConnect merchant ID, required for all requests.
hsnTerminal hardware serial number.
tokenIf two-factor authentication is enabled, you must include the token returned by the preconnect endpoint.

This token is displayed on the terminal.
forceIf set to true, any existing sessions are destroyed and any in-flight operations on the terminal are cancelled.

If blank, this parameter defaults to defaults to false.

Response Parameters

Field Description
X-CardConnect-SessionKey The session key for the established connection.

disconnect

A call to the disconnect endpoint closes the session and releases the session key provided in the request header.

Endpoint URL

The URL for the disconnect endpoint is:

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

Request Header

The following key/value pairs are required in the request header.

KeyValue
Content-Typeapplication/json
AuthorizationThe CardConnect Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

Request Parameters

Fields in bold are required.

Field Description
merchantId CardConnect merchant ID, required for all requests.
hsnTerminal hardware serial number.

display

A call to the display endpoint sends a text string, which is displayed on the idle terminal. You can display a single-line or multi-line string. 

To send a multi-line string, include \n in the text parameter in the request to create a line break.

Additionally, you can send a blank string, which clears any existing prompts and returns the terminal display to an idle state. You can also call the clearDisplay endpoint to clear the terminal display.

The terminal display is limited to 1000 characters.

Endpoint URL

The URL for the display endpoint is:

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

Request Header

The following key/value pairs are required in the request header.

KeyValue
Content-Typeapplication/json
AuthorizationThe CardConnect Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

Request Parameters

Fields in bold are required.

Field Description
merchantId CardConnect merchant ID, required for all requests.
hsnTerminal hardware serial number.
textThe text to send to the terminal display. The terminal display is limited to 1000 characters.

To create a line break in the display, include \n.

If this field is blank, the terminal display is cleared. 

clearDisplay

A call to the clearDisplay endpoint sends a display command to the terminal with an empty string. This clears the current display prompt.

    Endpoint URL

    The URL for the clearDisplay endpoint is:

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

    Request Header

    The following key/value pairs are required in the request header.

    KeyValue
    Content-Typeapplication/json
    AuthorizationThe CardConnect Authorization Key
    X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

    Request Parameters

    Fields in bold are required.

    Field Description
    merchantId CardConnect merchant ID, required for all requests.
    hsnTerminal hardware serial number.

    readConfirmation

    A call to the readConfirmation endpoint retrieves a confirmation response (either true or false) from the specified terminal. 

    Endpoint URL

    The URL for the readConfirmation endpoint is:

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

    Request Header

    The following key/value pairs are required in the request header.

    KeyValue
    Content-Typeapplication/json
    AuthorizationThe CardConnect Authorization Key
    X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

    Request Parameters

    Fields in bold are required.

    Field Description
    merchantId Merchant ID, required for all requests.
    hsnTerminal hardware serial number.
    promptThe text to send to the terminal display to prompt for confirmation. 
    beepSpecifies whether the terminal beeps until the prompt is accepted.

    If true, beep is enabled. If blank, the value defaults to false.

    Response Parameters

    Field Description
    confirmed Returns true if the prompt was accepted at the terminal, or false if the prompt was canceled.

    readInput

    Endpoint URL

    The URL for the readInput endpoint is:

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

    Request Header

    The following key/value pairs are required in the request header.

    KeyValue
    Content-Typeapplication/json
    AuthorizationThe CardConnect Authorization Key
    X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

    Request Parameters

    Fields in bold are required.

    Field Description
    merchantId Merchant ID, required for all requests.
    hsnTerminal hardware serial number.
    promptThe text to send to the terminal display to prompt for confirmation.

    The prompt parameter has a 1000-character limit.
    formatThe readInput request reads data from the Bolt terminal keypad in the specified format.

    The format must be a valid getInput format.
    beepSpecifies whether the terminal beeps until the prompt is accepted.

    If true, beep is enabled.

    If blank, the value defaults to false.

    getInput Formats

    ValueDescriptionUse
    PHONEPhone Number EntryUse the PHONE format to prompt the terminal to receive a phone number input.

    The terminal displays a phone number input field with dashes (-).

    The response returns the phone number, including dashes.
    AMOUNTAmount EntryUse the AMOUNT format to prompt the terminal to receive an amount input.

    The terminal displays an input field with a dollar sign ($) and decimal. The returned value is numeric only, with the decimal and dollar sign implied.

    For example, if "$123.45" is entered at the terminal, the response returns 12345.
    MMYYMonth/Year Date EntryUse the MMYY format to prompt the terminal to receive a month/year date input. 

    The terminal displays an input field with four digits separated by a forward slash (/). The response returns the 4 digit month and year in the format MMYY.

    For example, if "11/18" is entered at the terminal, the response returns 1118.
    Nx[,y]Numeric EntryUse the Nx[,y] format to prompt the terminal to receive a numeric input.
    N specifies a numeric entry where:
    • x = the minimum number of digits.
    • y = the maximum number of digits, up to 32.
    y is optional, and if y is not specified, then the input must match the length specified by x.

    For example:
    • If you specify N5, then the user input must be a 5-digit number, such as "19406."
    • If you specify N5,9, then the user input can be a number ranging from 5 to 9 digits, such as "08081" or "080819876."
    ANx[,y]Alpha-Numeric EntryUse the ANx[,y] format to prompt the terminal to receive an alpha-numeric input.
    AN specifies an alpha-numeric entry where:
    • x = the minimum number of characters.
    • y = the maximum number of characters, up to 32.
    y is optional, and if y is not specified, then the input must match the length specified by x.

    For example:
    • If you specify AN8, then the user input must be an 8-character entry, such as "A1B2C3D4."
    • If you specify AN1,32, then the user input can be an entry ranging from 1 to 32 characters, such as "A" or "A123."

    Response Parameters

    Field Description
    input Returns the input provided at the terminal. The type and format of the input value depends on the getInput format specified in the request.

    readSignature

    A call to the readSignature endpoint sends a prompt to the terminal to capture the cardholder's signature, which is then returned in the response. The readSignature endpoint is supported for terminal devices that support signature capture.

    As of April 2018, major card brands no longer require signatures. Capturing cardholder signatures is optional; however, you should assess your business needs to determine whether to implement signature verification. Refer to Updated Signature Requirements for more information.  

    Endpoint URL

    The URL for the readSignature endpoint is:

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

    Request Header

    The following key/value pairs are required in the request header.

    KeyValue
    Content-Typeapplication/json
    AuthorizationThe CardConnect Authorization Key
    X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

    Request Parameters

    Fields in bold are required.

    FieldDescription
    merchantIDCardConnect merchant ID, required for all requests.
    hsnThe terminal Hardware Serial Number.
    promptThe text to display on the terminal.
    signatureFormat

    Specifies the signature file format. One of the following values:

    • BMP (this is the default if the value is omitted)
    • JPG
    • PNG
      gzipSignature

      Determines if the captured signature is compressed using Gzip.

      If true, the signature data returned is a JSON-escaped, Base64-encoded, Gzipped, bitmap (BMP) file.

      If false, the signature data returned is an uncompressed BMP in base64-encoded. 

      Defaults to true if not provided.

      signatureDimensions

      Specifies the custom width and height of the signature image, in the format 'x,y'. The maximum value is 999,999.

      signatureImageType

      Specifies if the image has a 1-bit color depth (binary) or 24-bit color depth (RGB).

      This property defaults to binary (1-bit) for BMP and PNG files. JPG files will always be rgb (24-bit).

      Possible values are:

      • binary - 1-bit; the default for BMP and PNG files.
      • rgb - 24-bit; the default for JPG files, and optional for PNG files.

      cancel

      A call to the cancel endpoint sends a cancel command from the POS software to terminate any in-flight operations. 

      Endpoint URL

      The URL for the cancel endpoint is:

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

      Request Header

      The following key/value pairs are required in the request header.

      KeyValue
      Content-Typeapplication/json
      AuthorizationThe CardConnect Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

      Request Parameters

      Fields in bold are required.

      Field Description
      merchantId Merchant ID, required for all requests.
      hsnTerminal hardware serial number.

      readCard

      A call to the readCard endpoint requests swiped (MSR) or inserted (EMV) card data and returns a token to be used in a subsequent Authorization request to the CardPointe gateway. The readCard endpoint does not initiate an Authorization or capture funds. To use Bolt to authorize and capture a transaction, call the authCard endpoint.

      A call to the readCard endpoint initiates the following sequence:

      1. The Bolt service sends a ping command to the terminal to verify the connection.
      2. The Bolt service sends a series of commands to the terminal, based on the options specified in the readCard request. For example:
        1. The terminal displays the transaction amount, and prompts the user to confirm.
        2. The terminal beeps and prompts the user to swipe or insert a card.
        3. The terminal prompts the user for a signature to complete the transaction.
      3. The readCard endpoint returns the tokenized card number, signature, and any additional data to the client.
      4. You can then pass the token and cardholder data in an authorization request to the CardConnect Gateway to capture the funds for the transaction.

      Endpoint URL

      The URL for the readCard endpoint is:

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

      Request Header

      The following key/value pairs are required in the request header.

      KeyValue
      Content-Typeapplication/json
      AuthorizationThe CardConnect Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.
      • readCard (v2) requires a CardConnect session key.
      • readCard (v2) is an alias for compositeReadCard (v1).
      • compositeReadCard (v1) does not require a CardConnect session key.

      Request Parameters

      Fields in bold are required.

      Field Description
      merchantIDCardConnect merchant ID, required for all requests.
      hsnTerminal Hardware Serial Number.
      includeAmountDisplay Determines if the transaction amount is displayed to the user during an MSR or EMV (card-present) transaction.

      Defaults to true if not provided.
      confirmAmountDetermines if the terminal prompts to confirm the the transaction amount prior to prompting to insert/swipe/tap the card.

      Defaults to true if not provided.
      includeSignature Determines if the terminal prompts for a signature for devices that support signature capture.

      Defaults to true if not provided.

      The format of the signature data returned depends on the following parameters.
      signatureFormat

      One of the following values:

      • bmp (this is the default if not provided)
      • jpg
      • png
      gzipSignature

      Determines if the captured signature is compressed using Gzip.

      If true, the signature data returned is a JSON-escaped, Base64-encoded, Gzipped, bitmap (BMP) file.

      If false, the signature data returned is an uncompressed, Base64-encoded BMP file. 

      Defaults to true if not provided.

      signatureDimensions Specifies the custom width and height of the signature image, in the format 'x,y'. The maximum value is 999,999.
      signatureImageType

      Specifies if the image has a 1-bit color depth (binary) or 24-bit color depth (RGB).

      This property defaults to binary (1-bit) for BMP and PNG files. JPG files will always be rgb (24-bit).

      Possible values are:

      • binary - 1-bit; the default for BMP and PNG files.
      • rgb - 24-bit; the default for JPG files, and optional for PNG files.
      beep

      Determines if the terminal beeps to:

      • Prompt the user to swipe/dip the card.
      • Prompt the user to remove the card (EMV transactions).
      • Register key presses during PIN entry for debit transactions.

      If true, beep is enabled.

      Defaults to false if not provided.

      aid

      Sets the default EMV application ID.

      Supported values are:

      • credit (default if not provided)

      Response Parameters

      FieldDescription
      tokenThe tokenized card data returned by CardSecure.
      expiryThe card's expiration date in the format MMYY.
      name

      The cardholder's name on the card.

      The name is not returned if the card or mobile wallet is read through NFC (contactless).

      singleUseToken

      Specifies if the token is only valid for a single use. 

      Set to true if the card or mobile wallet is read through NFC (contactless).
      signature

      The signature captured by the request.

      The signature is a JSON-escaped, Base64-encoded, Gzipped, bitmap (BMP) file unless otherwise specified in request.

      readManual

      A call to the readManual endpoint requests manually-keyed card data and returns a token to be used in a subsequent Authorization request to the CardPointe Gateway. The readManual endpoint does not initiate an Authorization or capture funds. To use Bolt to authorize and capture a transaction, call the authManual endpoint.

      A call to the readManual endpoint initiates the following sequence:

      1. The Bolt service sends a ping command to the terminal to verify the connection.
      2. The Bolt service sends a series of commands to the terminal, based on the options specified in the readManual request. For example:
        1. The terminal displays the transaction amount, and prompts the user to confirm.
        2. The terminal beeps and prompts the user to manually enter the card number.
        3. The terminal prompts the user to enter the card's expiration date
        4. The terminal prompts the user for a signature to complete the transaction.
      3. The readCard endpoint returns the tokenized card number, signature, and any additional data to the client.
      4. You can then pass the token and cardholder data in an authorization request to the CardConnect Gateway to capture the funds for the transaction.

      Endpoint URL

      The URL for the readManual endpoint is:

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

      Request Header

      The following key/value pairs are required in the request header.

      KeyValue
      Content-Typeapplication/json
      AuthorizationThe CardConnect Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.
      • readManual (v2) requires a CardConnect Session Key.
      • readManual (v2) is an alias for compositeReadManual (v1).
      • compositeReadManual (v1) does not require a CardConnect Session Key.

      Request Parameters

      Field Description
      merchantIDCardConnect merchant ID, required for all requests.
      hsnTerminal hardware serial number.
      includeSignature Determines if the terminal prompts for a signature for devices that support signature capture.

      Defaults to true if not provided.

      The format of the signature data returned depends on the following parameters.
      signatureFormat

      One of the following values:

      • bmp (this is the default if not provided)
      • jpg
      • png
      gzipSignature

      Determines if the captured signature is compressed using Gzip.

      If true, the signature data returned is a JSON-escaped, Base64-encoded, Gzipped, bitmap (BMP) file.

      If false, the signature data returned is an uncompressed, Base64-encoded BMP file. 

      Defaults to true if not provided.

      signatureDimensions Specifies the custom width and height of the signature image, in the format 'x,y'. The maximum value is 999,999.
      signatureImageType

      Specifies if the image has a 1-bit color depth (binary) or 24-bit color depth (RGB).

      This property defaults to binary (1-bit) for BMP and PNG files. JPG files will always be rgb (24-bit).

      Possible values are:

      • binary - 1-bit; the default for BMP and PNG files.
      • rgb - 24-bit; the default for JPG files, and optional for PNG files.
      includeExpirationDate

      Determines if the terminal prompts the user to enter the expiration date for the card.

      Defaults to true if not provided
      beep

      Determines if the terminal beeps to register key presses.

      If true, beep is enabled.

      Defaults to false if not provided.

      Response Parameters

      FieldDescription
      tokenThe tokenized card data returned by CardSecure.
      expiryThe card's expiration date in the format MMYY.
      signature

      The signature captured by the request.

      The signature is a JSON-escaped, Base64-encoded, Gzipped, bitmap (BMP) file unless otherwise specified in request.

      authCard

      A call to the authCard endpoint requests swiped (MSR) or inserted (EMV) card data and initiates Authorization request to the CardPointe gateway. 

      A call to the authCard endpoint initiates the following sequence:

      1. The Bolt service sends a ping command to the terminal to verify the connection.
      2. The Bolt service sends a series of commands to the terminal, based on the options specified in the authCard request. For example:
        1. The terminal displays the transaction amount, and prompts the user to confirm.
        2. The terminal beeps and prompts the user to swipe or insert a card.
        3. The terminal prompts the user for a signature.
      3. The captured data is passed in an authorization request to the CardConnect Gateway, which returns the authorization response details.
      4. The authorization response text, resptext,  (for example, "Approved") displays on the terminal.

      The Bolt API does not provide the ability to void or inquire on transactions. See the CardPointe Gateway API documentation for information on integrating these features and other advanced capabilities.

      Endpoint URL

      The URL for the authCard endpoint is:

      https://<subdomain>.cardpointe.com:<port>/api/v3/authCard

      Request Header

      The following key/value pairs are required in the request header.

      KeyValue
      Content-Typeapplication/json
      AuthorizationThe CardConnect Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

      Request Parameters

      Fields in bold are required.

      Field Description
      merchantId

      The CardConnect merchant ID (MID) that is associated with your Bolt terminals in the CardConnect terminal management system.

      The merchantId can be different than the authMerchantId, however both values must belong to the same customer account.

      hsnTerminal hardware serial number.
      authMerchantId

      This value is only required if the authorization merchant ID is different from the Bolt terminal merchant ID. The authMerchantId and merchantId must belong to the same CardConnect customer account.

      This setting must be enabled for your merchant account.

      Contact integrationdelivery@cardconnect.com for additional information.

      amount The amount to be authorized (and captured) for payment.
      includeSignature Determines if the terminal prompts for a signature for devices that support signature capture. 

      Defaults to true if not provided. 
      gzipSignature

      Determines if the captured signature is compressed using Gzip.

      If true, the signature data returned is a JSON-escaped, Base64-encoded, Gzipped, bitmap (.bmp) file.

      If false, the signature data returned is an uncompressed, Base64-encoded bitmap (.bmp) file. 

      Defaults to true if not provided.

      includeAmountDisplay Determines if the transaction amount is displayed to the user during an MSR or EMV (card-present) transaction. 

      Defaults to true if not provided.
      beep

      Determines if the terminal beeps to:

      • Prompt the user to swipe/dip the card.
      • Prompt the user to remove the card (EMV transactions).
      • Register key presses during PIN entry for debit transactions.

      If true, beep is enabled.

      Defaults to false if not provided.

      aid

      Sets the default EMV application ID.

      Supported values are:

      • credit (default if not provided)
      includeAVS

      Determines if the user is prompted to enter the billing zip code for the card.

      If true, prompts the user to enter the zip code.

      Defaults to false if not provided.

      includeCVV

      Determines if the user is prompted to enter the Card Verification Value (CVV) for the card.

      If true, prompts the user to enter the CVV.

      Defaults to false if not provided.

      capture

      Captures the amount for settlement within the authorization request.

      If set to false, the authorization (retref/authcode) must be captured in a separate request in order for the merchant to receive funding for the transaction.

      Defaults to true if not provided.

      userFields

      Enables optional userFields to include additional data in the authorization request for future retrieval.

      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 can be any string and the total length of user defined fields (URL/JSON-encoded) is limited to 4000 bytes.

      orderId

      An optional order ID used to associate the transaction with an order identifier.

      It is strongly recommended that you populate this field with a unique value.

      The orderId can include alphanumeric characters and has a maximum string length of 19 characters.

      clearDisplayDelay
      Specifies the number of milliseconds to wait, after an authCard request completes, before clearing the authorization status from the terminal display and returning to the idle display.

      Set to 0 to disable clearing of the display after an authCard request.

      If not provided (null), the default delay configured in Bolt will be used.

      Response Parameters 

      See Authorization Response for details.

      authManual

      A call to the authManual endpoint requests manually-entered card data and initiates Authorization request to the CardPointe gateway. 

      A call to the authManual endpoint initiates the following sequence:

      1. The Bolt service sends a ping command to the terminal to verify the connection.
      2. The Bolt service sends a series of commands to the terminal, based on the options specified in the authCard request. For example:
        1. The terminal displays the transaction amount, and prompts the user to confirm.
        2. The terminal beeps and prompts the user to manually-enter the card number and expiration date.
        3. The terminal prompts the user for a signature.
      3. The captured data is passed in an authorization request to the CardConnect Gateway, which returns the authorization response details.
      4. The authorization response text, resptext,  (for example, "Approved") displays on the terminal.

      The Bolt API does not provide the ability to void or inquire on transactions. See the CardPointe Gateway API documentation for information on integrating these features and other advanced capabilities.

      Endpoint URL

      The URL for the authManual endpoint is:

      https://<subdomain>.cardpointe.com:<port>/api/v3/authManual

      Request Header

      The following key/value pairs are required in the request header.

      KeyValue
      Content-Typeapplication/json
      AuthorizationThe CardConnect Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

      Request Parameters

      Field Description
      merchantId

      The CardConnect merchant ID (MID) that is associated with your Bolt terminals in the CardConnect terminal management system.

      The merchantId can be different than the authMerchantId, however both values must belong to the same customer account.

      hsnThe terminal hardware serial number.
      authMerchantId

      This value is only required if the authorization merchant ID is different from the Bolt terminal merchant ID. The authMerchantId and merchantId must belong to the same CardConnect customer account.

      This setting must be enabled for your merchant account.

      Contact integrationdelivery@cardconnect.com for additional information.

      includeSignature Determines if the terminal prompts for a signature for devices that support signature capture. 

      Defaults to true if not provided. 
      includeAmountDisplay
      Determines if the transaction amount is displayed to the user during an MSR or EMV (card-present) transaction. 

      Defaults to true if not provided.
      beep

      Determines if the terminal beeps to register key presses.

      If true, beep is enabled.

      Defaults to false if not provided.

      amount The amount to be authorized (and captured) for payment.
      includeAVS

      Determines if the user is prompted to enter the billing zip code for the card.

      If true, prompts the user to enter the zip code.

      Defaults to false if not provided.

      includeCVV

      Determines if the user is prompted to enter the Card Verification Value (CVV) for the card.

      If true, prompts the user to enter the CVV.

      Defaults to false if not provided.

      capture

      Captures the amount for settlement within the authorization request.

      If set to false, the authorization (retref/authcode) must be captured in a separate request in order for the merchant to receive funding for the transaction.

      Defaults to true if not provided.

      orderId

      An optional order ID used to associate the transaction with an order identifier.

      It is strongly recommended that you populate this field with a unique value.

      The orderId can include alphanumeric characters and has a maximum string length of 19 characters.

      clearDisplayDelay Specifies the number of milliseconds to wait, after an authCard request completes, before clearing the authorization status from the terminal display.

      Set to 0 to disable clearing of the display after an authCard request.

      If not provided (null), the default delay configured in Bolt will be used.

      Response Parameters 

      See Authorization Response for details.

      tip

      The tip endpoint is only supported on terminals running firmware version 1.6.3.4.

      A call to the tip endpoint prompts the user to select or enter a tip amount on the terminal.

      You can configure the terminal to display up to four preset tip amounts, or allow users to specify a custom tip amount.

      Endpoint URL

      The URL for the tip endpoint is:

      https://<subdomain>.cardpointe.com:<port>/api/v3/tip

      Request Header

      The following key/value pairs are required in the request header.

      KeyValue
      Content-Typeapplication/json
      AuthorizationThe CardConnect Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

      Request Parameters

      Fields in bold are required.

      FieldDescription
      merchantIdCardConnect Merchant ID, required for all requests.
      hsnThe terminal hardware serial number (HSN).
      prompt

      The text to display to prompt the user to select or enter a tip value.

      Note the following restrictions when specifying the prompt:

      • Ingenico iSC 250 terminals are limited to a maximum of 53 characters on single line.
      • The prompt text cannot include the word "amount"; however, "Amount" is acceptable. The terminal returns a cancel response if "amount" is present.
      amount

      The subtotal amount, used as a baseline to calculate tip percentage amounts

      Note the following restrictions when specifying the amount:

      • Amount cannot be null, 
      • Amount must be a numeric value with 2 implied decimal places (for example, to specify "$10.00," enter "1000").
      • Amount cannot exceed 2147483647
      includeAmountDisplay 
      (optional)

      Determines if the subtotal (amount) and total (amount + tip) is displayed on the terminal. 

      Defaults to true if not provided.

      includeCustomTipAmount
      (optional)

      Determines if a custom tip button is displayed on the terminal.

      Defaults to true if not provided.

      tipPercentPresets

      Specifies an array of fixed percent tip amounts. 

      If includeCustomTipAmount is false, you can specify a maximum of 4 percent values. 

      If includeCustomTipAmount is true you can specify a maximum of 3 percent values.

      Response Parameters

      FieldDescription
      amountThe amount provided in the original request.
      tipThe calculated tip amount based on the user's selection or input.
      totalThe calculated total transaction amount (amount + tip).

      HTTP Response Codes

      All requests 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

      A 200 response indicates that the request was completed successfully and includes the response body. 

      400: Bad Request

      A 400 response indicates that the request could not be completed due to invalid or missing information in the header or body elements. 

      a 400 response can include one of the following error codes:

      Error CodeDescription
      3Generic Error
      4Missing Required Parameter(s)

      Error Code 3 is a generic code, which includes an error message that provides specific contextual information for the error, based on the request. 

      For example, if a the prompt parameter in a call to the readSignature endpoint is greater than 16 characters, the following response is returned:

      { "errorCode" : 3, "errorMessage" : "Prompt text must be less than or equal to 16 characters" }

      The following table describes Error Code 3 conditions that can be returned for calls to each endpoint.

      EndpointError Message
      connectIncorrect token
      dateTimeText could not be parsed
      disconnectSession key for hsn was not valid
      preconnectMerchant is not configured for two-factor authentication
      readInputInvalid format
      readSignaturePrompt text must be less than or equal to 16 characters

      401: Unauthorized

      An HTTP 401 response indicates an authentication error. Authentication errors can occur when the API key is invalid or missing from the Authorization header, the merchant ID is missing from the body or does not match the API key. Authorization errors can also occur due to a terminal configuration error in TMS.

      403: Invalid HSN for MerchantID

      a 403 response indicates that the request included an HSN value that does not match the specified merchant ID.

      500: Bolt Client or Server Error

      A 500 response indicates a Bolt client or Bolt server error. The response includes an error code, which corresponds to one or more specific error messages that describe the error.

      For example, error code 1 denotes a general Bolt client or server error, which can be one of the following:

      • Terminal request timed out

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

      • Request method not supported

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

      • Invalid content type

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

      • Attempting to connect to a terminal with an active session, and the force property is set to false.

        { "errorCode" : 1, "errorMessage" : "Session exists for hsn" }

      The following table describes the various error codes that can be returned in an HTTP 500 response:

      Error codes are fixed; however the error messages associated with each error code are subject to change. 

      Error Code Description Source
      1 Generic catch all error - Server failed Bolt Client/Server
      See 500: Bolt Client or Server Error for more information.
      6 Terminal not connected to the Bolt service (no request queue registered)  Bolt Client/Server
      7 Terminal in use Bolt Client/Server
      8 Command canceled by terminal/User Bolt Client/Server
      100 Internal Server Error if no terminals found for merchant Bolt listTerminals response
      400 PIN Debit not supported for <merchantID> Bolt authCard response
      500 Generic Bolt authManual response
      624 Decryption failure CardSecure
      643 Server failed CardSecure
      700Signature capture not supported by deviceBolt readSignature or authCard, authManual, readCard, or readManual request including a signature