We're excited to announce a new addition to our developer resources. Our CardConnect Developer Guides provide additional information for integrating CardConnect products and services. 

You can browse the whole library at https://developer.cardconnect.com/guides/home, or jump right to the Bolt Developer Guides to make the most of your Bolt integration. 

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

Browse the CardConnect Developer Guides library for general information on integrating our products and services, or jump right to the Bolt Developer Guides to make the most of your Bolt integration.

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.

What's New?

Date Updated: 11/15/2019

The following updates were deployed to the UAT environment on 11/15/2019. 

Note: These updates will not be deployed to the production environment until after January 1, 2020. 

Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications. 

New authCard and authManual Response Fields

The authCard and authManual responses now include the following fields:

RequestFieldTypeDescription
authCard/authManualreceiptDataArrayAn object that includes additional transaction information to be printed on a receipt.

See the Receipt Data Fields description in the CardPointe Gateway API for a list of the possible fields returned.
authCard/authManualorderidStringThe order ID included in the authCard or authManual request, or the automatically-generated order ID if no value was included in the request.
authCard/authManualentrymodeStringNote: Currently, entrymode is only returned for merchants processing on the First Data North (FNOR) platform.

The point-of-sale (POS) payment entry mode.

Possible values are:
  • Keyed
  • Moto
  • ECommerce
  • Recurring
  • Swipe(Non EMV)
  • DigitalWallet
  • EMVContact
  • Contactless
  • Fallback to Swipe
  • Fallback to Keyed
authCard/authManualbintypeStringNote: Currently, bintype is only returned for merchants processing on the First Data North (FNOR) platform.

The type of card used, determined by the BIN. 

Possible values are:
  • Corp
  • FSA+Prepaid
  • GSA+Purchase
  • Prepaid
  • Prepaid+Corp
  • Prepaid+Purchase
  • Purchase

RESTful Implementation

The Bolt P2PE RESTful web service uses the JSON (JavaScript Object Notation) method of encoding data for transmission via the HTTP network protocol. Most programming languages have libraries to convert an arbitrary object to and from a JSON data transfer encoding.

The Bolt P2PE API provides a library of POST operations used to submit HTTP requests to the web service. Responses are returned in JSON objects. See Service Endpoints for detailed information on the supported request types and corresponding responses.

Bolt 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. Click the following button to download the collection.

Run in Postman

See Running the API in Postman in the Bolt Developer Guides for information on using the Postman Collection.

Getting Started

See the Bolt Developer Guides for information to help you get started, including guides for understanding the Bolt API application workflow and understanding the Bolt API service endpoints.

Additionally, see the API Connectivity Guide for information on connecting to the Bolt service and other CardConnect products and services.

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://<site>.cardpointe.com/api/v2/display

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

See Understanding the Bolt API Service Endpoints for additional information to help you make the most of your Bolt integration.

Complete List of Bolt API Service Endpoints

Service Resource Name Supported Version(s) Requires Session Key
listTerminals listTerminals v1 + v2 false
dateTime dateTime v1 + v2 v1: false
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://<site>.cardpointe.com/api/v2/listTerminals

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.

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://<site>.cardpointe.com/api/v1/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.
  • Bolt v1 dateTime requests do not require a session key.
  • Bolt v2 dateTime 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.
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://<site>.cardpointe.com/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://<site>.cardpointe.com/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 is not required. 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 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://<site>.cardpointe.com/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.

See Establishing a Session for more information.

Once the session 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://<site>.cardpointe.com/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. The session key can not be used in any subsequent requests; you must call the connect endpoint to retrieve a new session key.

The disconnect command does not cancel an in-flight transaction (for example an authCard request in progress). To terminate an in-flight transaction, call the cancel endpoint.

Endpoint URL

The URL for the disconnect endpoint is:

https://<site>.cardpointe.com/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:

  • Sending a single-line string displays the text in the display footer area, retaining the idle image.
  • Sending a multi-line string displays the text in the primary display area, replacing the idle image.

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.

To include a percent sign (%) in the display text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.

The terminal display is limited to 1000 characters.

Endpoint URL

The URL for the display endpoint is:

https://<site>.cardpointe.com/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.

Note: To include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.

