Overview

The Bolt Terminal solution is now available for the Clover Mini (2nd generation) and Clover Flex terminals. These Clover terminals are next-generation payment devices that provide a sleek and secure transaction experience for your customers. By integrating the Bolt Terminal API with your POS software, you can quickly build and deploy a complete P2PE payment solution, effectively reducing your scope of PCI compliance as a merchant or integrator.

Support for Clover Flex terminals is coming soon.

This solution consists of the following components:

  • The Bolt Terminal API, which provides your software with access to the Bolt services.
  • The Bolt app for Clover devices, which is EMV pre-certified and enables you to quickly achieve EMV acceptance and PCI scope reduction.
  • The CardPointe Gateway, CardConnect's payments gateway, which provides a complete solution for transaction processing and reporting.
  • CardSecure, which tokenizes payment card information.
  • Clover terminal devices, provided by CardConnect.
  • Your POS software, integrated with the Bolt Terminal API.

Requirements

This solution requires:

  • Your merchant account, boarded to the First Data Rapid Connect processing platform.
  • Your application, integrated with the Bolt Terminal API via HTTPS.
  • A Clover terminal device, pre-provisioned and provided by CardConnect.
  • The Bolt app, running on the Clover device.

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

Additional Resources

Sample Postman Collection

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 and parameters that are supported for Bolt Clover Terminals. Click the following button to download the sample collection:

Run in Postman

See Configuring Your Postman Environment in the Bolt Terminal Developer Guides for detailed information on setting up your environment variables.

Related Documentation

The following API references and terminal user guides provide additional helpful information: 

Integrating a Clover Terminal

If your payment acceptance solution already uses the Bolt Terminal API to integrate Ingenico terminals, you can add support for Clover terminals with some minor adjustments to your integration.

Device Integration Details

Bolt Clover terminals offer a few additional features when compared to the Ingenico terminals. The following topics describe the new and different features that you should consider. 

Merchant and Customer Modes

The Bolt app for Clover terminals has two modes of operation: Merchant Mode and Customer Mode.

Customer Mode is the customer-facing interface, in which the device displays an idle screen until your application sends a command to the device. This is the default mode of operation, and the device should remain in Customer Mode.

The terminal can only receive commands when the Bolt app is connected (Bolted) and running in Customer Mode. 

With the exception of the ping request, the terminal ignores commands from your software when it is in Merchant Mode. If you send a ping request while the device is in merchant mode, a "Ping received" message is displayed on the device.

Other Bolt Terminal API requests that send commands to the device return the error
"errorMessage": "Unexpected status from terminal: CANCEL".

Merchant Mode is the merchant-facing administrative interface. In Merchant Mode, the merchant user can access the Bolt Admin Panel to configure and troubleshoot the Bolt application and device settings. Additionally, the user can exit the Bolt app to access the App Launcher and Settings menu to access the Android device settings. The merchant user can switch from Customer Mode to Merchant Mode by pressing all four corners of the touch screen simultaneously.

A noted, only the ping request should be used when the device is in Merchant Mode. 

Receipt Printing

The Clover terminal includes a built-in receipt printer. To take advantage of this feature, the authCard and authManual Bolt Terminal API service endpoints now include a printReceipt parameter. See Software Integration Details for more information on integrating this feature with your software.

When a transaction is successfully authorized by the CardPointe Gateway, the authorization response includes EMV card data (if the payment was made using an EMV or contactless payment) as well as specific merchant information. Some receipt field settings must be configured for your merchant account. Contact isvhelpdesk@cardconnect.com to configure the receipt printing properties for your merchant accounts.

See Printing Receipts later in this guide for detailed information on the data used to print a receipt from the Clover terminal, and for guidelines on integrating a custom solution for receipt printing. Additionally, you can customize the data that you include on your receipts, depending on your business needs.

