The following guides provide best practices and other supplemental information for integrating the Bolt P2PE API.

Understanding the Bolt API Application Workflow

The Bolt P2PE API allows developers the flexibility to accommodate a wide variety of business needs and specific use cases. Regardless of the intricacies of each implementation, a Bolt integration generally involves the following workflow:

  1. Connecting a Terminal to Bolt
  2. Connecting your Client to the Bolt Server
  3. Establishing a Session
  4. Getting a Token and Running a Payment

See the API Connectivity Guide for general information on connecting to Bolt and other CardConnect services.

Connecting a Terminal to Bolt

Once a Bolt terminal is provisioned and delivered to a client, it must be connected to the client's network using either an Ethernet or Wi-Fi connection.

If your site's network configuration includes firewall rules to restrict traffic, you should allow outbound traffic to the following IP address ranges to ensure that your terminals and software can communicate with Bolt's servers:

  • 198.62.138.0/24
  • 206.201.63.0/24

See Network Whitelisting for more detailed information.

The terminal displays either Bolted or Unbolted depending on whether it has established an internet connection and made contact with the Bolt P2PE servers.

Once the terminal has established a Bolted status, it can receive requests from your application.

Connecting your Client to the Bolt Server

The Bolt REST Web Service base URL includes a protocol, host, port and servlet specification. For example:

https://<subdomain>.cardpointe.com:<port>/api/v2

An API key is required as the HTTP authorization header in each POST request. The API key is provided by a CardConnect Integrated Solutions specialist and can be used for one merchant ID (MID) or a group of MIDs.

The following example shows an API key supplied as a basic authorization header:

Authorization: QWxhZGluOnNlc2FtIG9wZW4sjajlkHJApa=

If the API key is missing or incorrect in the request, an HTTP Exception "401:Unauthorized" is returned to the calling application.

It is strongly recommended that you maintain your API key on an application server, rather than in the client application, to ensure that the key value is secure. This requires that all requests and responses are managed by the server, not the client.

Establishing a Session

In addition to connecting to the Bolt server, the terminal also connects to your point-of-sale system. This connection is referred to as a session. You establish a session between your POS system and the terminal by calling the connect endpoint.

A successful call to the connect endpoint returns a custom HTTP header, called X-CardConnect-SessionKey. The returned value includes the session key value and an expiration date and time.

For example:

X-CardConnect-SessionKey →<key value>;expires=<date:time>.

This session key must be included in the header of each Bolt API requests. Requests without a session key return the following error:

"errorCode": 1, "errorMessage": "SessionKey header is required"

A session key is valid for 10 minutes after it is generated. Requests including an expired session key return the following error:

"errorCode": 1, "errorMessage": "Session key for hsn <terminal HSN> was not valid"

See managing terminal sessions for more information.

Getting a Token and Running a Payment

The Bolt API provides the following methods for either tokenizing payment card data or getting a token and running a payment:

Regardless of which method you implement, tokenization is handled by CardSecure, and the payment authorization is handled by the CardPointe Gateway.

  • If you use the Bolt API readCard or readManual endpoint to get a token, you must then pass that token in an authorization request from your client application, using the CardPointe Gateway API.
  • If you use the Bolt API authCard or authManual endpoint to get a token, Bolt passes the token in an authorization request to the CardPointe Gateway.

In addition to handling payment requests, the CardPointe Gateway also provides methods for voiding and refunding transactions, and for gathering reporting data. Integrate your application using the CardPointe Gateway API to take full advantage of these and other features offered by the CardPointe Gateway. For more information, see the CardPointe Gateway API documentation.

Running the API in Postman

To help you get started with your integration, CardConnect provides a sample Postman Collection that includes a template of the Bolt API service endpoints.

Run in Postman

Configuring Your Postman Environment

The Bolt API service templates in this collection use Environment variables to simplify your integration. Environment variables allow you to autofill select fields with pre-configured values. For example, instead of manually specifying your merchant ID in the body of each request, you can set the {{merchantid}} variable to your specific MID.

