The Bolt Terminal API is now the CardPointe Integrated Terminal API.
Overview
The CardPointe Integrated Terminal API streamlines the integration of our P2PE-validated, card-present payment acceptance solution with your point-of-sale (POS) application. Integrating the Terminal API with your application, allows you to easily and securely accept card-present payments within your POS environment.
The CardPointe Integrated Terminal solution consists of the following components:
The Terminal API, which provides your software with access to the terminal service.
CardPointe Integrated Terminals, pre-provisioned for your merchant account.
The CardPointe Gateway, which provides a complete solution for transaction processing and reporting.
CardSecure, which tokenizes payment card information.
Your point-of-sale (POS) software, integrated with the Terminal API.
This API reference describes the complete Terminal API and all supported features and operations. Some features are specific to either Ingenico or Clover terminals, as noted throughout the API. See the CardPointe Integrated Terminal Developer Guide for Clover Terminals for detailed information on key differences and additional information specific to integrating Clover terminals.
The CardPointe Gateway API provides additional capabilities not offered by the Terminal API, including the ability to void or inquire on past transactions. To take full advantage of these features, you must integrate the CardPointe Gateway API into your payment acceptance solution. See the CardPointe Gateway API for information on integrating these features and other advanced capabilities.
What's New?
Visit Statuspage and click subscribe to updates to receive important release and status notifications.
Date Updated: 10/24/2023
An update to the CardPointe Integrated Terminal service is planned for deployment to the UAT environment on 10/24/2023, and is tentatively planned for deployment to the Production environment on 10/28/023.
This update includes backend improvements and enhancements; no merchant impact is expected.
The Terminal API is a RESTful web service, which uses the JSON (JavaScript Object Notation) method of encoding data for transmission via the HTTP network protocol. Most programming languages have libraries to convert an arbitrary object to and from a JSON data transfer encoding. See the API Basics and Best Practices Guide for more information on these concepts.
The Terminal API provides a library of POST operations used to submit HTTP requests to the web service. The Terminal service expects that ALL properties are encoded as US ASCII strings. Responses are returned in JSON objects. See Service Endpoints for detailed information on the supported request types and corresponding responses.
Changes to the Terminal API are designed to retain backwards-compatibility. The JSON standard does not assign any significance to the ordering of key/value pairs, and this API does not guarantee the order of key/value pairs in response messages. See the API Basics and Best Practices Guide for recommendations for retaining backwards compatibility in your application.
Requirements
Integrating the Terminal API requires:
Your application, which calls the Terminal service endpoints via HTTPS.
Pre-provisioned terminal devices.
Additionally, integrating EMV acceptance requires your merchant account to be on a supported processing platform.
Additionally, review the CardPointe Gateway API documentation for more information on the additional transaction processing and reporting capabilities offered by the CardPointe Gateway, for example the ability to void and inquire on transactions.
Run in Postman
To help you get started with your integration, we created a Terminal API Postman collection that includes a template of the Terminal API service endpoints. Click the following button to download the collection.
The following table details each service of the Terminal API, its associated resource name, and which version it is supported in.
The Terminal API version and endpoint name are appended to the base URL.
Example URL:
https://<site>.cardpointe.com/api/v2/display
Details about the REST implementation for each endpoint follow this section.
A call to the terminalDetails endpoint returns an array of terminals associated with the merchant ID specified in the request. The response includes one or more objects containing the hardware serial number (HSN), model, status, and features supported for each device.
This can be useful for merchants with multiple terminal models, 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.
A call to the dateTime endpoint sends a request to the specified terminal to set the terminal's system 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.
Endpoint URL
The URL for the dateTime endpoint is:
https://<site>.cardpointe.com/api/v2/dateTime
Request Header
The following key/value pairs are required in the request header.
Returns true if the terminal is connected to the terminal service, or false if the terminal is not connected.
connect
connect Successful Response 200 Example
HTTP/1.1 200 OK
Content-Type: application/json
X-CardConnect-SessionKey →e3072040eb08454dac18ff67cd6c311c;expires=2018-08-22T23:49:55.684Z
A call to the connect endpoint establishes a session between the terminal and the terminal service. The response returns a session key to use in subsequent requests to the terminal.
If force is set to true, any existing sessions will be destroyed and all in-flight operations on the terminal will be cancelled. The force parameter is optional and defaults to false.
Once the session is complete, call the disconnect endpoint to end the session. Otherwise, the session key will expire at the the ISO-8601 expiration timestamp included in the initial connect response.
Endpoint URL
The URL for the connect endpoint is:
https://<site>.cardpointe.com/api/v2/connect
Request Header
The following key/value pairs are required in the request header.
Key
Value
Content-Type
application/json
Authorization
The Terminal API Authorization Key
Request Parameters
Fields in bold are required.
Field
Description
hsn
Terminal hardware serial number.
merchantId
Your merchant ID, required for all requests.
force
If set to true, any existing sessions are destroyed and any in-flight operations on the terminal are cancelled.
If blank, this parameter defaults to defaults to false.
HTTP/1.1 200 OK
Content-Type: application/json
(no body)
A call to the disconnect endpoint closes the session and releases the session key provided in the request header. The session key can not be used in any subsequent requests; you must call the connect endpoint to retrieve a new session key.
The disconnect command does not cancel an in-flight transaction (for example an authCard request in progress). To terminate an in-flight transaction, call the cancel endpoint.
Endpoint URL
The URL for the disconnect endpoint is:
https://<site>.cardpointe.com/api/v2/disconnect
Request Header
The following key/value pairs are required in the request header.
HTTP/1.1 200 OK
Content-Type: application/json
(no body)
A call to the display endpoint sends a text string, which is displayed on the idle terminal.
On a Clover terminal, sending either a single or multi-line message replaces the idle image with the message, along with the logo image (if one is configured for the device).
On an Ingenico terminal:
Sending a single-line string displays the text in the display footer area, retaining the idle image.
Sending a multi-line string displays the text in the primary display area, replacing the idle image.
Additionally, you can send a blank string, which clears any existing prompts and returns the terminal display to an idle state. You can also call the clearDisplay endpoint to clear the terminal display.
For Ingenico terminals, to include a percent sign (%) in the display text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
The terminal display is limited to 1000 characters.
Endpoint URL
The URL for the display endpoint is:
https://<site>.cardpointe.com/api/v2/display
Request Header
The following key/value pairs are required in the request header.
HTTP/1.1 200 OK
Content-Type: application/json
{ "confirmed" : true }
A call to the readConfirmation endpoint retrieves a confirmation response (either true or false) from the specified terminal.
Ensure that you allow at least a 1 second delay after sending the readConfirmation command, before sending a subsequent command (for example, authCard), to prevent "terminal in use" errors.
The text to send to the terminal display to prompt for confirmation.
To include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
beep
Specifies whether the terminal beeps until the prompt is accepted.
If true, beep is enabled. If blank, the value defaults to false.
Response Parameters
Field
Description
confirmed
Returns true if the prompt was accepted at the terminal, or false if the prompt was canceled.
The text to send to the terminal display to prompt for confirmation.
The prompt parameter has a 1000-character limit.
For Ingenico terminals, to include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
format
The readInput request reads data from the terminal keypad in the specified format.
The format must be a valid getInput format.
beep
Specifies whether the terminal beeps until the prompt is accepted.
If true, beep is enabled.
If blank, the value defaults to false.
getInput Formats
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."
Use the PHONE format to prompt the terminal to receive a phone number input.
The terminal displays a phone number input field with dashes (-).
The response returns the phone number, including dashes.
AMOUNT
Amount Entry
Use the AMOUNT format to prompt the terminal to receive an amount input.
The terminal displays an input field with a dollar sign ($) and decimal. The returned value is numeric only, with the decimal and dollar sign implied.
For example, if "$123.45" is entered at the terminal, the response returns 12345.
MMYY
Month/Year Date Entry
Use the MMYY format to prompt the terminal to receive a month/year date input.
The terminal displays an input field with four digits separated by a forward slash (/). The response returns the 4 digit month and year in the format MMYY.
For example, if "11/18" is entered at the terminal, the response returns 1118.
Nx[,y]
Numeric Entry
Use the Nx[,y] format to prompt the terminal to receive a numeric 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."
ANx[,y]
Alpha-Numeric Entry
Use the ANx[,y] format to prompt the terminal to receive an alpha-numeric input. AN specifies an alpha-numeric 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."
Response Parameters
Field
Description
input
Returns the input provided at the terminal. The type and format of the input value depends on the getInput format specified in the request.
A call to the readSignature endpoint sends a prompt to the terminal to capture the cardholder's signature, which is then returned in the response. The readSignature endpoint is supported for terminal devices that support signature capture.
For Ingenico terminals, to include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
signatureFormat
Specifies the signature file format. One of the following values:
BMP (this is the default if the value is omitted)
JPG
PNG
gzipSignature
Determines if the captured signature is compressed using Gzip.
If true, the signature data returned is a JSON-escaped, Base64-encoded, Gzipped, bitmap (BMP) file.
If false, the signature data returned is an uncompressed BMP in base64-encoded.
Defaults to true if not provided.
signatureDimensions
Specifies the custom width and height of the signature image, in the format 'x,y'. The maximum value is 999,999.
signatureImageType
Specifies if the image has a 1-bit color depth (binary) or
24-bit color depth (RGB).
This property defaults to binary (1-bit) for BMP and PNG files. JPG files will always be rgb (24-bit).
Possible values are:
binary - 1-bit; the default for BMP and PNG files.
rgb - 24-bit; the default for JPG files, and optional for PNG files.
cancel
cancel Request Example
HTTP/1.1 200 OK
Content-Type: application/json
X-CardConnect-SessionKey: e3072040eb049990aahgk39937cd6c311c //required for v2
{
"merchantId" : "1234",
"hsn" : "14012PP20131409"
}
cancel Successful Response 200 Example
HTTP/1.1 200 OK
Content-Type: application/json
A call to the cancel endpoint sends a cancel command from the POS software to terminate any in-flight operations.
If you use the cancel command to allow a merchant or cardholder to attempt to cancel a transaction in progress, you should also use the CardPointe Gateway API's InquireByOrderid request to verify the status of the transaction. A transaction cannot be canceled if the terminal service has already initiated the authorization request to the CardPointe Gateway; however, you can use the InquireByOrderid request to check the status of the transaction and void if necessary.
Endpoint URL
The URL for the cancel endpoint is:
https://<site>.cardpointe.com/api/v2/cancel
Request Header
The following key/value pairs are required in the request header.
A call to the readCard endpoint initiates an MSR (magnetic stripe), EMV (chip), or NFC (contactless) payment card interaction and returns a token to be used in a subsequent authorization request to the CardPointe Gateway. The readCard endpoint does not initiate an authorization or capture funds.
To authorize and capture a transaction, call the authCard endpoint.
The dollar amount to be authorized, with two implied decimal places (for example, to specify "$10.00," enter "1000").
includeAmountDisplay
Determines if the transaction amount is displayed to the user during an MSR or EMV (card-present) transaction.
Defaults to true if not provided.
confirmAmount
Determines if the terminal prompts to confirm the the transaction amount prior to prompting to insert/swipe/tap the card.
Defaults to true if not provided.
includeSignature
Determines if the terminal prompts for a signature for devices that support signature capture.
Defaults to true if not provided.
The format of the signature data returned depends on the following parameters.
signatureFormat
One of the following values:
bmp (this is the default if not provided)
jpg
png
gzipSignature
Determines if the captured signature is compressed using Gzip.
If true, the signature data returned is a JSON-escaped, Base64-encoded, Gzipped, bitmap (BMP) file.
If false, the signature data returned is an uncompressed, Base64-encoded BMP file.
Defaults to true if not provided.
signatureDimensions
Specifies the custom width and height of the signature image, in the format 'x,y'. The maximum value is 999,999.
signatureImageType
Specifies if the image has a 1-bit color depth (binary) or 24-bit color depth (RGB).
This property defaults to binary (1-bit) for BMP and PNG files. JPG files will always be rgb (24-bit).
Possible values are:
binary - 1-bit; the default for BMP and PNG files.
rgb - 24-bit; the default for JPG files, and optional for PNG files.
beep
Determines if the terminal beeps to:
Prompt the user to swipe/dip the card.
Prompt the user to remove the card (EMV transactions).
Register key presses during PIN entry for debit transactions.
If true, beep is enabled.
Defaults to false if not provided.
aid
Sets the default EMV application ID, which processes the request as either a PIN debit or a credit transaction.
See Accepting PIN Debit Cards for detailed information on PIN Debit requirements and application workflows.
Note: PIN debit is only supported for qualified merchants boarded on the First Data North and Rapid Connect processing platforms.
Supported values are:
debit - Set to debit for EMV cards with a debit AID to request a PIN.
credit - Set to credit for all other cards. This is the default if no AID is specified.
includePIN
Determines if the user is prompted to enter a PIN after card swipe for MSR (magnetic-stripe) debit cards that support PIN.
See Accepting PIN Debit Cards for detailed information on PIN Debit requirements and application workflows.
Note: PIN debit is only supported for qualified merchants boarded on the First Data North and Rapid Connect processing platforms. Contact Support for more information.
Set this value to true for MSR debit cards, to process the transaction as debit.
Defaults to false if not provided.
Response Parameters
Field
Description
token
The tokenized card data returned by CardSecure.
expiry
The card's expiration date in the format MMYY.
name
The cardholder's name on the card.
The name is not returned if the card or mobile wallet is read through NFC (contactless).
singleUseToken
Specifies if the token is only valid for a single use.
Set to true if the card or mobile wallet is read through NFC (contactless).
signature
The signature captured by the request.
The signature is a JSON-escaped, Base64-encoded, Gzipped, bitmap (BMP) file unless otherwise specified in request.
A call to the readManual endpoint requests manually-keyed card data and returns a token to be used in a subsequent authorization request to the CardPointe Gateway. The readManual endpoint does not initiate an authorization or capture funds. To authorize and capture a transaction, call the authManual endpoint.
A call to the authCard endpoint initiates an MSR (magnetic stripe), EMV (chip), or NFC (contactless) payment card interaction and initiates an authorization request to the CardPointe Gateway.
The Terminal API does not provide the ability to void or inquire on transactions. See the CardPointe Gateway API for information on integrating these features and other advanced capabilities.
Endpoint URL
The URL for the authCard endpoint is:
https://<site>.cardpointe.com/api/v3/authCard
Request Header
The following key/value pairs are required in the request header.
The merchant ID (MID) associated with your terminal's hsn.
The merchantId can be different than the authMerchantId, however both values must belong to the same customer account. See the authMerchantId description, below, for more information.
hsn
Terminal hardware serial number.
amount
The dollar amount to be authorized and captured, with two implied decimal places (for example, enter "1000" to specify "$10.00").
amount can be a positive or negative value. If negative, the transaction is treated as a refund without reference (forced credit).
aid
Sets the default EMV application ID, which processes the request as either a PIN debit or a credit transaction.
See Accepting PIN Debit Cards for detailed information on PIN Debit requirements and application workflows.
Note: PIN debit is only supported for qualified merchants boarded on the First Data North and Rapid Connect processing platforms, and for Ingenico terminals. Contact CardPointe Support for more information.
Supported values are:
debit - Set to debit for EMV cards with a debit AID to request a PIN.
credit - Set to credit for all other cards. This is the default if no AID is specified.
authCode
An authorization code returned by the issuer, when voice authorization is required to complete a transaction.
authMerchantId
This value is only used if you have multiple merchant IDs, and want to process the transaction using a different merchant ID that is not associated with this terminal. The authMerchantId and merchantId must belong to the same customer account.
This setting must be enabled for your merchant account.
Determines if the binInfo object is included in the authorization 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.
Defaults to false if not provided.
beep
Determines if the terminal beeps to:
Prompt the user to swipe/dip the card.
Prompt the user to remove the card (EMV transactions).
Register key presses during PIN entry for debit transactions.
If true, beep is enabled.
Defaults to false if not provided.
capture
Determines whether or not to capture the amount for settlement within the authorization request.
If set to false, the retref or authcode must be captured in a separate request in order for the merchant to receive funding for the transaction.
Defaults to true if not provided.
clearDisplayDelay
Determines the number of milliseconds to wait, after the request completes, before clearing the authorization status from the terminal display and returning to the idle display.
Set to 0 to disable clearing the display after an authCard request.
confirmAmount
Determines if the terminal prompts the user to confirm the transaction amount prior to prompting to insert/swipe/tap the card.
Defaults to true if not provided.
createProfile
Determines whether or not to create a stored profile using the payment data in the request.
If true, initiates a profile create request to the CardPointe Gateway API profile endpoint.
If false, no profile is created. Defaults to false if not provided.
Determines if the captured signature is compressed using Gzip.
If true, the signature data returned is a JSON-escaped, Base64-encoded, Gzipped, bitmap (.bmp) file.
If false, the signature data returned is an uncompressed, Base64-encoded bitmap (.bmp) file.
Defaults to true if not provided.
includeAmountDisplay
Determines if the transaction amount is displayed to the user during a card-present transaction.
Defaults to true if not provided.
Note: This parameter is not supported for Clover terminals. The Clover terminal displays the amount to the user regardless of this parameter.
includeAVS
Determines if the user is prompted to enter the billing zip code for the card.
If true, prompts the user to enter the zip code.
Defaults to false if not provided.
includePIN
Determines if the user is prompted to enter a PIN after card swipe for MSR (magnetic-stripe) debit cards that support PIN.
See Accepting PIN Debit Cards for detailed information on PIN Debit requirements and application workflows.
Note: PIN debit is only supported for qualified merchants boarded on the First Data North and Rapid Connect processing platforms, and for Ingenico terminals. Contact CardPointe Support for more information.
Set this value to true for MSR debit cards, to process the transaction as debit.
Defaults to false if not provided.
includeSignature
Determines if the terminal prompts for a signature for devices that support signature capture.
Defaults to true if not provided.
invoiceId
A unique invoice ID, used for ClientLine reporting. This value is an alphanumeric string with a maximum of 12 characters.
orderId
A unique order ID used to identify the transaction. This value is an alphanumeric string with a maximum of 50 characters. If no order ID is specified in the request, the terminal automatically generates a unique order ID in the format <HSN-timestamp> and amends it to the transaction record.
You can use the order ID to get information on a transaction using the CardPointe Gateway API inquireByOrderid endpoint.
Additionally, when an authorization attempt times out and the terminal service does not receive a response from the CardPointe Gateway, the terminal service uses the order ID to make an inquireByOrderid request to check the status of the transaction. If the transaction status cannot be determined, the terminal service makes three voidByOrderId requests to void the transaction. See Handling Timeouts in the CardPointe Integrated Terminal Developer Guides for more information.
Note: If you include an order ID it must meet the following requirements:
The order ID must be a unique value. Using duplicate order IDs can lead to the wrong transaction being voided in the event of a timeout.
The order ID must not include any portion of a payment account number (PAN), and no portion of the order ID should be mistaken for a PAN. If the order ID passes the Luhn check performed by the CardPointe Gateway, the value will be masked in the database, and attempts to use the order ID in an inquire, void, or refund request will fail.
printDelay
For Clover terminals, specifies the amount of time (in milliseconds) to wait before printing generating and printing a second receipt, when "printExtraReceipt":"true". On average, this process takes approximately 5 seconds (5000 ms), therefore the total amount of time to print a second receipt is equal to the printDelay value + 5000ms.
Valid values range from 0 to 60000 (ms).
Notes:
printDelay is required when "printExtraReceipt":"true"; otherwise, the response returns the following error:
{"errorCode":1,"errorMessage":"printDelay is a required parameter when printExtraReceipt=true"}
If printDelay is set to a value outside of the allowed range, the response returns the following error:
{"errorCode":3,"errorMessage":"'printDelay' value must be between 0 and 60,000"}
printExtraReceipt
For Clover terminals, if true, the terminal prints a second copy of the receipt once the authorization is complete and the initial receipt is printed.
Notes:
Only applicable if printReceipt is true.
If true, the printDelay parameter is also required.
Defaults to false if not provided.
printReceipt
For Clover terminals, specifies whether or not the terminal prints a receipt.
Defaults to false if not provided.
signatureDimensions
Specifies the custom width and height of the signature image, in the format 'x,y'. The maximum value is 999,999.
signatureFormat
Specifies the signature file format. One of the following values:
bmp (this is the default if the value is omitted)
jpg
png
signatureImageType
Specifies if the image has a 1-bit color depth (binary) or
24-bit color depth (RGB).
This property defaults to binary (1-bit) for BMP and PNG files. JPG files will always be rgb (24-bit).
Possible values are:
binary - 1-bit; the default for BMP and PNG files.
rgb - 24-bit; the default for JPG files, and optional for PNG files.
termId
The Terminal Device ID, if required for ClientLine reporting.
If specified, termId must be exactly 8 characters.
userFields
Enables optional userFields to include additional data in the authorization request for future retrieval.
The value of the userFields object is a series of name-value pairs that are meaningful to the merchant.
The userFields object is limited to 4000 bytes total.
Response Parameters
The response includes a subset of the responses available in the CardPointe Gateway Authorization response. Currently, the authCard response includes the following fields:
Field
Comments
token
The token generated for the payment card.
expiry
The payment card expiration date, in MMYY format.
signature
JSON escaped, Base64-encoded, Gzipped, BMP of signature data, if a signature was provided with the payment.
name
The name on card, if present in the track or EMV data.
batchid
The identifier for the batch that the transaction was added to.
retref
The retrieval reference number used to look up and manage the transaction.
avsresp
Alpha-numeric AVS (zip code) verification response code. Note:avsresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account.
respproc
An abbreviation that represents the platform and the processor for the transaction.
amount
The authorized amount. For most transactions, this is the same as the request amount.
For prepaid or gift cards, if partial authorization is enabled for the merchant account, the amount returned is the amount remaining on the card.
For declines, the amount returned is "0.00"
resptext
A text description of the authorization response.
authcode
The Authorization Code from the card issuer.
respcode
An alpha-numeric response code that represents the description of the response
merchid
The merchant ID, copied from the authorization request.
cvvresp
Alpha-numeric CVV (card verification value) verification response code, if returned by the processor.
One of the following values:
M - Valid CVV Match.
N - Invalid CVV.
P - CVV Not Processed.
S - Merchant indicated that the CVV is not present on the card.
U - Card issuer is not certified and/or has not provided Visa encryption keys.
X - No response.
Note:cvvresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account.
respstat
Indicates the status of the authorization request.
One of the following values:
A - Approved
B - Retry
C - Declined
emvTagData
A string of receipt and EMV tag data (when applicable) returned from the processor. Note: This string is returned for both EMV and non-EMV transactions on the First Data Rapid Connect (RPCT) front end platform.
This data returned should be presented on a receipt if applicable, and recorded with the transaction details for future reference.
Returned for contactless (NFC) payments. "tokenexpired":"true" indicates that an NFC payment method was used, and that the token generated is valid only for this authorization.
acctid
The account ID for the stored profile, created if "createProfile":"true" in the request.
profileid
The profile ID for the stored profile, created if "createProfile":"true" in the request.
orderid
The unique order ID for this transaction. Returns the orderid specified in the request, otherwise returns the orderid generated by the terminal, in the format <HSN-timestamp>.
entrymode
Only returned for merchants using the First Data North, First Data Rapid Connect, and Chase Paymentech Tampa processors.
Possible Values:
Keyed
Moto
ECommerce
Recurring
Swipe(Non EMV)
DigitalWallet
EMVContact
Contactless
Fallback to Track
Fallback to Keyed
bintype
Possible Values:
Corp
FSA+Prepaid
GSA+Purchase
Prepaid
Prepaid+Corp
Prepaid+Purchase
Purchase
receiptData
An object that includes additional fields to be printed on a receipt.
The Terminal API does not provide the ability to void or inquire on transactions. See the CardPointe Gateway API for information on integrating these features and other advanced capabilities.
Endpoint URL
The URL for the authManual endpoint is:
https://<site>.cardpointe.com/api/v3/authManual
Request Header
The following key/value pairs are required in the request header.
The merchant ID (MID) associated with your terminal's hsn.
The merchantId can be different than the authMerchantId, however both values must belong to the same customer account. See the authMerchantId description, below, for more information.
hsn
Terminal hardware serial number.
amount
The dollar amount to be authorized and captured, with two implied decimal places (for example, enter "1000" to specify "$10.00").
amount can be a positive or negative value. If negative, the transaction is treated as a refund without reference (forced credit).
authCode
An authorization code returned by the issuer, when voice authorization is required to complete a transaction.
authMerchantId
This value is only used if you have multiple merchant IDs, and want to process the transaction using a different merchant ID that is not associated with this terminal. The authMerchantId and merchantId must belong to the same customer account.
This setting must be enabled for your merchant account.
Determines if the binInfo object is included in the authorization 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.
Defaults to false if not provided.
beep
Determines if the terminal beeps to:
Prompt the user to swipe/dip the card.
Prompt the user to remove the card (EMV transactions).
Register key presses during PIN entry for debit transactions.
If true, beep is enabled.
Defaults to false if not provided.
capture
Determines whether or not to capture the amount for settlement within the authorization request.
If set to false, the retref or authcode must be captured in a separate request in order for the merchant to receive funding for the transaction.
Defaults to true if not provided.
clearDisplayDelay
Determines the number of milliseconds to wait, after the request completes, before clearing the authorization status from the terminal display and returning to the idle display.
Set to 0 to disable clearing the display after an authCard request.
createProfile
Determines whether or not to create a stored profile using the payment data in the request.
If true, initiates a profile create request to the CardPointe Gateway API profile endpoint.
If false, no profile is created. Defaults to false if not provided.
Determines if the captured signature is compressed using Gzip.
If true, the signature data returned is a JSON-escaped, Base64-encoded, Gzipped, bitmap (.bmp) file.
If false, the signature data returned is an uncompressed, Base64-encoded bitmap (.bmp) file.
Defaults to true if not provided.
includeAmountDisplay
Determines if the transaction amount is displayed to the user during a card-present transaction.
Defaults to true if not provided.
Note: This parameter is not supported for Clover terminals. The Clover terminal displays the amount to the user regardless of this parameter.
includeAVS
Determines if the user is prompted to enter the billing zip code for the card.
If true, prompts the user to enter the zip code.
Defaults to false if not provided.
includeCVV
Determines if the user is prompted to enter the card verification value (CVV) for the card.
If true, prompts the user to enter the CVV.
Defaults to false if not provided.
includeSignature
Determines if the terminal prompts for a signature for devices that support signature capture.
Defaults to true if not provided.
invoiceId
A unique invoice ID, used for ClientLine reporting. This value is an alphanumeric string with a maximum of 12 characters.
orderId
A unique order ID used to identify the transaction. This value is an alphanumeric string with a maximum of 50 characters. If no order ID is specified in the request, the terminal automatically generates a unique order ID in the format <HSN-timestamp> and amends it to the transaction record.
You can use the order ID to get information on a transaction using the CardPointe Gateway API inquireByOrderid endpoint.
Additionally, when an authorization attempt times out and the terminal service does not receive a response from the CardPointe Gateway, it uses the order ID to make an inquireByOrderid request to check the status of the transaction. If the transaction status cannot be determined, the terminal service makes three voidByOrderId requests to void the transaction. See Handling Timeouts in the CardPointe Integrated Terminal Developer Guides for more information.
Note: If you include an order ID it must meet the following requirements:
The order ID must be a unique value. Using duplicate order IDs can lead to the wrong transaction being voided in the event of a timeout.
The order ID must not include any portion of a payment account number (PAN), and no portion of the order ID should be mistaken for a PAN. If the order ID passes the Luhn check performed by the CardPointe Gateway, the value will be masked in the database, and attempts to use the order ID in an inquire, void, or refund request will fail.
printDelay
For Clover terminals, specifies the amount of time (in milliseconds) to wait before printing generating and printing a second receipt, when "printExtraReceipt":"true". On average, this process takes approximately 5 seconds (5000 ms), therefore the total amount of time to print a second receipt is equal to the printDelay value + 5000ms.
Valid values range from 0 to 60000 (ms).
Notes:
printDelay is required when "printExtraReceipt":"true"; otherwise, the response returns the following error:
{"errorCode":1,"errorMessage":"printDelay is a required parameter when printExtraReceipt=true"}
If printDelay is set to a value outside of the allowed range, the response returns the following error:
{"errorCode":3,"errorMessage":"'printDelay' value must be between 0 and 60,000"}
printExtraReceipt
For Clover terminals, if true, the terminal prints a second copy of the receipt once the authorization is complete and the initial receipt is printed.
Notes:
Only applicable if printReceipt is true.
If true, the printDelay parameter is also required.
Defaults to false if not provided.
printReceipt
For Clover terminals, specifies whether or not the terminal prints a receipt.
Defaults to false if not provided.
signatureDimensions
Specifies the custom width and height of the signature image, in the format 'x,y'. The maximum value is 999,999.
signatureFormat
Specifies the signature file format. One of the following values:
bmp (this is the default if the value is omitted)
jpg
png
signatureImageType
Specifies if the image has a 1-bit color depth (binary) or
24-bit color depth (RGB).
This property defaults to binary (1-bit) for BMP and PNG files. JPG files will always be rgb (24-bit).
Possible values are:
binary - 1-bit; the default for BMP and PNG files.
rgb - 24-bit; the default for JPG files, and optional for PNG files.
termId
The Terminal Device ID, if required for ClientLine reporting.
If specified, termId must be exactly 8 characters.
userFields
Enables optional userFields to include additional data in the authorization request for future retrieval.
The value of the userFields object is a series of name-value pairs that are meaningful to the merchant.
The userFields object is limited to 4000 bytes total.
Response Parameters
The response includes a subset of the responses available in the CardPointe Gateway Authorization response.Currently, the authManual response includes the following fields:
Field
Comments
token
The token generated for the payment card.
expiry
The payment card expiration date, in MMYY format.
signature
JSON escaped, Base64-encoded, Gzipped, BMP of signature data, if a signature was provided with the payment.
batchid
The identifier for the batch that the transaction was added to.
retref
The retrieval reference number used to look up and manage the transaction.
avsresp
Alpha-numeric AVS (zip code) verification response code. Note:avsresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account.
respproc
An abbreviation that represents the platform and the processor for the transaction.
amount
The authorized amount. For most transactions, this is the same as the request amount.
For prepaid or gift cards, if partial authorization is enabled for the merchant account, the amount returned is the amount remaining on the card.
For declines, the amount returned is "0.00"
resptext
A text description of the authorization response.
authcode
The Authorization Code from the card issuer.
respcode
An alpha-numeric response code that represents the description of the response
merchid
The merchant ID, copied from the authorization request.
S - Merchant indicated that the CVV is not present on the card.
U - Card issuer is not certified and/or has not provided Visa encryption keys.
X - No response.
Note:cvvresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account.
respstat
Indicates the status of the authorization request.
One of the following values:
A - Approved
B - Retry
C - Declined
acctid
The account ID for the stored profile, created if "createProfile":"true" in the request.
profileid
The profile ID for the stored profile, created if "createProfile":"true" in the request.
orderid
The unique order ID for this transaction. Returns the orderid specified in the request, otherwise returns the orderid generated by the terminal, in the format <HSN-timestamp>.
entrymode
Only returned for merchants using the First Data North, First Data Rapid Connect, and Chase Paymentech Tampa processors.
Possible Values:
Keyed
Moto
ECommerce
Recurring
Swipe(Non EMV)
DigitalWallet
EMVContact
Contactless
Fallback to Track
Fallback to Keyed
bintype
Possible Values:
Corp
FSA+Prepaid
GSA+Purchase
Prepaid
Prepaid+Corp
Prepaid+Purchase
Purchase
receiptData
An object that includes additional fields to be printed on a receipt.
The subtotal amount, used as a baseline to calculate tip percentage amounts
Note the following restrictions when specifying the amount:
Amount cannot be null.
Amount must be a numeric value with two implied decimal places (for example, to specify "$10.00," enter "1000").
Amount cannot exceed 2147483647.
hsn
The terminal hardware serial number (HSN).
merchantId
Your merchant ID, required for all requests.
prompt
The text to display to prompt the user to select or enter a tip value.
Note the following restrictions when specifying the prompt:
Ingenico iSC 250 terminals are limited to a maximum of 53 characters on single line.
The prompt text cannot include the word "amount"; however, "Amount" is acceptable. The terminal returns a cancel response if "amount" is present.
For Ingenico terminals, to include a percent sign (%) in the prompt text, you must include two percent signs (%%) in the request. If you include a single percent sign, the terminal will display an unexpected message string.
includeAmountDisplay
Determines if the subtotal (amount) and total (amount + tip) are displayed on the terminal.
Defaults to true if not provided.
includeCustomTipAmount
Determines if a custom tip button is displayed on the terminal. If false, tipPercentPresets is required to provide a range of preset tip percentage values.
Defaults to true if not provided.
tipPercentPresets
An array of three preset tip percentages, in the format [n, n, n] (for example, [10, 15, 20]).
Required if "includeCustomTipAmount:"false".
Note: The ability to set four preset values is planned for a future enhancement.
Response Parameters
Field
Description
amount
The amount provided in the original request.
tip
The calculated tip amount based on the user's selection or input.
total
The calculated total transaction amount (amount + tip).
The order ID for the transaction for which to print a receipt. Note: If multiple transactions are found for the order ID, then the latest transaction with that order ID will be sent to the terminal for printing.
printDelay
Required when "printExtraReceipt":"true". The number of milliseconds to wait after printing the first receipt, before generating and printing the second receipt. On average, this process takes approximately 5 seconds (5000 ms); therefore, the total amount of time to print a second receipt is equal to the printDelay value + 5000ms.
Valid values range from 0 to 60000.
printExtraReceipt
Optional. If true the terminal prints a second copy of the receipt. Use the printDelay parameter to specify the amount of time (in milliseconds) to wait between printing each receipt.
Defaults to false if not specified.
Note: If true, the printDelay parameter is also required in the request, to specify the delay (in milliseconds) between printing the first and second receipts.
If the printer is already printing a receipt when the terminal receives the printReceipt command, the following error is returned:
{"errorCode":7,"errorMessage":"hsn: <hsn> is currently printing"}
Additionally, for the Clover Mini, the terminal must be connected to a power supply to print a receipt. If the terminal is operating on the backup battery when it receives the printReceipt command, the following error is returned:
{
"errorCode": 800,
"errorMessage": "Printing not supported",
"receiptData": {<receiptData>}
}
A 200 response indicates that the request was completed successfully and includes the response body.
400: Bad Request
A 400 response indicates that the request could not be completed due to invalid or missing information in the header or body elements.
a 400 response can include one of the following error codes:
Error Code
Description
3
Generic Error
4
Missing Required Parameter(s)
Error Code 3 is a generic code, which includes an error message that provides specific contextual information for the error, based on the request.
For example, if a the prompt parameter in a call to the readSignature endpoint is greater than 16 characters, the following response is returned:
{ "errorCode" : 3, "errorMessage" : "Prompt text must be less than or equal to 16 characters" }
The following table describes Error Code 3 conditions that can be returned for calls to each endpoint.
Endpoint
Error Message
connect
Incorrect token
dateTime
Text could not be parsed
disconnect
Session key for hsn was not valid
printReceipt
printDelay value must be between 0 and 60000 (miliseconds)
readInput
Invalid format
readSignature
Prompt text must be less than or equal to 16 characters
401: Unauthorized
An HTTP 401 response indicates an authentication error. Authentication errors can occur when the API key is invalid or missing from the Authorization header, the merchant ID is missing from the body or does not match the API key. Authorization errors can also occur due to a terminal configuration error in TMS.
403: Invalid HSN for MerchantID
a 403 response indicates that the request included an HSN value that does not match the specified merchant ID.
500: Client or Server Error
authCard Error Response 500 - Terminal Request Timed Out After Successful Authorization
A 500 response indicates a client or server error. The response includes an error code, which corresponds to one or more specific error messages that describe the error.
In the event that an authorization attempt was successfully initiated before the command sequence timed out or was canceled, the response body returned for errorCode 1 and errorCode 8 include the authorization response data returned from the CardPointe Gateway in an authResponse object.
For example, error code 1 denotes a general client or server error, which can be one of the following:
Terminal not connected to the terminal service (no request queue registered)
Client/Server
7
Terminal in use
Client/Server
8
The in-flight request (for example an authCard command sequence) was canceled. The error includes one of the following messages, which describe the specific cancellation scenario.
Command Cancelled - The client application sent a cancel request.
Operation Cancelled - The cardholder or merchant canceled a readCard sequence at the terminal.
Authorization Cancelled - The client application, merchant, or cardholder attempted to cancel an authCard or authManual request; however, the terminal service already submitted the authorization request to the CardPointe Gateway. In this case, the authorization was processed, and the error includes an authResponse object that contains the authorization response from the CardPointe Gateway.
Client/Server
100
Internal Server Error if no terminals found for merchant
authCard or authManual request including "printReceipt:"true", or printReceipt request, when the Clover Mini is running in low-power mode (not connected to AC power).
Note: This error response also includes the receiptData array for the associated transaction.