The built-in receipt printer includes the following limitations:

  • Currently, you can only print receipts at the time of the transaction.

    The ability to inquire on and print receipts for past transactions is planned for a future update.

  • For Clover Mini terminals, the printer is disabled when the device is enters low-power mode.

    The Clover Mini must be connected to the hub, and the hub must be connected to a power source in order to print receipts.

    If the authCard or authManual request includes "printReceipt" : "true" but the device is in low power mode, the response includes the following error fields:

    "errorCode": 800,
    "errorMessage": "Printing not supported"

Display Specifications

The Clover Mini features a 7″ 1280×800 touch screen display, in a landscape orientation. 

The Clover Flex features a 5" 720×1280 touch screen display in a portrait orientation. 

LTE Connectivity

The Clover terminals support LTE connectivity, which enables merchants to fall back on the LTE wireless network to continue to process transactions in the event of a network interruption. Note that the device must have an active SIM card and wireless data plan, and merchants can manage these settings on the device.

When the terminal switches from the Wi-Fi/Ethernet network to the LTE network, the device loses the connection to the Bolt service, and a new session must be established by calling the Bolt Terminal API connect endpoint. When you call the connect endpoint to establish a new connection, you can optionally include the force parameter with a value of true to terminate the existing session (and any in-flight operations) before establishing the new session.

LTE connection quality and speed can vary, and may be slower than the device's primary Ethernet or Wi-Fi connection. Therefore, your software should allow for a delay in communications with the terminal.

Software Integration Details

The Bolt service itself is the same service that supports Ingenico terminals today. The Bolt Terminal API that you use to integrate your point-of-sale software with the Bolt service and terminals is largely unchanged, however there are a few key differences from the Ingenico terminal integration that you should understand.

See the Bolt Terminal API Developer Documentation for detailed information on integrating the Bolt Terminal API with your software.

Supported Endpoints

The following table illustrates which Bolt Terminal API endpoints are supported for use with Clover terminals. See Key Differences for detailed information on updating your integration.

Resource Name Ingenico Clover
authCard √ (with key differences)
authManual √ (with key differences)
cancel
clearDisplay
compositeReadCard (aka readCard)
compositeReadManual (aka readManual)
connect
dateTime
disconnect
display √ (with key differences)
listTerminals
ping
preconnect
readConfirmation
readInput
readSignature
readCard
readManual
tip

Key Differences

The following table explains the minor changes to the Bolt Terminal API, and how you should adjust your software integration to support the Clover terminals.

Bolt API Service Endpoint

Parameter

Comments

preconnect
Two-factor authentication is not currently supported for the Clover Bolt app; therefore, the preconnect service endpoint is not used to generate a token. If your application passes a value of true for this parameter, it will be ignored by the terminal.

Call the connect service endpoint to establish a Bolt session. 
displayOn 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 Ingenico terminals, sending a single-line message displays the message in the display footer, retaining the idle image; whereas, sending a multi-line string displays the text in the primary display area, replacing the idle image. 
readCard
The readCard service endpoint is not supported for the Clover Bolt app. This means that you can not use the terminal to retrieve a token for use by your POS software.

If you previously used the readCard service to capture and tokenize EMV, MSR, or NFC card data to use in a subsequent authorization request from your POS software via the CardPointe Gateway API, you can instead use the authCard endpoint to streamline those individual requests into a single call.
readManual
The readManual service endpoint is not supported by the Clover Bolt app. This means that you can not use the terminal to retrieve a token for use by your POS software. 

If you previously used the readManual service endpoint to capture and tokenize manually-entered card data to use in a subsequent authorization request from your POS software via the CardPointe Gateway API, you can instead use the authManual endpoint to streamline those individual requests into a single call.
authCardThe following parameters are not supported:
includeAVSThe includeAVS parameter must be set to false or not included in the request.

If a request includes "includeAVS" : "true"  the authCard command sequence fails to complete, and an error is returned in the response data.

aidCurrently, the Clover Bolt app processes all transactions as credit; therefore, the aid parameter used to specify the transaction type is superseded.

Support for debit transactions is planned for a future update.
The following parameters are new:
printReceiptThe printReceipt parameter is used to specify whether or not to print a receipt from the Clover terminal.