Once you have received a Bolt terminal and API key from CardConnect, you can configure the following variables to auto-fill your merchant-specific data in requests to the Bolt API:

  • url - Set this value to the root URL that you received from CardConnect. The {{url}} variable is used to set the base url (host and port) for the Bolt REST web services.
  • Authorization - Set this value to the API key that you received from CardConnect. The {{Authorization}} variable is used in the header of every request.
  • merchantId - Set this value to your CardConnect MID. The {{merchantid}} variable is used in the body of most requests.
  • hsn - Set this value to the hardware serial number (HSN) for your terminal. The {{HSN}} variable is used in the body of most requests.
  • X-CardConnect-SessionKey - Set this value to a valid session key. Session keys are returned by successful requests to the connect endpoint. The {{X-CardConnect-SessionKey}} variable is required in the header of some requests. 

To configure environment variables, do the following in Postman:

  1. Click the gear icon to open the Manage Environments menu.


  2. On the Manage Environments menu, enter your merchant-specific values for each variable.

  3. Click Update.

See the Postman user documentation for detailed information on configuring your environment and using variables.

Understanding the Bolt API Service Endpoints

Your client application makes requests to Bolt's service endpoints to send commands to the connected terminal.

The Bolt API service endpoints can be categorized in three groups:

The following topics describe the use of these endpoints, and provide tips for using them in your integration.

Using the Bolt API Connectivity Endpoints

You use the following endpoints to connect, disconnect, and pair terminals with your point-of-sale system:

See the Bolt P2PE API for a complete description of each request and response

API Service EndpointDescription
listTerminalsYou can use the listTerminals endpoint to retrieve information about the terminals associated with a merchant ID.

The listTerminals response returns the list of terminals to the client application, which can be used for pairing terminals with the integrated POS system.
preconnectYou can use the preconnect endpoint to retrieve a two-factor authentication token, if two-factor authentication is configured for your merchant ID.

Note that you should only integrate the preconnect endpoint when two-factor authentication is enabled for the merchant account. When two-factor authentication is enabled, it is required. in this case, your application must always call the preconnect endpoint before establishing a connection. Your application must retrieve the authentication token from the preconnect response and include it in the subsequent request to the connect endpoint. 
connectYou can use the connect endpoint to establish a session between the terminal and your point-of-sale application.

See Establishing a Session for more information and recommendations for using the connect endpoint.

Additionally, see Sharing a Bolt Terminal Between POS Systems if you want to share a Bolt terminal amongst multiple point-of-sale systems or Merchant IDs.
pingYou can use the ping endpoint to verify that the terminal has an open session.

Note that the v1 ping endpoint does not require a session key, whereas the v2 endpoint does. The v2 ping is useful for verifying that the terminal is connected and has a valid session, whereas the v1 ping is useful for only verifying the terminal's connection.
disconnectYou can use the disconnect endpoint to terminate the current session.

Using the Bolt API Payment and Tokenization Endpoints

You use the following endpoints to tokenize payment card data and run authorizations:

See the Bolt P2PE API for a complete description of each request and response

EndpointEnvironmentDescription
readCard

Card Present

This endpoint is used to get a token.

The readCard endpoint requests card input (MSR, EMV, or NFC) and retrieves the encrypted data from the terminal. Encrypted data is sent to CardSecure for tokenization, and the token is returned to the client application to be passed in a subsequent authorization request to the CardPointe Gateway API.
authCardCard PresentThis endpoint is used to get a token and run a payment.

The authCard endpoint requests card input (MSR, EMV, or NFC), and retrieves the encrypted data from the terminal. Encrypted data is sent to CardSecure for tokenization, and the token is returned to Bolt, which initiates an authorization request to the CardPointe Gateway.
readManualCard Not  PresentThis endpoint is used to get a token.

The readManual endpoint requests manually-entered card input and retrieves the encrypted data from the terminal. Encrypted data is sent to CardSecure for tokenization, and the token is returned to the client application to be passed in a subsequent authorization request to the CardPointe Gateway API.
authManualCard Not PresentThis endpoint is used to get a token and run a payment.

The authManual endpoint requests manually-entered card input, and retrieves the encrypted data from the terminal. Encrypted data is sent to CardSecure for tokenization, and the token is returned to Bolt, which initiates an authorization request to the CardPointe Gateway.
tipCard PresentThis endpoint is used to prompt the user to select a tip amount prior to the authorization. 

The tip endpoint requests a tip amount, and retrieves the user's selection from the terminal. The tip request parameters allow you to configure up to three preset percentages and one custom amount, which allows the user to specify a dollar amount. 

Generally your software should call the tip endpoint to retrieve the tip amount to add to the transaction amount before submitting the authorization or tokenization request for the total amount. 

Payment Workflow (authCard and authManual)

