The Bolt Terminal Solution now includes support for the Clover Mini 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 for your merchant account. The Bolt Terminal solution supports select Clover and Ingenico terminal devices.
  • The CardPointe 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. Some features are specific to either Bolt Ingenico or Bolt Clover terminals, as noted throughout the API. 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 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.

Date Updated: 2/27/2021

The following updates were deployed to the UAT on 1/8/2021 and to the Production environment on 2/27/2021.

New terminalDetails Endpoint

The Bolt Terminal API includes a new terminalDetails endpoint, which allows you to identify the model and supported features for each terminal associated with your merchant ID. This can be useful for merchants with multiple terminals, to determine which supports signature capture or receipt printing, or for merchants with multiple locations, who need to determine which terminals are associated with each merchant ID. See the terminalDetails endpoint description for more information.

Receipt Printing Enhancements for Bolt Clover Terminals

The Bolt Terminal API now includes a printReceipt endpoint, which allows you to reprint receipts after the authorization, using the orderId associated with the transaction. Previously, receipts could only be printed at the time of the authorization. See the printReceipt endpoint description for more information.

Additionally, the authCard and authManual endpoints now support printing a second receipt during the transaction, using the following new parameters:

Note: This feature is now available in the Bolt Terminal API; however it is not yet supported by the Clover Bolt App. See the Bolt Clover Terminal Developer Guide for additional updates. 

  • printExtraReceipt - If true, the terminal prints a second receipt.
  • printDelay - Specifies the amount of time (in milliseconds) to wait before printing the second receipt.

authCard and authManual Endpoint Enhancements

In addition to the printExtraReceipt and printDelay parameters, the authCard and authManual endpoints have been updated with the following enhancements:

  • orderId and receiptData response fields are now returned by default. 

    Previously, these response fields were only returned if "printReceipt":"true". was specified in the request. For Ingenico terminals, the printReceipt request field is no longer used. For Clover terminals, printReceipt is still used to select whether or not to print a receipt at the end of the transaction.

  • authCode request parameter added.

    authCard and authManual requests now support the optional authCode parameter, to support voice authorizations. 

  • bin request parameter added.

    authCard and authManual requests now support the optional bin parameter to return the binInfo object in the response. The binInfo data includes additional information about the payment card used in the authorization. See the CardPointe Gateway API's BIN endpoint description for more information.

  • invoiceId request parameter added.

    authCard and authManual requests now support the optional invoiceId parameter for ClientLine reporting.

  • termId request parameter added.

    authCard and authManual requests now support the optional termId parameter for ClientLine reporting.

Updated Postman Collections

The Bolt Terminal API Postman Collection and the Bolt Clover Terminal Postman Collection have been updated to include these new features. 

Date Updated: 6/2/2020

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.

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 CardPointe 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 this API does not guarantee the order of key/value pairs in response messages. 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. 
  • Pre-provisioned Bolt Terminal devices.

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

For more information on specific requirements, contact integrationdelivery@fiserv.com.

Additional Resources

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

Developer Guides

Browse the 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, we created a Bolt Terminal API 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
terminalDetailsterminalDetailsv3false
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
readManual readManual v2 true
authCard authCard v3 true
authManual authManual v3 true
tiptipv3true
printReceiptprintReceiptv3true

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 to prompt a user to select the terminal HSN to pair or use with the POS 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 Bolt Terminal API Authorization Key

Request Parameters

Fields in bold are required.

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

terminalDetails

A call to the terminalDetails endpoint returns an array of terminals associated with the merchant ID specified in the request. The response includes one or more objects containing the hardware serial number (HSN), model, status, and features supported for each device. 

This can be useful for merchants with multiple terminal models, to determine which supports signature capture or receipt printing, or for merchants with multiple locations, who need to determine which terminals are associated with each merchant ID. 

Endpoint URL

The URL for the terminalDetails endpoint is:

https://<site>.cardpointe.com/api/v3/terminalDetails

Request Header

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

KeyValue
Content-Typeapplication/json
AuthorizationThe Bolt Terminal API Authorization Key

Request Parameters

Fields in bold are required.

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

Response Parameters

Field Description
terminalDetails An array of objects, containing the details for each terminal associated with the merchant ID. 