Set to true to enable receipt printing. Defaults to false if not specified.

For the Clover Mini, the built-in printer is disabled when the terminal is in low-power mode. The terminal must be connected to the hub, and the hub must be connected to a power source in order to print receipts.

If the authCard or authManual request includes "printReceipt" : "true" but the terminal is in low-power mode, the response includes the following error fields:

"errorCode": 800,
"errorMessage": "Printing not supported"

See Printing Receipts for detailed information.
authManualThe following parameters are not supported:
includeAVSThe includeAVS parameter must be set to false or not included in the request.

If a request includes "includeAVS" : "true" the authManual command sequence fails to complete, and an error is returned in the response data.
aidCurrently, the Clover Bolt app processes all transactions as credit; therefore, the aid parameter used to specify the transaction type is superseded.

Support for debit transactions is planned for a future update.
The following parameters are new:
printReceiptThe printReceipt parameter is used to specify whether or not to print a receipt from the Clover Mini.  

Set to true to enable receipt printing. Defaults to false if not specified.

Note that the built-in printer is disabled when the device is in low-power mode. The device must be connected to the hub, and the hub must be connected to a power source in order to print receipts.

If the authCard or authManual request includes "printReceipt" : "true" but the device is in low-power mode, the response includes the following error fields:

"errorCode": 800,
"errorMessage": "Printing not supported"

See Printing Receipts for detailed information.

Customizing the Clover Bolt App

The Bolt app includes color and image properties that allow you to customize some aspects of the application.

The Bolt app style properties must be configured by CardConnect. 

To configure the following properties, contact cardpointesupport@cardconnect.com for assistance.

Property NameValue TypeDefault SettingDescription
firstColorhex46597fSpecifies the primary color displayed in the background.
secondColorhex2b3855Specifies the secondary color used throughout the application.
thirdColorhex37476cSpecifies the tertiary color used throughout the application.
fontColorhexffffffSpecifies the system-wide font color.
ackButtonColorhex6ada99Specifies the color of the acknowledge button.

This button is displayed when the merchant or customer is prompted to acknowledge a message on the terminal (for example, to confirm an amount).
ackButtonFontColorhex000000Specifies the font color used on the acknowledge button.
idleimageJPEG or PNG image fileBolt app wallpaperSpecifies the image displayed when the device is idle.

The image must meet the following requirements:
  • The dimensions must be:
    • Mini - 1280x800
    • Flex - 720x1280
  • The file type must be PNG or JPEG.
  • The file size must not exceed 1MB

By default, the Bolt app wallpaper is displayed.
logoimageJPEG or PNG image fileBolt logoSpecifies the logo image that appears on the Welcome screen and other displays.

The image must meet the following requirements:
  • The dimensions must be 267x67.
  • The file type must be PNG or JPEG.
  • The file size must not exceed 1MB

By default, the Bolt logo is displayed. 

Expand the following examples to see how the style properties correspond to the Bolt app UI elements:

The examples illustrate the Bolt app running on a Clover Mini; however, the elements are the same for both devices.

Custom Color Properties

Custom Image Properties

Printing Receipts

This topic provides information for printing receipts, either from the Clover terminal's built-in printer, or using your own custom integration. 

Receipt Rules and Requirements

This topic provides general best practices and integration details for printing receipts; however, each card brand provides specific rules and requirements. You should understand and follow the receipt guidelines for the card brands that you accept.

Consult the following card brand guidelines for detailed information:

Additionally, signature and receipt requirements vary depending on the card type. For example, EMV (chip and contactless) cards do not require a signature; however receipts generated for EMV card transactions must include specific EMV tag data returned in the authorization response. Ensure that you understand the requirements for accepting both EMV and MSR (magnetic-stripe) cards as determined by the card brands.

Understanding Receipt Data

When an authorization is successfully approved and processed by the CardPointe Gateway, the authorization response payload includes important transaction details that you can capture and print on a receipt.

In general, a receipt must include:

