Understanding the Terminal API Application Workflow

The CardPointe Integrated Terminal 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 Terminal API integration generally involves the following workflow:

1. Connecting a Terminal
2. Connecting your Client
3. Establishing a Session
4. Setting the Terminal's Time
5. Getting a Token and Running a Payment

Connecting a Terminal

Once a 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.

The terminal displays either Connected or Disconnected depending on whether it has established an internet connection and made contact with the terminal service.

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

Connecting your Client

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

https://<site>.cardpointe.com/api/v3

An API key is required as the HTTP authorization header in each POST request. The API key is provided by an 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.

Establishing a Session

In addition to connecting to the 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 Terminal 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"

In this case, send a connect request including "force" : "true" to forcibly terminate the invalid session and retrieve a new session key.

Setting the Terminal's Time

You should include the dateTime request into your terminal connection workflow to ensure that the terminal's time is accurate for transaction reporting and receipts, and to ensure that the terminal's nightly PCI reboot occurs outside of your business hours, as intended.

Getting a Token and Running a Payment

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

• If you use the Terminal 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 Terminal API authCard or authManual endpoint to get a token, the terminal 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, we created a sample Postman Collection that includes a template of the Terminal API service endpoints.

Configuring Your Postman Environment

The Terminal 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 CardPointe Integrated Terminal device and API key, you can configure the following variables to auto-fill your merchant-specific data in requests to the Terminal API:

• site - Set this value to the UAT or production host that you received (for example, bolt-uat). The {{site}} variable is required to complete the URL.
• url - Set this value to the root URL that you received . The {{url}} variable is used to set the base url (host and port) for the REST web services.
• Authorization - Set this value to the API key that you received. The {{Authorization}} variable is used in the header of every request.
• merchantId - Set this value to your CardPointe merchant ID. 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. Select the Terminal API UAT Environment, then click the eye icon to open the environment.
   
   
2. Click Edit to open the Manage Environments menu.
   
3. On the Manage Environments menu, enter your merchant-specific values for each variable, then click Update.
   

Understanding the Terminal API Service Endpoints

Your client application makes requests to the Terminal API service endpoints to send commands to the connected terminal.

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

• Connectivity endpoints
• Payment and tokenization endpoints
• Operational endpoints

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

Using the Terminal API Connectivity Endpoints

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

Using the Terminal API Payment and Tokenization Endpoints

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

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 terminal service.
2. The terminal service sends a ping command to the terminal to verify the connection.
3. The terminal 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 CardPointe 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 terminal service.
2. The terminal service sends a ping command to the terminal to verify the connection.
3. The terminal 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 terminal 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 CardPointe Gateway to capture the funds for the transaction.

Using the Terminal API Operational Endpoints

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

Using readInput to Capture Customer Information

Calling the Terminal 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:

Configuring Custom Themes and Logos

CardPointe Integrated Terminal devices support the ability to display a custom image, such as your merchant’s or software’s logo, and to modify the color of the header, footer, and font that displays within the user interface. This allows you to match the style of the terminal interface with your branding to create a more seamless experience for the end user.

Wallpaper Image Requirements

Ensure that your image meets the following requirements:

Theme Requirements

Customizing the Terminal Beep Settings

To experiment with the volume, pitch, and duration of the beep heard when using the device, you can temporarily adjust these settings from the Beep menu. The terminal beeps when prompting the user to tap/insert/swipe a card, and when prompting to remove. 

1. Access the Admin Menu:
   1. Press F and enter the default password of CCMerchant.
   2. Press O (green button) to confirm the password.
2. Press O (green button) to select Settings.
3. Press the down arrow to scroll down and press O (green button) to select Beep.
4. Use the number pad to enter a value for Frequency (Hz) and press the down arrow to scroll down and enter values for Volume, Time On (ms), and Time Off (ms). Reference the table below for the default values and acceptable ranges.

   Parameter Name	Default	Range	Description
   Frequency (Hz)	1,000	20-20,000	The frequency of the beep in Hz or vibrations per second. Controls the pitch of the beep.
   Volume	100	1-100	Controls the volume of the beep, as a percentage. Low – 1-30 Medium – 31-70 High – 71-100
   Time On (ms)	250	10-5,000	Controls the length of each single beep.
   Time Off (ms)	250	10-5,000	Controls the length of time between each beep.

5. Press O (green button) when finished.
6. The terminal displays Beep parameters have been updated and beeps several times to confirm the new settings.

Sharing a Terminal Between POS Systems

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

Overview

CardPointe Integrated Terminal devices are identified by a unique hardware serial number (HSN), which can be found on a label on the terminal, or on the terminal's display. When a terminal is provisioned, 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 Terminal 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, as described in Connecting a Terminal. 

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:

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 the Terminal API returns a token in a successful response to your POS system.

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.

Accepting PIN Debit Cards

This guide provides information for accepting PIN debit payments.

Merchant Requirements

To accept PIN debit transactions, your merchant account must be boarded to the First Data Rapid Connect processing platform.

Merchants already accepting PIN debit on the First Data North platform continue to be supported; however new or existing merchants who want to include support for PIN debit must be boarded to the Rapid Connect platform.

Contact integrationdelivery@fiserv.com to confirm your merchants' compatibility.