A call to the authCard or authManual endpoint captures payment card data and initiates an Authorization request to the CardPointe Gateway.

Generally, an authCard or authManual request initiates the following sequence:

  1. The client application sends the request to the Bolt service.
  2. The Bolt service sends a ping command to the terminal to verify the connection.
  3. The Bolt service sends a series of commands to the terminal, based on the options specified in the request.

    For example:
    1. The terminal displays the transaction amount, and prompts the user to confirm.
    2. The terminal prompts the user to swipe/insert/tap or manually enter the card data.
    3. The terminal prompts the user for a signature.
  4. The captured data is passed in an authorization request to the CardConnect Gateway, which returns the authorization response details.
  5. The authorization response text (resptext) displays on the terminal (for example, "Approved").

Tokenization Workflow (readCard and readManual)

A call to the readCard or readManual endpoint captures payment card data and returns a token to be used in a subsequent Authorization request to the CardPointe gateway. These endpoints do not initiate an Authorization or capture funds.

Generally, a readCard or readManual request initiates the following sequence:

  1. The client application sends the request to the Bolt service.
  2. The Bolt service sends a ping command to the terminal to verify the connection.
  3. The Bolt service sends a series of commands to the terminal, based on the options specified in the request.

    For example:
    1. The terminal displays the transaction amount, and prompts the user to confirm.
    2. The terminal prompts the user to swipe/insert/tap or manually enter the card data.
    3. The terminal prompts the user for a signature.
  4. The Bolt service returns the tokenized card number, signature, and any additional data to the client application.
  5. The client application can then pass the token and cardholder data in an authorization request to the CardConnect Gateway to capture the funds for the transaction.

Using the Bolt API Operational Endpoints

You use the following endpoints to capture information for use by your point-of-sale system:

See the Bolt P2PE API for a complete description of each request and response

API Service EndpointDescription
readInputYou can use the readInput endpoint to capture customer information (for example, an email address or loyalty account ID).

See Using readInput to Capture Customer Information for more information.
readSignatureYou can use the readSignature endpoint to capture a customer's signature.

See Capturing and Handling Cardholder Signatures for more information.
readConfirmationYou can use the readConfirmation endpoint to prompt the customer to confirm the purchase amount.
displayYou can use the display endpoint to display text on the terminal's screen.
clearDisplayYou can use the clearDisplay endpoint to clear the terminal's screen and return to the idle display.
cancelYou can use the cancel endpoint to cancel an in-flight command on the terminal.

Using readInput to Capture Customer Information

Calling the Bolt API readInput endpoint sends a command to the terminal to prompt the user to enter information. The user follows the prompt and enters information (for example, a phone number), and the information is returned to the calling application.

You might use this endpoint to gather customer contact information to store in a profile, allow the customer to enter a phone number to look up a loyalty account, or request some other information required for your business.

A request to the readInput endpoint requires the format parameter, which is used to specify the type of user input requested from the terminal.

The following table describes the supported format values and how each can be used:

The following values are case-sensitive. For example, you must enter "PHONE" not "phone" or "Phone." entering an incorrect value returns the error "errorMessage": "Invalid Format".

ValueDescriptionUseExamples
PHONE Phone Number Entry Use the PHONE format to prompt the terminal to receive a phone number input.

Workflow example:
  1. The application sends a readInput request to the terminal with "format" : "PHONE".
  2. The terminal displays a phone number input field including dashes (-).
  3. The user enters a phone number using the keypad.
  4. The response returns the phone number, including dashes to the calling application.
request:
"format" : "PHONE"

response:
"input" : "1-234-567-8901"
amount Amount Entry Use the AMOUNT format to prompt the terminal to receive an amount input.

Workflow example:
  1. The application sends a readInput request to the terminal with "format" : "AMOUNT".
  2. The terminal displays an input field with a dollar sign ($) and decimal.
  3. The user enters a dollar amount, using the keypad.
  4. The amount is returned to the calling application.

    Note that the the returned value is numeric only, with the decimal and dollar sign implied. For example, if the user enters "$123.45" at the terminal, the response returns 12345.
request:
"format" : "AMOUNT"


response:
"input" : "12345"
MMYYMonth/Year Date Entry Use the MMYY format to prompt the terminal to receive a month/year date input.

