Bolt Terminal API

The following entries describe changes to the Bolt Terminal API and documentation.

Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.

Date Updated: 2/27/2021

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

Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.

New terminalDetails Endpoint

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

Receipt Printing Enhancements for Bolt Clover Terminals

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

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

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

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

authCard and authManual Endpoint Enhancements

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

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

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

  • authCode request parameter added.

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

  • bin request parameter added.

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

  • invoiceId request parameter added.

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

  • termId request parameter added.

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

Updated Postman Collections

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

Date Updated: 6/2/2020

PIN Debit Support

The Bolt Terminal solution now supports PIN debit payments for merchants processing on the Rapid Connect platform. 

To update your integration to support PIN debit transactions, you must include the aid and includePIN parameters in your authCard or readCard requests. 

See Accepting PIN Debit Cards in the Bolt Terminal Developer Guides for detailed information on updating your integration to include PIN debit payment workflows.

Before you begin to update your application, note the following important restrictions:

  • New or existing merchants who want to accept PIN debit payments must be boarded to the First Data Rapid Connect platform. Merchants currently accepting PIN debit payments on the First Data North platform will continue to be supported.
  • PIN debit is currently only supported on Bolt Ingenico terminals.
  • Terminals must be provisioned with the necessary encryption keys for handling PIN data.

Date Updated: 3/28/2020

The following updates were deployed to the UAT environment on 11/15/2019 and the production environment on 3/28/2020. 

Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications. 

New authCard and authManual Response Fields

The authCard and authManual responses now include the following fields:

RequestFieldTypeDescription
authCard/authManualreceiptDataArrayIf "printReceipt":"true" is included in the request, the response includes the receiptData array. This array includes additional transaction information to be printed on a receipt.

See the Receipt Data Fields description in the CardPointe Gateway API for a list of the possible fields returned.
authCard/authManualorderidStringThe order ID included in the authCard or authManual request, or the automatically-generated order ID if no value was included in the request.
authCard/authManualentrymodeStringNote: Currently, entrymode is only returned for merchants processing on the First Data North (FNOR) platform.

The point-of-sale (POS) payment entry mode.

Possible values are:
  • Keyed
  • Moto
  • ECommerce
  • Recurring
  • Swipe(Non EMV)
  • DigitalWallet
  • EMVContact
  • Contactless
  • Fallback to Swipe
  • Fallback to Keyed
authCard/authManualbintypeStringNote: Currently, bintype is only returned for merchants processing on the First Data North (FNOR) platform.

The type of card used, determined by the BIN. 

Possible values are:
  • Corp
  • FSA+Prepaid
  • GSA+Purchase
  • Prepaid
  • Prepaid+Corp
  • Prepaid+Purchase
  • Purchase

Terminal in Merchant Mode Error Response

For Bolt Clover terminals, the following error message is now returned to the calling application when the device is in Merchant Mode:

"errorMessage": "hsn: <hsn> is currently in merchant mode"

See the Bolt Clover Terminal Developer Guide for more information.

Date Updated: 7/24/2019

This release includes the following updates:

Updated Signature Capture Logic

The authCard and authManual endpoints no longer prompt for signature when an authorization is declined. 

Previously, if the authCard or authManual request included "includeSignature" : "true", the cardholder would be prompted for their signature even if the authorization was declined.

Updated Error Messages

"errorCode" : 1 and "errorCode" : 8

The response body returned for errorCode 1 and errorCode 8 now include the authorization response data returned from the CardPointe Gateway, in the event that an authorization attempt was successfully initiated before the command sequence was canceled or timed out. 

For example:

HTTP/1.1 500
Content-Type: application/json
 
{
  "errorCode": 1,
  "errorMessage": "Terminal request timed out",
  "authResponse": {
       "token" : "9445123546981111",
       "expiry" : "0224",
       "name" : "John Doe",
       "batchid" : "100",
       "retref" : "173006146691",
       "avsresp" : "Y",
       "respproc" : "RPCT",
       "amount" : "1.00",
       "resptext" : "Approval",
       "authcode" : "909443",
       "respcode" : "00",
       "merchid" : "1234",
       "cvvresp" : "",
       "respstat": "A",
       "orderId": "C032UQ82820315-20180422141315"    
    }  
}

This allows you to determine if the authorization was successfully completed before the authCard or authManual command sequence timed out or was canceled.

See 500: Bolt Client or Server Error for more information.

{"errorCode": 400, "errorMessage: "PIN Debit not supported for merchantId <MID>"}

The "PIN Debit not supported for merchantId" message now includes the MID used in the authorization attempt.

Date Updated: 5/3/2019

This release includes the following updates:

Improved Timeout Handling Logic

Bolt has been updated with improved logic for handling timed out transactions. When Bolt does not receive an authorization response from the CardPointe Gateway, Bolt uses the CardPointe Gateway API inquireByOrderid endpoint to check on the status of the authorization attempt. If no status is returned, Bolt sends three voidByOrderID requests to void the transaction. If enough time remains in Bolt's request sequence, Bolt retries the authorization. Otherwise, Bolt returns an authorization failed error, and the request must be resent. See Handling Timeouts in the Bolt Developer Guides for more information.

authCard and authManual Improvements

The authCard and authManual endpoints include the following enhancements:

  • Support for refunds - You can now specify a negative amount value to initiate a negative authorization (forced credit). Note that the merchant account must be enabled to process forced credit transactions.
  • Ability to create profiles - You can now use the data in the request to create a payment profile. If you set the createProfile parameter to true, Bolt initiates a request to the CardPoint Gateway profile endpoint to create a secure stored payment profile. See the CardPointe Gateway API Profile endpoint description for detailed information.
  • Default orderid values - To support the improved timeout handling logic, Bolt now automatically generates a unique order ID in the format <HSN-timestamp> if the orderId parameter is not included in the request.

Date Updated: 11/29/2018

This release includes the following updates:

New tip Endpoint

The new tip endpoint allows you to prompt a user for a tip. You can specify up to four preset tip percentage amounts, including a custom amount option that allows the user to enter a custom tip amount.

Developer Documentation Improvements

The Bolt P2PE API Developer Documentation has been updated with numerous improvements, including:

  • An updated Postman Collection and additional information for getting started.
  • More detailed and consistent service endpoint descriptions and API documentation.
  • Revised content and improved layout, throughout.

Date Updated: 8/23/2018

This release includes the following updates:

Enhanced Authorization Capabilities

Enhanced Terminal Integration