Integration Requirements

• Your integration must include Ingenico terminals provisioned with the required key for processing PIN debit transactions. PIN debit is currently not supported for Clover terminals.
• Your application must be updated to include the following fields in the authCard and readCard requests for PIN debit transactions:
  • "aid" : "debit" - This allows the terminal to accept the debit application identifier (AID), when available on the customer's card.
  • "includePIN" : "true" - This prompts for PIN input on the terminal.

Understanding EMV (Chip) and MSR (Swipe) Debit Card Handling

The parameters that your application must pass in the readCard or authCard request depend on the type of card presented in the transaction.

EMV (chip) cards are programmed with an application identifier (AID) that determines the card type. To process an EMV card as PIN debit, the card must be programmed with a debit AID, and your application must include "aid" : "debit" in the authCard or readCard request. Additionally, EMV cards are programmed with a cardholder verification method (CVM) specification, which determines if the transaction requires the cardholder's signature or PIN.

Cards that do not support debit transactions (credit-only cards) may also support PIN entry as a CVM. Including "aid" : "debit" in your request will ensure the cardholder is prompted for a PIN, whenever the credit or debit card supports it. However, the AID embedded in the EMV data of a credit-only card will ensure the transaction is ultimately processed as credit.

Non-EMV (magstripe or MSR) cards also fall into different categories, as specified in the card's track data. For MSR debit transactions, your application must specify "includePin" : "true" in the request to prompt the cardholder for their PIN.

The following examples illustrate authCard and readCard requests including the PIN debit parameters: 

Handling PIN Prompts

You can use the readConfirmation request to prompt the customer to specify whether they intend to pay with a credit or debit card prior to initiating the readCard or authCard sequence. This can be useful to create a conditional application sequence in which the user's credit or debit selection determines the values that your application passes in the aid and includePIN parameters in the subsequent readCard or authCard request.

A call to the readConfirmation endpoint prompts the user to acknowledge or reply to a message on the terminal. 

You can use the prompt parameter to ask the user a question (for example, "Is this debit?"). If the customer selects yes at the terminal, the readConfirmation response includes "confirmed" : "true". Your application can then call the authCard endpoint with "aid" : "debit" and "includePIN" : "true".

The following examples illustrate the readCard request and response in this scenario:

Accepting Closed Loop Gift Cards

The CardPointe platform 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, see Tokenizing Closed Loop Gift Cards in the CardSecure Developer Guides for more information.

Handling Timeouts

The following topics provide information for understanding and handling transaction timeouts.

Understanding Timeouts

The payment flow includes requests to and responses from both the Terminal 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 terminal service and CardPointe Gateway service.

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 the terminal service handles each situation.

Terminal Request Timeout (2 Minutes)

Most interactions between the 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 terminal service waits 1 minute and 59 seconds for a response after a request is made.

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

Terminal API Authorization Request Timeout (2 Minutes + 32 Seconds)

When you use the Terminal API authCard or authManual requests to authorize a payment, you must consider the individual timeout thresholds for both the Terminal API and the CardPointe Gateway API requests and responses. The Terminal API authorization requests combine the time needed for a terminal 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 terminal service. The terminal service 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 the Terminal API, which is included in the response. 

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

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

CardPointe Gateway Authorization Timeout (32 Seconds)

When you use the Terminal 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 in the CardPointe Gateway Developer Guides for information on handling Gateway-only time outs.

Terminal API Timeout Handling

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

• The application receives a "Timed out" response from the CardPointe Gateway or terminal service.
• The application receives no response.

Gateway Timed 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.

Gateway "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.

No Response Returned

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

When the terminal service does not receive a response from the CardPointe Gateway, the terminal service uses the order ID included in the request to handle the timed out transaction. The terminal 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.

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

If the terminal service 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, the terminal service retries the authCard or authManual request. Otherwise, your application must resend the request. 

Capturing and Handling Cardholder Signatures

Some 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:

• MasterCard: https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/transaction-processing-rules.pdf
• Visa: https://usa.visa.com/dam/VCOM/download/about-visa/visa-rules-public.pdf

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.

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 Terminal 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 Terminal API authCard or authManual endpoint and include the includeSignature = true parameter.
   
   The signature prompt and capture are integrated into the command sequence that the Terminal 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 Terminal API authCard or authManual endpoint and include the includeSignature = false parameter.
   
   The authorization response is returned to your software.
   
2. Call the Terminal 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 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 Terminal 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 Terminal 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 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:

• MasterCard: https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/transaction-processing-rules.pdf
• Visa: https://usa.visa.com/dam/VCOM/download/about-visa/visa-rules-public.pdf

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:

• transaction details from the authorization response
• merchant account information and additional transaction details returned in the receipt object
• EMV tag data returned in the EMV tag object, if the card used was an EMV (chip or contactless) card.

Authorization Response Data

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

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:

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:

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:

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 a Credit Card Surcharge

Surcharging allows merchants to add a "% checkout fee" to a credit card transaction, paid by the cardholder, to help cover the merchant’s credit card processing fees.

The Merchant Surcharge Program allows eligible merchants to add a surcharge on applicable credit card transactions. This guide provides an overview of the integration requirements for surcharging card-present credit card transactions using a CardPointe Integrated Terminal.