Workflow example:
  1. The application sends a readInput request to the terminal with "format" : "MMYY".
  2. The terminal displays an input field with 4 digits separated by a forward slash (/).
  3. The user enters the 2-digit month and 2-digit year, using the keypad.
  4. The response returns the 4-digit month and year string to the calling application in the format MMYY.

    For example, if the user enters "11/18" at the terminal, the response returns 1118.
request:
"format" : "MMYY"


response:
"input" : "1222"
Nx[,y]Numeric Entry Use the Nx[,y] format to prompt the terminal to receive a numeric string input.
N specifies a numeric entry where:
  • x = the minimum number of digits.
  • y = the maximum number of digits, up to 32.

    y is optional, and if y is not specified, then the input must match the length specified by x.
For example:
  • If you specify N5, then the user input must be a 5-digit number, such as "19406."
  • If you specify N5,9, then the user input can be a number ranging from 5 to 9 digits, such as "08081" or "080819876."
Workflow example:
  1. The application sends a readInput request to the terminal with "format" : "N5" to capture the cardholder's zip code for demographic purposes.
  2. The terminal displays a 5-digit input field.
  3. The user enters the 5-digit zip code, using the keypad.
  4. The response returns the 5-digit string to the calling application.
request:
"format" : "N5"


response:
"input" : "19406"


request:
"format" : "N5,9"


response:
"input" : "194062848"

ANx[,y] Alpha-Numeric Entry Use the ANx[,y] format to prompt the terminal to receive an alphanumeric string input.
AN specifies an alphanumeric entry where:
  • x = the minimum number of characters.
  • y = the maximum number of characters, up to 32.

    y is optional, and if y is not specified, then the input must match the length specified by x.
For example:
  • If you specify AN8, then the user input must be an 8-character entry, such as "A1B2C3D4."
  • If you specify AN1,32, then the user input can be an entry ranging from 1 to 32 characters, such as "A" or "A123."
Workflow example:
  1. The application sends a readInput request to the terminal with "format" : "AN1,20" to capture the cardholder's driver's license number.
  2. The terminal displays an alphanumeric input field.
  3. The user enters the driver's license state and number, using the keypad.
  4. The response returns the alphanumeric string to the calling application.
request:
"format" : "AN8"


response:
"input" : "A1B2C3D4"


request:
"format" : "AN1,20"


response:
"input" : "PA22639348"

Sharing a Bolt Terminal Between POS Systems

This guide provides information for sharing a Bolt terminal among two or more integrated point-of-sale (POS) systems using more than one merchant ID (MID).

Overview

Bolt terminals are identified by a CardConnect hardware serial number (HSN), which can be found on a label on the terminal, or on the terminal's display. When CardConnect provisions a Bolt terminal, the HSN is assigned to a parent merchant ID (MID), which is used to fulfill the order and maintain a chain of custody for the terminal.

All Bolt P2PE API requests require a MID. Typically, the integrated POS software uses the MID assigned to the terminal to tokenize credit card numbers and send authorization requests.

Tokens are site-specific; however, a token can be used by any MID on the same site. Therefore, you can use the MID assigned to the terminal to tokenize a credit card using a readCard or readManual request, and then use another MID on your site to use that token to make an authorization request to the CardPointe Gateway.

The following topics describe this workflow in greater detail, including required parameters and best practices.

Connecting to the Terminal

First, one of the integrated POS systems must connect to the terminal.

The POS system sends a request to the Bolt P2PE API's connect endpoint. See the Bolt P2PE API for detailed information on using the API to send requests.

When sharing a terminal, do not include "force" : "true" in the request. Doing so will terminate active (or in-flight) transactions.

A successful response header includes a session key in the format <key value>;<expiration>. This session key value must be provided as a session key/value pair in the header of every subsequent request in the format X-CardConnect-SessionKey: <key value>.

When multiple POS systems are sharing a terminal, and "force" : "false", a POS system will receive the following error response if it attempts to send a command to a terminal that is already in use:

You can handle this error by displaying a message on your POS system such as "Terminal in use. Please retry in a few seconds."

Getting a Token

Once your POS system is connected and has a valid session key, it can begin to make tokenization requests by calling the readCard endpoint for card present transactions, or readManual endpoint for card not present transactions.

These requests prompt the terminal's user to swipe/insert/tap or manually enter the payment card information.

The customer inserts the payment card at the terminal, and Bolt returns a token in a successful response to your POS system.

This token is not directly associated with the MID used in the readCard request; therefore another MID on the same site can use this token in an authorization request to the CardPointe Gateway.

