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.
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.
What's New?
Date Updated: 1/8/2021
The Bolt Terminal API update released to the UAT environment on 1/8/2021 includes numerous enhancements to the Bolt Terminal API. See What's New? in the Bolt Terminal API for the release status and a complete list of updates.
This release includes the following updates for Bolt Clover terminals:
To help you get started with your integration, we've created 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:
This guide provides useful information specific to integrating Bolt Clover terminals. The following API references and terminal user guides provide additional helpful information:
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": "hsn: <hsn> is currently in merchant mode".
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.
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 your application sends a request to the printer while the terminal 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.
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.
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.
display
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 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.
authCard
The following parameters are not supported:
aid
Currently, 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.
includeAmountDisplay
The includeAmountDisplay parameter is not supported. The device displays the payment amount to the user regardless of this parameter's value within the authCard request.
The following parameters are specific to Clover terminals:
printReceipt
The 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"
the printExtraReceipt parameter is used to specify whether or not to print 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.
printDelay
Required when "printExtraReceipt":"true". The number of milliseconds to wait after printing the first receipt, to begin printing the second receipt.
Valid values range from 0 to 60000.
authManual
The following parameters are not supported:
aid
Currently, 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.
includeAmountDisplay
The includeAmountDisplay parameter is not supported. The device displays the payment amount to the user regardless of this parameter's value within the authManual request.
includeCVV
The includeCVV parameter must be set to false or not included in the request.
If a request includes "includeCVV" : "true" the authManual command sequence fails to complete, and an error is returned in the response data.
The following parameters are specific to Clover terminals:
printReceipt
The 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"
the printExtraReceipt parameter is used to specify whether or not to print 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.
printDelay
Required when "printExtraReceipt":"true". The number of milliseconds to wait after printing the first receipt, to begin printing the second receipt.
Valid values range from 0 to 60000.
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.
Specifies the primary color displayed in the background.
secondColor
hex
2b3855
Specifies the secondary color used throughout the application.
thirdColor
hex
37476c
Specifies the tertiary color used throughout the application.
fontColor
hex
ffffff
Specifies the system-wide font color.
ackButtonColor
hex
6ada99
Specifies 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).
ackButtonFontColor
hex
000000
Specifies the font color used on the acknowledge button.
idleimage
JPEG or PNG image file
Bolt app wallpaper
Specifies 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.
logoimage
JPEG or PNG image file
Bolt logo
Specifies 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.
merchant account information and additional transaction details returned in the receipt object
EMV tag data returned in the EMV tag object, if the card used was an EMV (chip or contactless) card.
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.
Alpha-numeric response code that represents the description of the response
resptext
Response text
-
Text description of response
respproc
Response processor
4
Abbreviation that represents the platform and the processor for the transaction
bintype
Type of BIN
16
Possible 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:
Name
Tag
Details
Source
Format
Max Length
TVR (Terminal Verification Results)
95
Status of the different functions as seen from the terminal
Terminal
binary
5
ARC (Authorization Response Code)
8A
Indicates the transaction disposition of the transaction received from the issuer for online authorizations.
Issuer/Terminal
an 2
2
PIN (CVM Results)
9F34
Indicates the results of the last CVM performed. If PIN was entered, returns "Verified by PIN"
Terminal
String
15
Signature (CVM Results)
9F34
Indicates 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.
Terminal
Boolean
5
Mode
Identifies the mode used to authorize (or decline) the transaction. Always "Issuer"
CardConnect
String
6
TSI (Transaction Status Information)
9B
Indicates the functions performed in a transaction
Terminal
b
2
Application Preferred Name
9F12
Preferred mnemonic associated with the AID. If unavailable, use Application Label.
Card
ans
1-16
AID (Application Identifier, Terminal)
9F06
Identifies the application as described in ISO/IEC 7816-5
Terminal
binary 40-128
5-16
IAD (Issuer Application Data)
9F10
Contains proprietary application data for transmission to the issuer in an online transaction.
Card
binary
0-32
Entry method
Indicator identifying how the card information was obtained.
Terminal
String
11
Application Label
50
Mnemonic associated with the AID according to ISO/IEC 7816-5. If unavailable, use the Application Preferred Name.
Card
ans with the special character limited to space
1-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:
Field
Description
receiptOrderNote
Use this field to provide a custom note to include on the receipt.
receiptItems
Use this field to provide custom item descriptors to include on the receipt.
receiptHeader
Use this field to override the header configured for your MID.
receiptFooter
Use this field to override the footer configured for your MID.
receiptDba
Use this field to override the DBA name configured for your MID.
receiptPhone
Use this field to override the phone number configured for your MID.
receiptAddress1
Use this field to override the address (line 1) configured for your MID.
receiptAddress2
Use 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:
Field
Format
Description
header
AN
A customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement.
footer
AN
A customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement.
dba
AN
The merchant's Doing Business As (DBA) name.
address1
AN
Line 1 of the merchant's address.
address2
AN
Line 2 of the merchant's address.
phone
N
The merchant's phone number.
dateTime
N
The date and time of the transaction (YYYYMMDDHHMMSS).
nameOnCard
A
The Cardholder's name, if included in the authorization request.
orderNote
AN
A custom order note, if included in the userFields in the authorization request.
items
AN
A 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.
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 your application sends a request to the printer while the terminal is in low-power mode, the response includes the following error fields:
"errorCode": 800, "errorMessage": "Printing not supported"
Printing a Receipt Using the authCard or authManual Request
To print a receipt at the time of the transaction, include the "printReceipt" : "true" parameter in your authCard or authManual request.
To print a second copy of the receipt at the time of the transaction, include "printExtraReceipt":"true" and specify a printDelay value between 0 and 60000 milliseconds (for example "printDelay":"1000")
Reprinting a Receipt Using the printReceipt Request
To reprint a receipt for a past transaction, make a request to the printReceipt endpoint, including the orderId associated with the existing transaction. Note that if more than one transaction is associated with the order ID, the most recent transaction is selected.
Printing a Receipt from a Standalone Printer
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:
Feature
Status
Component
Description
Print receipts for past transactions
Released
Bolt Terminal API
The 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 endpoints
In development
Clover Bolt App
The 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 includeAVS
Released
Clover Bolt App
The Clover Bolt app will be enhanced to support the includeAVS parameter to capture the cardholder's zip code.