The Bolt Terminal Solution now includes support for the Clover Mini (2nd Generation) and Clover Flex.

See the Bolt Clover Terminal Developer Guide for detailed information for adding Clover terminal devices to your Bolt Terminal integration.

Overview

The Bolt Terminal API streamlines the integration of our Bolt P2PE-validated, card-present payment acceptance solution with your point-of-sale (POS) application. Integrating the Bolt Terminal API with your application, allows you to easily and securely accept card-present payments within your POS environment. 

The Bolt Terminal solution consists of the following components:

  • The Bolt Terminal API, which provides your software with access to the Bolt terminal services.
  • Bolt terminals, pre-provisioned and provided by CardConnect. The Bolt terminal solution supports select Clover and Ingenico terminal devices.
  • 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 Terminal API.

This API reference describes the complete Bolt Terminal API and all supported features and operations. All of the features described in this reference are supported for use with Ingenico terminals; however, some features are currently not supported for use with Bolt Clover terminals. See the Bolt Clover Terminal Developer Guide for detailed information on key differences and additional information specific to integrating Clover terminals.

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.

What's New?

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

PIN Debit Support

The Bolt Terminal solution now supports PIN debit payments for merchants processing on the Rapid Connect platform. 

To update your integration to support PIN debit transactions, you must include the aid and includePIN parameters in your authCard or readCard requests. 

See Accepting PIN Debit Cards in the Bolt Terminal Developer Guides for detailed information on updating your integration to include PIN debit payment workflows.

Before you begin to update your application, note the following important restrictions:

  • New or existing merchants who want to accept PIN debit payments must be boarded to the First Data Rapid Connect platform. Merchants currently accepting PIN debit payments on the First Data North platform will continue to be supported.
  • PIN debit is currently only supported on Bolt Ingenico terminals.
  • Terminals must be provisioned with the necessary encryption keys for handling PIN data.

Date Updated: 3/28/2020

The following updates were deployed to the UAT environment on 11/15/2019 and the production environment on 3/28/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/authManualreceiptDataArrayIf "printReceipt":"true" is included in the request, the response includes the receiptData array. This array 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

Terminal in Merchant Mode Error Response

For Bolt Clover terminals, the following error message is now returned to the calling application when the device is in Merchant Mode:

"errorMessage": "hsn: <hsn> is currently in merchant mode"

See the Bolt Clover Terminal Developer Guide for more information.

Getting Started

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

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

RESTful Implementation

The Bolt Terminal service is a RESTful web service, which 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. See the API Basics and Best Practices Guide for more information on these concepts.

The Bolt Terminal API provides a library of POST operations used to submit HTTP requests to the web service. The Bolt Terminal service expects that ALL properties are encoded as US ASCII strings. Responses are returned in JSON objects. See Service Endpoints for detailed information on the supported request types and corresponding responses.

Changes to the Bolt Terminal API are designed to retain backwards-compatibility. The JSON standard does not assign any significance to the ordering of key/value pairs, and CardConnect does not guarantee the order of key/value pairs in response messages for any of our APIs. See the API Basics and Best Practices Guide for recommendations for retaining backwards compatibility in your application.

Requirements

Integrating the Bolt Terminal API requires: 

  • Your application, which calls the Bolt Terminal service endpoints via HTTPS. 
  • Terminal devices, 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

In addition to this API documentation, the following additional resources are available to help you get started.

Developer Guides

Browse the CardConnect Developer Guides library for general information on integrating our products and services.

The following guides provide helpful information for developing your Bolt Terminal solution:

Additionally, review the CardPointe Gateway API 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.

Run in Postman

To help you get started with your integration, CardConnect provides a sample Postman collection that includes a template of the Bolt Terminal API service endpoints. Click the following button to download the collection.

Run in Postman

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

Service Endpoints

The following table details each service of the Bolt Terminal API, its associated resource name, and which version it is supported in. The Bolt Terminal 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 Terminal API Service Endpoints for additional information to help you make the most of your Bolt Terminal 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, your application might include an option for the merchant to select the terminal to connect to:

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 currently not supported for Bolt Clover terminals.
  • The preconnect endpoint is not required for Bolt Ingenico terminals. 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. 

On a Clover terminal, sending either a single or multi-line message replaces the idle image with the message, along with the logo image (if one is configured for the device).

On an Ingenico terminal:

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