Authorizing the Payment Using a Different MID

Once your POS system has retrieved the token, you can use the token in a request to the CardPointe Gateway API's auth endpoint.

The authorization request requires a MID; however, this MID can be any MID that shares a site with the MID that obtained the token. In this case an integrated POS system associated with another MID on the same site creates an authorization request.

The request is processed, and a successful response includes the authorization response details.

This transaction flow included two MIDs: one to obtain a token from the Bolt terminal, and one to submit an authorization request to the CardPointe Gateway. For reporting purposes, the MID that made the authorization request is the MID that is associated with the transaction.

Accepting Closed Loop Gift Cards with Bolt

CardConnect allows merchants the flexibility to accept their own proprietary, closed loop gift cards for customer purchases. If you want to include closed loop gift cards in your accepted payment methods, review the following information to get started.

Gift Card Requirements

Before you begin, check with your gift card printer to verify that your gift cards meet the following requirements:

  • Cards must include a magnetic-stripe to provide track 2 data.
  • The track data must include an expiration date.
  • Cards numbers must pass Luhn algorithm verification.
  • Card numbers must not start with 9.
  • Card numbers must not be greater than 19 digits. 
  • You must provide CardConnect with a unique Bank Identification Number (BIN) range for your gift cards. This range must not overlap any other BIN ranges.

If you currently use gift cards that do not meet all of these requirements, or if they are in a different BIN range, you will not be able to accept those gift cards.

How it Works

Accepting gift cards with your existing CardConnect solutions is simple, provided your cards meet the stated requirements.

Using Bolt

If you are using Bolt to process payments, you can use a readCard or readManual request to initiate a gift card transaction. When the gift card is swiped or manually entered at a Bolt terminal, Bolt matches the BIN with the range of BINs for your gift cards and returns an unencrypted clear text card number, which your point-of-sale software uses to complete the transaction.

Unlike a credit or debit card transaction, Bolt does not encrypt or tokenize the card number.

Using CardSecure

If your software directly integrates the CardSecure API, your software passes the gift card number to CardSecure, which matches the BIN with the whitelisted BIN range and returns the unencrypted card number.

Unlike a credit or debit card transaction, CardSecure does not encrypt or tokenize the card number.

Establishing a BIN Range

Before you can begin to accept gift card payments, you must provide CardConnect with the BIN range used to identify your gift cards. CardConnect uses this information to whitelist the specific BIN range, allowing CardSecure to return unencrypted clear text data to your point-of-sale software.

Contact CardConnect Support to get started.

The BIN range that you provide must be unique, and must not overlap any other BIN range.

Loading a Gift Card

When a customer purchases a gift card, the merchant initiates an authorization request using the customer's payment card. The authorization response data can then be used to update the merchant's ledger to include the transaction amount, the total amount added to the gift card, the quantity of gift cards, issued gift card numbers, and any additional identifying information for the transaction.

Accepting a Payment

When a customer presents a gift card for payment, the payment request process is similar to accepting a credit or debit card payment. For example, your point-of-sale software initiates a readCard request using the Bolt API, and the card is swiped or dipped at the Bolt terminal. Bolt then matches the gift card BIN with the range of BINs that you provided, and returns the unencrypted clear text card number to your point-of-sale software. From there, your software completes the transaction.

In the event that the gift card balance is insufficient to cover the full amount of the transaction, your software will need to initiate a second request to complete the transaction using another payment method.

Managing Gift Card Transactions

Because these gift card transactions take place within a closed loop, no settlement or funding data is passed to an issuing bank. Instead, it is the merchant or partner's responsibility to manage gift card transaction and funding data. By integrating with the CardPointe Gateway API and Bolt P2PE API your software can retrieve the data necessary for you to manage your general ledger, and to ensure that funds are transferred from the gift card to the merchant.

Support

For general inquiries or support for integrating gift cards into your CardConnect payment solution, contact integrationdelivery@cardconnect.com.

Handling Timeouts

This guide describes Bolt's transaction timeout handling and reversal process.

Understanding Timeouts

The Bolt payment flow includes requests to and responses from both the Bolt P2PE API and the CardPointe Gateway API. Both of these APIs support synchronous communication; therefore, your application must make requests and expect responses in sync with the Bolt and CardPointe Gateway services.

As a developer integrating these solutions with your point-of-sale software, it is important for you to understand how long the steps of the payment process can take so your software can interact accordingly. 