Each object includes the following fields:
  • hsn - The hardware serial number (HSN) of the terminal
  • name - The name associated with the terminal. Currently unused.
  • merchantId - The merchant ID associated with the terminal.
  • connected - Indicates whether the terminal is currently connected to the Bolt service.
  • deviceType - The terminal model, for example iSMP4 or Flex.
  • environment - The environment that the terminal is registered in. Either UAT or PROD.
  • deviceCapabilities - An object that includes the following fields:
    • screenDimensionX - The horizontal measurement of the display, in pixels.
    • screenDimensionY - The vertical measurement of the display, in pixels.
    • pinPad - Whether or not the device includes a physical or on-screen pin pad. Either true or false.
    • msr - Whether or not the device can accept magnetic stripe (swipe) card payments. Either true or false.
    • emv - Whether or not the device can accept magnetic stripe (swipe) card payments. Either true or false.
    • nfc - Whether or not the device can accept magnetic stripe (swipe) card payments. Either true or false.
    • signature - Whether or not the device can capture a cardholder's signature. Either true or false.
    • printer - Whether or not the device has a built-in receipt printer. Either true or false.

dateTime

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

You should include the dateTime request into your terminal connection workflow to ensure that the terminal's time is accurate for transaction reporting and receipts, and to ensure that the terminal's nightly PCI reboot occurs outside of your business hours, as intended.

Endpoint URL

The URL for the dateTime endpoint is:

https://<site>.cardpointe.com/api/v2/dateTime

Request Header

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

KeyValue
Content-Typeapplication/json
AuthorizationThe Bolt Terminal API 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
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: 2021-02-03T11:30:45  or 2021-02-03T18:30
hsnTerminal hardware serial number.
merchantIdYour merchant ID, required for all requests.

getPanPadVersion

This endpoint is specific to Ingenico Bolt Terminals.

A call to the getPanPadVersion endpoint returns the version of the PanPad/Bolt terminal application running on the specified Ingenico Bolt 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 Bolt Terminal API Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

Request Parameters

Fields in bold are required.

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

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 Bolt Terminal API 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
hsnTerminal hardware serial number.
merchantId Your merchant ID, required for all requests.

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 Bolt Terminal API 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
hsnTerminal hardware serial number.
merchantId Your merchant ID, required for all requests.

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 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 Bolt Terminal API Authorization Key

Request Parameters

Fields in bold are required.

Field Description
hsnTerminal hardware serial number.
merchantId Your merchant ID, required for all requests.
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 Bolt Terminal API Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

Request Parameters

Fields in bold are required.

Field Description
merchantId Your 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 Bolt Terminal API Authorization Key
X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

Request Parameters

Fields in bold are required.