If you are using the Bolt Terminal API's authCard or authManual endpoint to make authorization requests, the following data is returned in the authCard or authManual response.

Authorization Response Data

A successful authorization response includes the following fields. If you are integrating the Clover terminal's built-in printer, the highlighted fields are included in on the receipt. Otherwise, it is recommended that you include these fields on a receipt generated from your custom integration.

Field Content Max Length Comments
respstat Status 1 Indicates the status of the authorization request. Can be one of the following values:
  • A - Approved
  • B - Retry
  • C - Declined
retref Retrieval reference number 12 CardConnect retrieval reference number from authorization response
account Account number 19 Copied from the authorization request, masked except for the last four digits.
token (if requested) Token 19 A token that replaces the card number in capture and settlement requests if requested
amount Amount 12 Authorized amount. Same as the request amount for most approvals.
The amount remaining on the card for prepaid/gift cards if partial authorization is enabled.
Not relevant for declines.
batchid Batch ID 12 Automatically created and assigned unless otherwise specified. Returned for a successful authorization with capture.
orderid Order ID 19 Order ID copied from the authorization request.
merchid Merchant ID 12 Copied from the authorization request.
Note: If you include the merchant ID on a receipt, mask this value, except the last four digits.
respcode Response code - Alpha-numeric response code that represents the description of the response
resptext Response text - Text description of response
respproc Response processor4Abbreviation that represents the platform and the processor for the transaction
bintypeType of BIN16Possible Values:
  • Corp
  • FSA+Prepaid
  • GSA+Purchase
  • Prepaid
  • Prepaid+Corp
  • Prepaid+Purchase
  • Purchase
entrymode POS Entry Mode 25 Only returned for merchants using the First Data North front end platform.
Possible Values:
  • Keyed
  • Moto
  • ECommerce
  • Recurring
  • Swipe(Non EMV)
  • DigitalWallet
  • EMVContact
  • Contactless
  • Fallback to Swipe
  • Fallback to Keyed
avsresp AVS response code 2 Alpha-numeric AVS response.
cvvresp CVV response code 1 Alpha-numeric CVV response.
authcode Authorization code 6 Authorization Code from the Issuer
signature Signature Bitmap 6144

JSON escaped, Base64 encoded, Gzipped, BMP file representing the cardholder's signature. Returned if the authorization used a token that had associated signature data or track data with embedded signature data.

If you are integrating a custom receipt solution, you can convert this image file and print it to the receipt, if required.

commcard Commercial card flag 1 Y if a Corporate or Purchase Card
emv Cryptogram - Authorization Response Cryptogram (ARPC). This is returned only when EMV data is present within the Track Parameter.
emvTagData EMV tag data 2000 An object containing EMV data returned from the processor when an EMV card is used. This data returned should be presented on a receipt if applicable, and recorded with the transaction details for future reference.

Refer to EMV Tag Data below for a list of the possible fields returned.
receipt receipt data - An object that includes additional fields to be printed on a receipt.

Refer to Receipt Data below for a list of the fields returned.

EMV Tag Data

If the card used in the authorization request was an EMV (chip or contactless) card, then the response data includes an emvTagData object with the following fields:

NameTagDetailsSourceFormatMax Length
TVR (Terminal Verification Results)95Status of the different functions as seen from the terminalTerminalbinary5
ARC (Authorization Response Code)8AIndicates the transaction disposition of the transaction received from the issuer for online authorizations.Issuer/Terminalan 22
PIN (CVM Results)9F34Indicates the results of the last CVM performed. If PIN was entered, returns "Verified by PIN"TerminalString15
Signature (CVM Results)9F34Indicates the results of the last CVM performed. If "true" then CVM supports signature and signature line may be applicable. However, card brands have moved away from requiring signature for EMV transactions.TerminalBoolean5
Mode
Identifies the mode used to authorize (or decline) the transaction. Always "Issuer"CardConnectString6
TSI (Transaction Status Information)9BIndicates the functions performed in a transactionTerminalb2
Application Preferred Name9F12Preferred mnemonic associated with the AID. If unavailable, use Application Label.Cardans1-16
AID (Application Identifier, Terminal)9F06Identifies the application as described in ISO/IEC 7816-5Terminalbinary 40-1285-16
IAD (Issuer Application Data)9F10Contains proprietary application data for transmission to the issuer in an online transaction.Cardbinary0-32
Entry method
Indicator identifying how the card information was obtained.TerminalString11
Application Label50Mnemonic associated with the AID according to ISO/IEC 7816-5. If unavailable, use the Application Preferred Name.Cardans with the special character limited to space1-16