The following topics provide information to help you understand the possible timeout scenarios and how Bolt handles each situation.

Bolt Request Timeout (2 Minutes)

Most interactions between the Bolt terminal and your application require user input of some kind. Users might be prompted to swipe or insert a card, manually enter payment card information, or provide a signature or phone number. Because these interactions can take time to complete, the Bolt service waits 1 minute and 59 seconds for a response after a request is made.

If the Bolt service does not receive a response from the terminal within 2 minutes, the request times out and Bolt returns an HTTP 500 Error Code 1 "Terminal request timed out." Your application must resubmit the request.

Bolt Authorization Request Timeout (2 Minutes + 32 Seconds)

When you use the Bolt API authCard or authManual requests to authorize a payment, you must consider the individual timeout thresholds for both the Bolt API and the CardPointe Gateway API requests and responses. The Bolt authorization requests combine the time needed for a Bolt request (2 minutes) and the time it takes to handle the authorization request and response through the CardPointe Gateway (32 seconds).

After the request is sent, the terminal collects payment data from the user and sends it to the Bolt server. The Bolt server then makes an authorization request to the CardPointe Gateway.

The CardPointe Gateway sends the authorization request to the payment processing network and allows 31 seconds for a response. If the CardPointe Gateway does not receive a response within this limit, the request times out at 32 seconds and returns a "Timed Out" response to Bolt, which is included in the response. 

In some cases (for example, a network error), Bolt might not receive a response from the CardPointe Gateway. In these cases, Bolt automatically initiates a timeout reversal sequence to ensure that the transaction is voided. 

See Bolt Timeout Handling, later in this guide, for more information.

CardPointe Gateway Authorization Timeout (32 Seconds)

When you use the Bolt API readCard or readManual requests to tokenize card data for use in a CardPointe Gateway authorization request, you only need to consider the CardPoint Gateway timeout threshold. The CardPointe Gateway sends the request to the payment processing network and allows 31 seconds for a response. If the CardPointe Gateway does not receive a response within this limit, the request times out at 32 seconds and returns a "Timed Out" response. 

See the Handling Timed-Out Transactions CardPointe Gateway Developer Guide for information on handling Gateway-only time outs.

Bolt Timeout Handling

If your application uses authCard or authManual requests to authorize payments, you should allow it to handle the following scenarios:

Time Out Response Returned

In this case, a response, including a retrieval reference number (retref) for the transaction, is returned. You can use the retref to make an inquire request to the CardPointe Gateway to retrieve details about the authorization attempt.

"Timed Out" Response Example
Status: 200 OK
 
{
    "amount":"685.00",
    "resptext":"Timed out",
    "setlstat":"Declined",
    "acctid":"1",
    "respcode":"62",
    "merchid":"123456789012",
    "token":"9441282699177251",
    "respproc":"PPS",
    "name":"Jane Doe",
    "currency":"USD",
    "retref":"343005123105",
    "respstat":"B",
    "account":"9419786452781111"
}

The response includes a response status (repstat) of "B," which always means "Retry." Your application should resubmit the authorization request.

In this situation, CardConnect cannot guarantee that retrying the authorization will succeed. In the event of multiple retry failures, visit status.cardconnect.com to see if there are system-wide issues.

No Response Returned

In this case, your application cannot determine whether or not the transaction was successful.

When Bolt does not receive a response from the CardPointe Gateway, Bolt uses the order ID included in the request to handle the timed out transaction. Bolt generates a unique order ID for every transaction in the format <HSN-timestamp>. Alternatively, you can specify a unique order ID in your authCard and authManual requests.

If you include an order ID in your authCard or authManual requests you must ensure that you provide a unique value. Using duplicate order IDs can lead to the wrong transaction being voided in the event of a timeout.

Bolt makes an inquireByOrderid request to the CardPointe Gateway to check the status of the transaction. If the CardPointe Gateway returns a response, Bolt forwards the response to your application.

If Bolt does not receive a response to the inquireByOrderid request, it makes three voidByOrderId requests to void the transaction and ensure that funds were not captured. If at least half of the CardPointe Gateway timeout threshold remains, Bolt retries the authCard or authManual request. Otherwise, your application must resend the request. 

Capturing and Handling Cardholder Signatures

Some Bolt terminals include the ability to capture a cardholder signature. This guide provides recommendations and integration details for capturing and handling signatures, if necessary for your business.