Field Description
merchantId Your 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 Bolt Terminal API Authorization Key
    X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

    Request Parameters

    Fields in bold are required.

    Field Description
    merchantId Your 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. 

    Ensure that you allow at least a 1 second delay after sending the readConfirmation command, before sending a subsequent command (for example, authCard), to prevent "terminal in use" errors.

    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 Bolt Terminal API Authorization Key
    X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

    Request Parameters

    Fields in bold are required.

    Field Description
    merchantId Your 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 Bolt Terminal API Authorization Key
    X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

    Request Parameters

    Fields in bold are required.

    Field Description
    merchantId Your 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 Bolt Terminal API Authorization Key
    X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

    Request Parameters

    Fields in bold are required.

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

      If you use the cancel command to allow a merchant or cardholder to attempt to cancel a transaction in progress, you should also use the CardPointe Gateway API's InquireByOrderid request to verify the status of the transaction. A transaction cannot be canceled if Bolt has already initiated the authorization request to the CardPointe Gateway; however, you can use the InquireByOrderid request to check the status of the transaction and void if necessary.

      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 Bolt Terminal API Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

      Request Parameters

      Fields in bold are required.

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

      readCard

      A call to the readCard 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 Bolt Terminal API Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.
      • readCard (v2) requires a session key.
      • readCard (v2) is an alias for compositeReadCard (v1).
      • compositeReadCard (v1) does not require a session key.

      Request Parameters

      Fields in bold are required.

      Field Description
      merchantIdYour 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 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 Bolt Terminal API Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.
      • readManual (v2) requires a session key.
      • readManual (v2) is an alias for compositeReadManual (v1).
      • compositeReadManual (v1) does not require a session key.

      Request Parameters

      Field Description
      merchantIdYour 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 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 Bolt Terminal API Authorization Key
      X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

      Request Parameters

      Fields in bold are required.

      Field Description
      merchantId

      The merchant ID (MID) associated with your Bolt terminals in the 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, enter "1000" to specify "$10.00").

      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.
      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, and for Bolt Ingenico terminals. 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.
      authCodeAn authorization code returned by the issuer, when voice authorization is required to complete a transaction.
      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 customer account.

      This setting must be enabled for your merchant account.

      Contact integrationdelivery@fiserv.com for additional information.

      bin

      Determines if the binInfo object is included in the authorization response. The binInfo data includes additional information about the payment card used in the authorization. See the CardPointe Gateway API's BIN endpoint description for more information.

      Defaults to false 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.

      capture

      Determines whether or not to capture the amount for settlement within the authorization request.

      If set to false, the retref or 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.

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

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

      If not provided, the default delay configured in Bolt will be used.
      confirmAmountDetermines if the terminal prompts the user to confirm the transaction amount prior to prompting to insert/swipe/tap the card.

      Defaults to true if not provided.
      createProfile

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

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

      gzipSignature

      Determines if the captured signature is compressed using Gzip.

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

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

      Defaults to true if not provided.

      includeAmountDisplay Determines if the transaction amount is displayed to the user during a card-present transaction. 

      Defaults to true if not provided.


      Note: This parameter is not supported for Bolt Clover terminals. The Clover terminal displays the amount to the user regardless of this parameter.

      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.

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

      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, and for Bolt Ingenico terminals. 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.

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

      Defaults to true if not provided. 
      invoiceIdA unique invoice ID, used for ClientLine reporting. This value is an alphanumeric string with a maximum of 12 characters.
      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 Terminal 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.
      printDelayFor Clover terminals, specifies the amount of time (in milliseconds) to wait before printing generating and printing a second receipt, when "printExtraReceipt":"true". On average, this process takes approximately 5 seconds (5000 ms), therefore the total amount of time to print a second receipt is equal to the printDelay value + 5000ms.


      Valid values range from 0 to 60000 (ms).

      Notes:

      • printDelay is required when "printExtraReceipt":"true"; otherwise, the response returns the following error:

        {"errorCode":1,"errorMessage":"printDelay is a required parameter when printExtraReceipt=true"}

      • If printDelay is set to a value outside of the allowed range, the response returns the following error:

        {"errorCode":3,"errorMessage":"'printDelay' value must be between 0 and 60,000"}
      printExtraReceipt

      For Clover terminals, if true, the terminal prints a second copy of the receipt once the authorization is complete and the initial receipt is printed. 

      Notes:

      • Only applicable if printReceipt is true.
      • If true, the printDelay parameter is also required.

      Defaults to false if not provided.

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

      Defaults to false 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.

      signatureFormat

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

      • bmp (this is the default if the value is omitted)
      • jpg
      • png
        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.
        termId

        The Terminal Device ID, if required for ClientLine reporting. 

        If specified, termId must be exactly 8 characters.

        userFields

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

        The value of the userFields object is a series of name-value pairs that are meaningful to the merchant. 

        The userFields object is limited to 4000 bytes total.

        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:

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

        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, if returned by the processor.

        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, First Data Rapid Connect, 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.
        binInfo

        An object that includes the fields returned in the BIN response, if "bin":"true" in the request.

        authManual

        A call to the authManual endpoint requests manually-entered card data and initiates 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 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 Bolt Terminal API Authorization Key
        X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

        Request Parameters

        Fields in bold are required.

        Field Description
        merchantId

        The merchant ID (MID) that is associated with your Bolt Terminals in the 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, enter "1000" to specify "$10.00").

        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.
        authCodeAn authorization code returned by the issuer, when voice authorization is required to complete a transaction.
        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 customer account.

        This setting must be enabled for your merchant account.

        Contact integrationdelivery@fiserv.com for additional information.

        bin

        Determines if the binInfo object is included in the authorization response. The binInfo data includes additional information about the payment card used in the authorization. See the CardPointe Gateway API's BIN endpoint description for more information.

        Defaults to false 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.

        capture

        Determines whether or not to capture the amount for settlement within the authorization request.

        If set to false, the retref or 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.

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

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

        If not provided, the default delay configured in Bolt will be used.
        createProfile

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

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

        gzipSignature

        Determines if the captured signature is compressed using Gzip.

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

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

        Defaults to true if not provided.

        includeAmountDisplay Determines if the transaction amount is displayed to the user during a card-present transaction. 

        Defaults to true if not provided.

        Note: This parameter is not supported for Bolt Clover terminals. The Clover terminal displays the amount to the user regardless of this parameter.
        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.

        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, and for Bolt Ingenico terminals. 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.

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

        Defaults to true if not provided. 
        invoiceIdA unique invoice ID, used for ClientLine reporting. This value is an alphanumeric string with a maximum of 12 characters.
        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 Terminal 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.
        printDelayFor Clover terminals, specifies the amount of time (in milliseconds) to wait before printing generating and printing a second receipt, when "printExtraReceipt":"true". On average, this process takes approximately 5 seconds (5000 ms), therefore the total amount of time to print a second receipt is equal to the printDelay value + 5000ms.


        Valid values range from 0 to 60000 (ms).

        Notes:

        • printDelay is required when "printExtraReceipt":"true"; otherwise, the response returns the following error:

          {"errorCode":1,"errorMessage":"printDelay is a required parameter when printExtraReceipt=true"}

        • If printDelay is set to a value outside of the allowed range, the response returns the following error:

          {"errorCode":3,"errorMessage":"'printDelay' value must be between 0 and 60,000"}
        printExtraReceipt

        For Clover terminals, if true, the terminal prints a second copy of the receipt once the authorization is complete and the initial receipt is printed. 

        Notes: 

        • Only applicable if printReceipt is true.
        • If true, the printDelay parameter is also required.

        Defaults to false if not provided.

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

        Defaults to false 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.

        signatureFormat

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

        • bmp (this is the default if the value is omitted)
        • jpg
        • png
          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.
          termId

          The Terminal Device ID, if required for ClientLine reporting. 

          If specified, termId must be exactly 8 characters.

          userFields

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

          The value of the userFields object is a series of name-value pairs that are meaningful to the merchant.

          The userFields object is limited to 4000 bytes total.

          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:

          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 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, First Data Rapid Connect, 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.
          binInfoAn object that includes the fields returned in the BIN response, if "bin":"true" in the request.

          tip

          For Ingenico Bolt Terminals, 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 Bolt Terminal API Authorization Key
          X-CardConnect-SessionKeyThe session key returned by the connect endpoint.

          Request Parameters

          Fields in bold are required

          FieldDescription
          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.
          hsnThe terminal hardware serial number (HSN).
          merchantIdYour merchant ID, required for all requests.
          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.
          includeAmountDisplay 

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

          Defaults to true if not provided.

          includeCustomTipAmount

          Determines if a custom tip button is displayed on the terminal. If false, tipPercentPresets is required to provide a range of preset tip percentage values.

          Defaults to true if not provided.

          tipPercentPresets

          An array of three preset tip percentages, in the format [n, n, n] (for example, [10, 15, 20]). 

          Required if "includeCustomTipAmount:"false".

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

          printReceipt

          The printReceipt endpoint is only supported for Clover Bolt terminals. See the Bolt Clover Terminal Developer Guide for more information on printing receipts.

          A call to the printReceipt endpoint prints one or two receipts for a past transaction, specified by the orderId.

          Endpoint URL

          The URL for the printReceipt endpoint is:

          https://<site>.cardpointe.com/api/v3/printReceipt

          Request Header

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

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

          Request Parameters

          Fields in bold are required.

          FieldDescription
          hsnThe terminal hardware serial number (HSN).
          merchantIdMerchant ID, required in all requests.
          orderIdThe order ID for the transaction for which to print a receipt.

          Note: If multiple transactions are found for the order ID, then the latest transaction with that order ID will be sent to the terminal for printing.
          printDelayRequired when "printExtraReceipt":"true". The number of milliseconds to wait after printing the first receipt, before generating and printing the second receipt. On average, this process takes approximately 5 seconds (5000 ms); therefore, the total amount of time to print a second receipt is equal to the printDelay value + 5000ms.

          Valid values range from 0 to 60000.
          printExtraReceiptOptional. If true the terminal prints a second copy of the receipt. Use the printDelay parameter to specify the amount of time (in milliseconds) to wait between printing each receipt.

          Defaults to false if not specified.

          Note: If true, the printDelay parameter is also required in the request, to specify the delay (in milliseconds) between printing the first and second receipts.

          If the printer is already printing a receipt when the terminal receives the printReceipt command, the following error is returned:

          {"errorCode":7,"errorMessage":"hsn: <hsn> is currently printing"}

          Additionally, for the Clover Mini, the terminal must be connected to a power supply to print a receipt. If the terminal is operating on the backup battery when it receives the printReceipt command, the following error is returned:

          {
              "errorCode": 800,
              "errorMessage": "Printing not supported",
              "receiptData": {<receiptData>}
          }

          Response Parameters

          FieldDescription
          receiptDataThe receipt data details configured for the merchant account. See the Receipt Data description in the Bolt Clover Terminal Developer Guide for more information.

          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
          printReceiptprintDelay value must be between 0 and 60000 (miliseconds)
          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
          800Printing not supportedBolt authCard or authManual request including  "printReceipt:"true", or printReceipt request, when the Clover Mini is running in low-power mode (not connected to AC power).

          Note: This error response also includes the receiptData array for the associated transaction.