The CardPointe Integrated Terminal solution includes support for Clover Mini and Clover Flex terminals to provide a sleek and secure transaction experience for your customers. By integrating the 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:
Our Bolt family of integrated solutions is now CardPointe Integrated Payments.
On Thursday, October 13th, 2022, we released an update to the CardPointe Integrated Terminal Application for Clover terminals. This update includes the following changes:
Terminals will automatically download and install this update during the nightly reboot window. No merchant action is required.
For more information on using custom branding for your Clover terminals, see Customizing the Clover Terminal.
An update to the CardPointe Integrated Terminal application for Clover terminals was released on April 14th, 2022.
This release includes internal enhancements and bug fixes.
This solution requires:
For more Information on specific requirements contact isvintegrations@fiserv.com.
To help you get started with your integration, we've created a sample Postman Collection that includes a template of the Terminal API service endpoints and parameters that are supported for Clover terminals. Click the following button to download the sample collection:
See Configuring Your Postman Environment in the general CardPointe Integrated Terminal Developer Guides for detailed information on setting up your environment variables.
This guide provides useful information specific to integrating Clover terminals. The following API references and terminal user guides provide additional helpful information:
If your payment acceptance solution already uses the Terminal API to integrate Ingenico terminals, you can add support for Clover terminals with some minor adjustments to your integration.
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.
When your merchants unbox a new Clover terminal device, they must enter an activation code during the initial setup process. This activation code is provided in a welcome email; however you may want to retrieve and display the activation code within your application, to improve the setup process for your merchants.
The Terminal API includes a terminalActivationCode endpoint, which you can use to supply the merchant ID and hardware serial number (HSN) associated with a specific terminal to retrieve the activation code for that terminal.
The following example illustrates the terminalActivationCode request and response:
The CardPointe Integrated Terminal 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 terminal is connected 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 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 Admin Panel to configure and troubleshoot the application and device settings. Additionally, the user can exit the 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 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.
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 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 terminal service, and a new session must be established by calling the 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 following topics describe some specific details for integrating Clover terminals and key differences from the Terminal API integration for Ingenico terminals.
See the Terminal API Documentation for detailed information on integrating the Terminal API with your software.
The following table illustrates which 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 | √ | √ |
| connect | √ | √ |
| dateTime | √ | √ |
| disconnect | √ | √ |
| display | √ | √ (with key differences) |
| listTerminals | √ | √ |
| ping | √ | √ |
| readConfirmation | √ | √ |
| readInput | √ | √ |
| readSignature | √ | √ |
| readCard | √ | √ (with key differences) |
| readManual | √ | |
| tip | √ | √ |
| terminalDetails | √ | √ |
The following table explains the minor changes to the Terminal API, and how you should adjust your software integration to support the Clover terminals.
Terminal API Service Endpoint | Parameter | Comments |
|---|---|---|
| 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. | |
| readManual | The readManual service endpoint is not supported for Clover terminals. 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 terminal 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 terminal 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. | |
| includeAVS | The 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. | |
| 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. | |
| readCard | The following parameters are not supported: | |
| aid | Currently, the Clover terminal 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 Clover terminal app supports custom color and image settings to match your business' branding.
| 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 | CardPointe app wallpaper | Specifies the image displayed when the device is idle. The image must meet the following requirements:
|
| logoimage | JPEG or PNG image file | CardPointe 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 app UI elements:
The examples illustrate the Clover Mini display; 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 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 | CardPointe 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 | String | 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" | CardPointe Gateway | String | 6 | |
| TSI (Transaction Status Information) | 9B | Indicates the functions performed in a transaction | Terminal | Binary | 2 |
| Application Preferred Name | 9F12 | Preferred mnemonic associated with the AID. If unavailable, use Application Label. | Card | String | 16 |
| AID (Application Identifier, Terminal) | 9F06 | Identifies the application as described in ISO/IEC 7816-5 | Terminal | Binary | 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 | 26 | |
| Application Label | 50 | Mnemonic associated with the AID according to ISO/IEC 7816-5. If unavailable, use the Application Preferred Name. | Card | String (with the special character limited to space) | 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.
You can specify the following fields in a userFields object to override the merchant properties:
| Field | Description |
|---|---|
| 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 userFields description in the CardPointe Gateway API documentation for more information.
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. |
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.