Receipt Data

The receipt object, included in the authorization response, provides merchant account information. The merchant account information is populated using the merchant properties configured for the MID.

Additionally, this object includes additional transaction details from the authorization response. You can optionally include a custom order note (orderNote) and item details (items), by including a userFields object in the authCard or authManual request.

You can specify the following fields in a userFields object to include an order note or item details, or to override the merchant properties:

FieldDescription
receiptOrderNoteUse this field to provide a custom note to include on the receipt.
receiptItemsUse this field to provide custom item descriptors to include on the receipt.
receiptHeaderUse this field to override the header configured for your MID.
receiptFooterUse this field to override the footer configured for your MID.
receiptDbaUse this field to override the DBA name configured for your MID.
receiptPhoneUse this field to override the phone number configured for your MID.
receiptAddress1Use this field to override the address (line 1) configured for your MID.
receiptAddress2Use this field to override the address (line 1) configured for your MID.

Each value can be any string and the total length of user defined fields (URL/JSON-encoded) is limited to 4000 bytes. See the description of userFields in the CardPointe Gateway API documentation for more information.

Contact isvhelpdesk@cardconnect.com for assistance configuring the receipt printing properties for your merchant account.

A successful authorization response includes a receipt object with the following fields:

FieldFormatDescription
headerANA customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement.
footerANA customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement.
dbaANThe merchant's Doing Business As (DBA) name.
address1ANLine 1 of the merchant's address.
address2ANLine 2 of the merchant's address.
phoneNThe merchant's phone number.
dateTimeNThe date and time of the transaction (YYYYMMDDHHMMSS).
nameOnCardAThe Cardholder's name, if included in the authorization request.
orderNoteANA custom order note, if included in the userFields in the authorization request.
itemsANA custom item descriptor, if included in the userFields in the authorization request.

Printing a Receipt

You can print a receipt in one of two ways:

  • Directly from the Clover terminal's built-in printer, using the Bolt Terminal API.
  • From your POS system's custom printer integration.

To print a receipt from the Clover terminal, include the "printReceipt" : "true" parameter in your authCard or authManual request.

For the Clover Mini, the built-in printer is disabled when the terminal is in low-power mode. The terminal must be connected to the hub, and the hub must be connected to a power source in order to print receipts.

If the authCard or authManual request includes "printReceipt" : "true" but the terminal is in low-power mode, the response includes the following error fields:

"errorCode": 800,
"errorMessage": "Printing not supported"

To print a receipt from your custom integration, use the fields described in Understanding Receipt Data to build your receipt template.

In the following example, the Clover terminal receipt template is illustrated on the left, including the fields that are populated from the authorization response data. A sample receipt is illustrated on the right.

Future Enhancements

The following enhancements are planned for future updates of Bolt and the Clover Bolt app:

FeatureComponentDescription
Print receipts for past transactionsBolt Terminal APIThe Bolt Terminal API will be enhanced to allow your integrated software to retrieve and print stored receipt data for past transactions. Currently you can view and print receipt data for past transactions in the CardPointe web application.
Tokenization using the readCard and readManual service endpointsClover Bolt AppThe Clover Bolt app will be enhanced to include support for the readCard and readManual Bolt Terminal API service endpoints, to allow your software to make separate tokenization and authorization calls.
Capture zip code using includeAVSClover Bolt AppThe Clover Bolt app will be enhanced to support the includeAVS parameter to capture the cardholder's zip code.