For Ingenico terminals, 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.

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:
     For Ingenico terminals, 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: For Ingenico terminals, 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

      The readCard endpoint is currently not supported for Bolt Clover terminals. See the Bolt Clover Terminal Developer Guide for more information.

      A call to the readCardCard endpoint initiates an MSR (magnetic stripe), EMV (chip), or NFC (contactless) payment card interaction 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 the Bolt Terminal to authorize and capture a transaction, call the authCard endpoint.

      See Using the Bolt Terminal API 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, which processes the request as either a PIN debit or a credit transaction.

      See Accepting PIN Debit Cards for detailed information on PIN Debit requirements and application workflows.

      Note: PIN debit is only supported for qualified merchants boarded on the First Data North and Rapid Connect processing platforms. 

      Supported values are:

      • debit - Set to debit for EMV cards with a debit AID to request a PIN.
      • credit - Set to credit for all other cards. This is the default if no AID is specified.
      includePIN

      Determines if the user is prompted to enter a PIN after card swipe for MSR (magnetic-stripe) debit cards that support PIN.

      See Accepting PIN Debit Cards for detailed information on PIN Debit requirements and application workflows.

      Note: PIN debit is only supported for qualified merchants boarded on the First Data North and Rapid Connect processing platforms. Contact CardPointe Support for more information.

      Set this value to true for MSR debit cards, to process the transaction as debit.

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

      The readManual endpoint is currently not supported for Bolt Clover terminals. See the Bolt Clover Terminal Developer Guide for more information.

      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 Terminal API 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 initiates an MSR (magnetic stripe), EMV (chip), or NFC (contactless) payment card interaction and initiates an Authorization request to the CardPointe Gateway.

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

      The Bolt Terminal 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 it must meet the following requirements: 

      • The order ID must be a unique value. Using duplicate order IDs can lead to the wrong transaction being voided in the event of a timeout.
      • The order ID must not include any portion of a payment account number (PAN), and no portion of the order ID should be mistaken for a PAN. If the order ID passes the Luhn check performed by the CardPointe Gateway, the value will be masked in the database, and attempts to use the order ID in an inquire, void, or refund request will fail.
      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.

      printReceiptFor Clover terminals, specifies whether or not the terminal prints a receipt.

      See Printing Receipts in the Bolt Clover Terminal Developer Guide for detailed information.


      For Ingenico terminals, specifies whether or not the response includes the receiptData array.

      See the Receipt Data Fields description in the CardPointe Gateway API for detailed information.

      Defaults to false if not provided.

      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.

        includeAVS

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

        Note: This field is currently not supported for Clover terminals. If includeAVS is included in the request, it must be set to false.

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

        Sets the default EMV application ID, which processes the request as either a PIN debit or a credit transaction.

        See Accepting PIN Debit Cards for detailed information on PIN Debit requirements and application workflows.

        Note: PIN debit is only supported for qualified merchants boarded on the First Data North and Rapid Connect processing platforms. Contact CardPointe Support for more information.

        Supported values are:

        • debit - Set to debit for EMV cards with a debit AID to request a PIN.
        • credit - Set to credit for all other cards. This is the default if no AID is specified.
        includePIN

        Determines if the user is prompted to enter a PIN after card swipe for MSR (magnetic-stripe) debit cards that support PIN.

        See Accepting PIN Debit Cards for detailed information on PIN Debit requirements and application workflows.

        Note: PIN debit is only supported for qualified merchants boarded on the First Data North and Rapid Connect processing platforms. Contact CardPointe Support for more information.

        Set this value to true for MSR debit cards, to process the transaction as debit.

        Defaults to false if not provided.

        Response Parameters 

        The response includes a subset of the responses available in the CardPointe Gateway Authorization Response. Currently, the authCard response includes the following fields:

        We are continuing to enhance the authCard response to include additional fields. See What's New? for the latest updates to the Bolt Terminal API. 

        FieldComments
        tokenThe token generated for the payment card.
        expiryThe payment card expiration date, in MMYY format.
        signatureJSON escaped, Base64-encoded, Gzipped, BMP of signature data, if a signature was provided with the payment.
        nameThe name on card, if present in the track or EMV data.
        batchidThe identifier for the batch that the transaction was added to. 
        retrefThe retrieval reference number used to look up and manage the transaction.
        avsrespAlpha-numeric AVS (zip code) verification response code.

        Note:
        avsresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account.
        respprocAn abbreviation that represents the platform and the processor for the transaction.
        amountThe amount of the transaction. 

        The authorized amount. For most transactions, this is the same as the request amount.
        For prepaid or gift cards, if partial authorization is enabled for the merchant account, the amount returned is the amount remaining on the card.

        For declines, the amount returned is "0.00"

        resptextA text description of the authorization response.
        authcodeThe Authorization Code from the card issuer.
        respcodeAn alpha-numeric response code that represents the description of the response
        merchidThe merchant ID, copied from the authorization request.
        cvvresp

        Alpha-numeric CVV (card verification value) verification response code.

        One of the following values:

        • M - Valid CVV Match.
        • N - Invalid CVV.
        • P - CVV Not Processed.
        • S - Merchant indicated that the CVV is not present on the card.
        • U - Card issuer is not certified and/or has not provided Visa encryption keys.
        • X - No response.

        Note: cvvresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account.

        respstatIndicates the status of the authorization request. 

        One of the following values:
        • A - Approved
        • B - Retry
        • C - Declined
        emvTagDataA string of receipt and EMV tag data (when applicable) returned from the processor.

        Note:
        This string is returned for both EMV and non-EMV transactions on the First Data Rapid Connect (RPCT) front end platform.

        This data returned should be presented on a receipt if applicable, and recorded with the transaction details for future reference.

        See Printing Receipts Using Authorization Data in the Bolt Terminal Developer Guides for detailed information.
        tokenexpiredReturned for contactless (NFC) payments. 
        "tokenexpired":"true" indicates that an NFC payment method was used, and that the token generated is valid only for this authorization. 
        acctidThe account ID for the stored profile, created if "createProfile":"true" in the request.
        profileidThe profile ID for the stored profile, created if "createProfile":"true" in the request.
        orderidThe unique order ID for this transaction. Returns the orderid specified in the request, otherwise returns the orderid generated by the Bolt terminal, in the format <HSN-timestamp>.
        entrymode

        Only returned for merchants using the First Data North and Chase Paymentech Tampa processors.

        Possible Values:

        • Keyed
        • Moto
        • ECommerce
        • Recurring
        • Swipe(Non EMV)
        • DigitalWallet
        • EMVContact
        • Contactless
        • Fallback to Swipe
        • Fallback to Keyed
        bintypePossible Values:
        • Corp
        • FSA+Prepaid
        • GSA+Purchase
        • Prepaid
        • Prepaid+Corp
        • Prepaid+Purchase
        • Purchase
        receiptDataAn object that includes additional fields to be printed on a receipt.

        See Printing Receipts Using Authorization Data in the Bolt Terminal Developer Guides for detailed information.

        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 Terminal 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 it must meet the following requirements:

        • The order ID must be a unique value. Using duplicate order IDs can lead to the wrong transaction being voided in the event of a timeout.
        • The order ID must not include any portion of a payment account number (PAN), and no portion of the order ID should be mistaken for a PAN. If the order ID passes the Luhn check performed by the CardPointe Gateway, the value will be masked in the database, and attempts to use the order ID in an inquire, void, or refund request will fail.
        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.

        printReceiptFor Clover terminals, specifies whether or not the terminal prints a receipt.


        See Printing Receipts in the Bolt Clover Terminal Developer Guide for detailed information.

        For Ingenico terminals, specifies whether or not the response includes the receiptData array.

        See the Receipt Data Fields description in the CardPointe Gateway API for detailed information.

        Defaults to false if not provided.

        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.

        Note: This field is currently not supported for Clover terminals. If includeAVS is included in the request, it must be set to false.

        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 

        The response includes a subset of the responses available in the CardPointe Gateway Authorization Response. Currently, the authManual response includes the following fields:

        We are continuing to enhance the authManual response to include additional fields. See What's New? for the latest updates to the Bolt Terminal API.

        FieldComments
        tokenThe token generated for the payment card.
        expiryThe payment card expiration date, in MMYY format.
        signatureJSON escaped, Base64-encoded, Gzipped, BMP of signature data, if a signature was provided with the payment.
        batchidThe identifier for the batch that the transaction was added to.
        retrefThe retrieval reference number used to look up and manage the transaction.
        avsrespAlpha-numeric AVS (zip code) verification response code.

        Note:
        avsresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account.
        respprocAn abbreviation that represents the platform and the processor for the transaction.
        amountThe amount of the transaction.

        The authorized amount. For most transactions, this is the same as the request amount.
        For prepaid or gift cards, if partial authorization is enabled for the merchant account, the amount returned is the amount remaining on the card.

        For declines, the amount returned is "0.00"

        resptextA text description of the authorization response.
        authcodeThe Authorization Code from the card issuer.
        respcodeAn alpha-numeric response code that represents the description of the response
        merchidThe merchant ID, copied from the authorization request.
        cvvresp

        Alpha-numeric CVV (card verification value) verification response code.

        One of the following values:

        • M - Valid CVV Match.
        • N - Invalid CVV.
        • P - CVV Not Processed.
        • S - Merchant indicated that the CVV is not present on the card.
        • U - Card issuer is not certified and/or has not provided Visa encryption keys.
        • X - No response.

        Note: cvvresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account.

        respstatIndicates the status of the authorization request.

        One of the following values:
        • A - Approved
        • B - Retry
        • C - Declined
        acctidThe account ID for the stored profile, created if "createProfile":"true" in the request.
        profileidThe profile ID for the stored profile, created if "createProfile":"true" in the request.
        orderidThe unique order ID for this transaction. Returns the orderid specified in the request, otherwise returns the orderid generated by the Bolt terminal, in the format <HSN-timestamp>.
        entrymode

        Only returned for merchants using the First Data North and Chase Paymentech Tampa processors.

        Possible Values:

        • Keyed
        • Moto
        • ECommerce
        • Recurring
        • Swipe(Non EMV)
        • DigitalWallet
        • EMVContact
        • Contactless
        • Fallback to Swipe
        • Fallback to Keyed
        bintypePossible Values:
        • Corp
        • FSA+Prepaid
        • GSA+Purchase
        • Prepaid
        • Prepaid+Corp
        • Prepaid+Purchase
        • Purchase
        receiptDataAn object that includes additional fields to be printed on a receipt.

        See Printing Receipts Using Authorization Data in the Bolt Terminal Developer Guides for detailed information.

        tip

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

        A call to the tip endpoint prompts the user to specify a tip amount on the terminal.

        See Using the Bolt Terminal 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.
        • For Ingenico terminals, 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