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 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:
printExtraReceipt and printDelay parameters in the authCard or authManual request.includeAVS parameter in the authCard and authManual requests, to capture the cardholder's postal code. This solution requires:
For more Information on specific requirements contact isvintegrations@cardconnect.com.
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:
See Configuring Your Postman Environment in the Bolt Terminal Developer Guides for detailed information on setting up your environment variables.
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.
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.
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.
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"
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.
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.
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.
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) |
| printReceipt | √ | |
| cancel | √ | √ |
| clearDisplay | √ | √ |
| compositeReadCard (aka readCard) | √ | |
| compositeReadManual (aka readManual) | √ | |
| connect | √ | √ |
| dateTime | √ | √ |
| disconnect | √ | √ |
| display | √ | √ (with key differences) |
| listTerminals | √ | √ |
| ping | √ | √ |
| preconnect | √ | |
| readConfirmation | √ | √ |
| readInput | √ | √ |
| readSignature | √ | √ |
| readCard | √ | |
| readManual | √ | |
| tip | √ | √ |
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 | |
| 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"See Printing Receipts for detailed information. | |
| printExtraReceipt | the Defaults to false if not specified. Note: If true, the | |
| 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"See Printing Receipts for detailed information. | |
| printExtraReceipt | the Defaults to false if not specified. Note: If true, the | |
| 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. | |
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 Name | Value Type | Default Setting | Description |
|---|---|---|---|
| firstColor | hex | 46597f | 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:
|
| 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:
|
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.
This topic provides information for printing receipts, either from the Clover terminal's built-in printer, or using your own custom integration.
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.
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.
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:
|
| 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 processor | 4 | Abbreviation that represents the platform and the processor for the transaction |
| bintype | Type of BIN | 16 | Possible Values:
|
| entrymode | POS Entry Mode | 25 | Only returned for merchants using the First Data North front end platform. Possible Values:
|
| 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. |
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 |
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. |
You can print a receipt in one of two ways:
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"
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")
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.
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.
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. |