Signature Rules and Requirements

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

Consult the following card brand guidelines for detailed information:

Additionally, signature requirements vary depending on the card type. For example, EMV (chip and contactless) cards do not require a signature. Ensure that you understand the requirements for accepting both EMV and MSR (magnetic-stripe) cards as determined by the card brands.

As of April 2018, the major card brands no longer require merchants to capture cardholder signatures. See the Updated Signature Requirements for more information on this change.

Cardholder Signature Guidelines

As mentioned earlier in this guide, specific rules and requirements vary by card brand and by card type. Refer to each card brand's guidance for more information.

While most transactions do not require you to capture a signature, there are some cases in which you might want to to protect your business.

Consider the following best practices:

  • For EMV (chip and contactless) card transactions, no signature is required; however, you might want to capture signatures for large or high-risk transactions.
  • For MSR (magnetic-stripe) card transactions, you should capture a signature for amounts over $50.

If you only want to capture signatures for MSR transactions, see Detecting MSR Transactions below for information on determining when a transaction has been processed as MSR.

Capturing Cardholder Signatures

Capturing signatures requires a direct integration to the CardPointe Gateway API. While you can prompt for and capture a signature during the transaction, using the Bolt API, you must call the CardPointe Gateway API's signatureCapture endpoint to attach the signature to the authorization record.

Capturing a Signature During a Transaction

To run an authorization and capture a signature at the same time, do the following:

  1. Call the Bolt API authCard or authManual endpoint and include the includeSignature = true parameter.

    The signature prompt and capture are integrated into the command sequence that the Bolt API sends to the terminal, and the authorization response and signature data are returned to your software.
  2. Call the CardPointe Gateway API's signatureCapture endpoint, including the retref and signature returned in the authorization response, to add the signature to the transaction record.

Capturing a Signature After a Transaction

To run an authorization and capture a signature later, do the following

  1. Call the Bolt API authCard or authManual endpoint and include the includeSignature = false parameter.

    The authorization response is returned to your software.
  2. Call the Bolt API readSignature endpoint to prompt for and capture the cardholder's signature.

    The signature data is returned to your software.
  3. Call the CardPointe Gateway API's signatureCapture endpoint, including the retref and signature returned in the authorization response, to add the signature to the transaction record.

Detecting MSR Transactions

If you only want to capture a signature for transactions using MSR (magnetic-stripe) cards, you can use the data received in the authorization response to steer the behavior of your software.

For example, do the following:

  1. Call the Bolt API authCard endpoint and include the includeSignature = false parameter.

    The authorization response is returned to your software. If the authorization response does not include an EMV tag data array, or if entrymode = swipe, then the transaction was processed as MSR.
  2. If you want to capture a signature for the transaction, do the following:
    1. Call the Bolt API readSignature endpoint to prompt for and capture the cardholder's signature.

      The signature data is returned to your software.
    2. Call the CardPointe Gateway API's signatureCapture endpoint, including the retref returned in the authCard response and the signature returned in the readSignature response to add the signature to the transaction record.

Printing Receipts Using Authorization Data

This guide provides information for integrators who want to use authorization response data to print receipts from an integrated POS printer.

Receipt Rules and Requirements

This topic provides general best practices and integration details for printing receipts and capturing cardholder signature data; 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, receipt requirements vary depending on the card type. For example, receipts generated for EMV (chip and contactless) 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:

Authorization Response Data

A successful authorization response includes the following fields. You should include the highlighted fields on your receipts.

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 authorization 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

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

The following example illustrates a receipt template (left) and a receipt populated with data retrieved from the authorization response (right).

Accepting Payments when Bolt is Offline

Bolt's Offline Mode enables a merchant to accept transactions when the Bolt terminal is unable to connect to the Bolt server. In Offline Mode, encrypted transaction records are stored locally in the Bolt terminal firmware until the terminal is able to connect to the Bolt server to authorize and process the transactions.

Contact integrationdelivery@cardconnect.com to enable Offline Mode for your Bolt merchants.

Requirements

To use Offline mode, your Bolt P2PE solution must include the following:

  • An Ingenico Bolt terminal device configured to run in Offline Mode.
  • Terminal firmware version 1.6.2.11 or later.
  • The necessary Offline Settings must be configured for your merchant account. Contact integrationdelivery@cardconnect.com for assistance.

Risks and Mitigations