To create a line break to display a multi-line message, 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://<site>.cardpointe.com/api/v3/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://<site>.cardpointe.com/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. 

    Note: To include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
    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

    A call to the readInput endpoint sends a prompt to the terminal to request user input, in a format specified in the request.

    See Using readInput to Capture Customer Information for more information.

    Endpoint URL

    The URL for the readInput endpoint is:

    https://<site>.cardpointe.com/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.

    Note:
     To include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
    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

    The following values are case-sensitive. For example, you must enter "PHONE" not "phone" or "Phone." entering an incorrect value returns the error "errorMessage": "Invalid Format." 

    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.

    See Capturing and Handling Cardholder Signatures for guidance on how and when to capture signatures.

    Endpoint URL

    The URL for the readSignature endpoint is:

    https://<site>.cardpointe.com/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.

    Note: To include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
    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://<site>.cardpointe.com/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.

      See Using the Bolt Tokenization and Payment Endpoints for more information.

      Endpoint URL

      The URL for the readCard endpoint is:

      https://<site>.cardpointe.com/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.
      amountThe dollar amount to be authorized, with two implied decimal places (for example, to specify "$10.00," enter "1000"). 
      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.

      See Using the Bolt Tokenization and Payment Endpoints for more information.

      Endpoint URL

      The URL for the readManual endpoint is:

      https://<site>.cardpointe.com/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.
      amountThe dollar amount to be authorized, with two implied decimal places (for example, to specify "$10.00," enter "1000").
      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 an Authorization request to the CardPointe gateway.

      See Using the Bolt Tokenization and Payment Endpoints for more information.

      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://<site>.cardpointe.com/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.
      amount The dollar amount to be authorized and captured, with two implied decimal places (for example, to specify "$10.00," enter "1000").

      Amount can be a positive or negative value. If negative, the transaction is treated as a refund without reference (forced credit). Note that the merchant account must be enabled to process forced credit transactions.
      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.

      orderId

      A unique order ID used to identify the transaction. This value is an alphanumeric string with a maximum of 19-characters. If no order ID is specified in the request, Bolt automatically generates a unique order ID in the format <HSN-timestamp> and amends it to the transaction record.

      You can use the order ID to get information on a transaction using the CardPointe Gateway API inquireByOrderid endpoint.

      Additionally, when an authorization attempt times out and Bolt does not receive a response from the CardPointe Gateway, Bolt uses the order ID to make an inquireByOrderid request to check the status of the transaction. If Bolt cannot determine the status of the request, it makes three voidByOrderId requests to void the transaction. See Handling Timeouts in the Bolt Developer Guides for more information.

      Note: If you include an order ID you must ensure that it is a unique value. Using duplicate order IDs can lead to the wrong transaction being voided in the event of a timeout.

      createProfile

      Specifies whether or not to create a stored profile using the payment data in the request. 

      If true, Bolt initiates a profile create request to the CardPointe Gateway API profile endpoint. 

      If false, no profile is created. Defaults to false if not specified.

      See the CardPointe Gateway API profile endpoint description for detailed information.

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

      Defaults to true if not provided. 
      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, Base64-encoded bitmap (.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.
        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.
        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.

        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.

        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.

        See Using the Bolt Tokenization and Payment Endpoints for more information.

        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://<site>.cardpointe.com/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

        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.

        hsnThe terminal hardware serial number.
        amount The dollar amount to be authorized and captured, with two implied decimal places (for example, to specify "$10.00," enter "1000").

        Amount can be a positive or negative value. If negative, the transaction is treated as a refund without reference (forced credit). Note that the merchant account must be enabled to process forced credit transactions.
        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.

        orderId

        A unique order ID used to identify the transaction. This value is an alphanumeric string with a maximum of 19-characters. If no order ID is specified in the request, Bolt automatically generates a unique order ID in the format <HSN-timestamp> and amends it to the transaction record.

        You can use the order ID to get information on a transaction using the CardPointe Gateway API inquireByOrderid endpoint.

        Additionally, when an authorization attempt times out and Bolt does not receive a response from the CardPointe Gateway, Bolt uses the order ID to make an inquireByOrderid request to check the status of the transaction. If Bolt cannot determine the status of the request, it makes three voidByOrderId requests to void the transaction. See Handling Timeouts in the Bolt Developer Guides for more information.

        Note: If you include an order ID you must ensure that it is a unique value. Using duplicate order IDs can lead to the wrong transaction being voided in the event of a timeout.

        createProfile

        Specifies whether or not to create a stored profile using the payment data in the request. 

        If true, Bolt initiates a profile create request to the CardPointe Gateway API profile endpoint. 

        If false, no profile is created. Defaults to false if not specified.

        See the CardPointe Gateway API profile endpoint description for detailed 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.

        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.

        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 specify a tip amount on the terminal.

        See Using the Bolt API Tokenization and Payment Endpoints for more information.

        Endpoint URL

        The URL for the tip endpoint is:

        https://<site>.cardpointe.com/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.
        • To include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
        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 two 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

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

        Defaults to true.

        tipPercentPresets

        Specifies an array of three preset tip percentages. 

        Note: The ability to set four preset values is planned for a future enhancement.

        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.

        In the event that an authorization attempt was successfully initiated before the command sequence timed out or was canceled, the response body returned for errorCode 1 and errorCode 8 include the authorization response data returned from the CardPointe Gateway in an authResponse object.

        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 The in-flight request (for example an authCard command sequence) was canceled. The error includes one of the following messages, which describe the specific cancellation scenario.
        • Command Cancelled - The client application sent a cancel request.
        • Operation Cancelled - The cardholder or merchant canceled a readCard sequence at the terminal.
        • Authorization Cancelled - The client application, merchant, or cardholder attempted to cancel an authCard or authManual request; however, Bolt already submitted the authorization request to the CardPointe Gateway. In this case, the authorization was processed, and the error includes an authResponse object that contains the authorization response from the CardPointe Gateway.
        Bolt Client/Server
        100 Internal Server Error if no terminals found for merchant Bolt listTerminals response
        400 PIN Debit not supported for merchantID <MID> 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