Before you decide to accept transactions in Offline Mode, consider the significant risks of accepting delayed payments. By accepting customer card data before a transaction can be authorized, you assume the risk of the authorization being declined after the sale is completed (for example, if the payment card is expired or cancelled, or if the PIN is incorrect).

CardConnect does not accept liability for lost funds due to declined authorizations processed in Offline Mode. By enabling your merchants to accept transactions in Offline Mode, you assume liability for all risks involved.

To mitigate the risk of lost funds, CardConnect recommends that you employ the following best practices:

  • Ensure that cardholders do not interact with the Bolt terminal while operating in Offline Mode. Restrict access to the merchant user.
  • Ensure that the merchant user is trained in operating the terminal in Offline Mode to prevent user errors.
  • Assign unique order ID values for all Offline Mode transactions, so the order ID can be used to accurately tie records between the terminal’s offline batch and your software's order records.
  • When you work with CardConnect support to configure the required Offline Settings, you should:
    • Use the Offline Max Transaction Amount property to set a conservative limit on the maximum dollar amount that you will accept while operating in Offline Mode.
    • Use the Offline Max Transaction Count property to set a conservative limit on the number of transactions that you will accept while operating in Offline Mode.

      See Configuring Terminal Properties for more information.

Configuring Terminal Properties

To enable Offline Mode and configure the terminal behavior, the following terminal properties must be configured for the merchant account. To configure these properties and reprovision your terminals, contact CardConnect support at integrationdelivery@cardconnect.com. Note that the terminal must be restarted for the configuration changes to take effect.

Property NameValueDefault ValueDescription
Offline Mode

Yes/No

No

Specifies whether Offline Mode is enabled.

Require PIN

Yes/No

No

Specifies whether a PIN entry is required for swiped cards in Offline Mode.

When enabled:

  • If the card is not chipped, the merchant is prompted to select credit or debit. If the merchant selects debit, then prompted to enter a PIN.
  • If the card is chipped, the chip determines if the PIN is required.
Require Signature

Yes/No

No

Specifies whether a cardholder signature is required for swiped cards in Offline Mode.

When enabled:

  • If the card is not chipped, and a PIN was not entered, the merchant is prompted to capture the cardholder signature.
  • If the card is chipped, the chip determines if the signature is required.
Max Transaction AmountNumeral

100

Specifies the maximum amount (in dollars) allowed for a single transaction in Offline Mode.

Max Number of TransactionsNumeral

0 (Unlimited)

Specifies the maximum number of transactions allowed in a single Offline Mode session.

Using the Bolt Terminal in Offline Mode

When the terminal is unable to connect to the Bolt server, the terminal displays "UNBOLTED" in the status field. If Offline Mode is enabled, the merchant can continue to process transactions in Offline Mode.

Notes:

  • Ensure that access to the terminal is limited to the merchant. The cardholder should not interact with the terminal in Offline Mode.
  • The terminal cannot communicate with the POS software while operating in Offline Mode.

To use the terminal in Offline Mode, do the following:

  1. Enter the transaction amount.

    Note: If the transaction amount exceeds the Offline Max Transaction Amount configured in the Merchant Properties in TMS, the terminal displays an alert, and returns to the initial prompt.
  2. Enter a unique order ID.

    This Order ID will be associated with the authorization record and used during the transaction reconciliation process. It is strongly recommended that you use a unique value for every offline transaction.
  3. When prompted to specify if the card is present, press Yes if the card is present and able to be swiped or inserted, or No if the card is not present.
  4. Swipe or insert the card or manually enter the account number.
  5. If required, capture the cardholder's signature.

Viewing Offline Mode Transactions in CardPointe

When the terminal's connection to the Bolt service is restored (the terminal displays "BOLTED"), stored transactions that were accepted in Offline Mode are retrieved by the Bolt server and sent to the CardPointe Gateway for authorization and capture.

Offline transactions are not returned to your point-of-sale software. To reconcile these transactions and verify that they were successfully authorized and captured, you can access them in the merchant account in CardPointe.

To view the status of the offline transactions do the following:

  1. Log in to CardPointe and access the merchant account.
  2. Click Reporting in the menu bar, and select the Transactions tab.
  3. View the transactions for the merchant account.
  4. Optionally, enter the unique order ID for an offline transaction to view a specific transaction. Additionally, you can view the serial number for the terminal that accepted the transaction, the card data entry method, and other details for the transaction.

See the CardPointe Web App support page for more information.