The following guides provide best practices and other supplemental information for integrating the CardConnect Gateway API.

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 CardPointe Gateway API service endpoints.

The CardPointe Gateway API Integration collection also includes a sample Environment to help you get familiar with the API. See Configuring Your Postman Environment, below, for more information.

Click the button below to download the CardPointe Gateway API Integration collection:

Run in Postman

Configuring Your Postman Environment

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 API credentials from CardConnect, you can configure the following variables to auto-fill your merchant-specific data in requests to the CardPointe Gateway API:

  • site - Set this value to the site for the test or production environment, provided by CardConnect.
  • url - The {{url}} variable is used to set the base url (https://{{site}} for the CardPointe Gateway RESTful web services. {{site}} is populated with the value you set for that variable.
  • csurl - The {{csurl}} variable is used to set the url  (https://{{site}} for the CardSecure tokenize REST web service. {{site}} is populated with the value you set for that variable.
  • Authorization - Set this value to the Base64-encoded API credentials 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.

These variables are required in the header and body of most requests. The sample environment includes additional variables that you can configure when testing your integration.

Additionally, the sample collection includes test scripts, which gather specific values (such as token) from the response body, and dynamically update the corresponding environment variable.

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.

Testing Your Integration

This guide provides information to help you develop and test your integrated application. Whether you are developing a new application, or maintaining an existing one, you should incorporate continuous testing in your SDLC.

As CardConnect continues to update and improve the CardPointe Gateway, you should regularly schedule regression testing to ensure that your application utilizes and is compatible with applicable changes to the Gateway.

Understanding the UAT Environment

You use the UAT (user acceptance testing) sandbox environment to test and validate your application. When you begin your application development and integration, you connect to the UAT instance of the CardPointe Gateway.

To connect to the UAT environment, your application uses the following URL:


where <site> is the site name provided to you by CardConnect, and <endpoint> is a CardPointe Gateway service endpoint.

The UAT environment includes emulators that simulate the payment processing activities that occur in production. In this environment, you test with dummy data that is never sent to the payment processor. You should use test card numbers (for example, 4111 1111 1111 1111 or 4444 3333 2222 1111) and physical test cards. 

Data that you transmit to the UAT environment is never sent to the payment processing networks; instead, the CardPointe Gateway communicates with an emulator that simulates the payment processor that your CardConnect Merchant ID (MID) is boarded to. The emulator mimics the behavior of the given processing host, and returns a response similar to what you would receive for a live transaction in the production environment.

Some specific situations, such as a network timeout and specific decline scenarios, require specific input to initiate. See Test Cases, below, for more information on these specific scenarios.

See Gateway Response Codes for a complete list of all possible response codes for the CardPointe Gateway and each processor.

Getting Started

To get started, you'll need to configure your application with the following information:

Depending on your integration, CardConnect may provide a specific test MID, site, and credentials for you to use.

UAT Testing URL

CardConnect provides a sandbox UAT environment for integration testing. Your application can target this environment at

This environment is shared with other merchants, and any data transmitted to this environment may be visible to those merchants.

Never use actual cardholder data in the UAT environment. Ensure that only test data, including test payment cards, is used in this environment.

UAT API Credentials

To authenticate your application, the CardPointe Gateway API uses Basic Authorization. CardConnect provides a username and password, which must be converted into a string (in the format username:password) and encoded into Base64-encoded. Your application must then pass the encoded string in the Authorization header of every request.

To grant access to the production environment, CardConnect provides unique credentials.

To access the UAT sandbox environment use the following credentials:

  • username: testing
  • password: testing123

UAT Merchant ID

A CardConnect merchant ID (MID) is required in all API requests. To use your application to process live transactions, CardConnect will provide a unique production MID.

To develop and test your application, you can use the test MID 496160873888.

Using Test Payment Accounts

When testing in the UAT environment, you must use test cards (either physical cards or test card numbers).

Never use actual cardholder data to test in the UAT environment.

First Data North UAT Test Card Data

The UAT Merchant ID is boarded to the First Data North UAT environment. If you are testing with this MID, you can use the following test card data to test card-not-present transactions.

First Data North UAT Test Card Numbers

You can use the following test card data to test card-not-present payments on the First Data North emulator.

Any card number that meets the following requirements and passes Luhn check validation will return an approval response:

Card BrandPAN PrefixPAN Length
Mastercard51* through 55*16
Amex34* or 37*15
Discover6011*, 622*, 644* through 65*16

First Data North UAT Test Card Numbers for Specific Responses

The following test cards return specific responses on the First Data North emulator:

Test PANresptext Returnedrespstat Returnedrespproc Returnedrespcode Returnedauthcode Returned
4788250000121443 ApprovalA FNOR00PPS009
4387751111111020 Refer to issuerC FNOR01-
4387751111111038 Do not honorC FNOR05-
4387751111111046 Wrong expirationC FNOR54-
4387751111111053 Insufficient fundsC FNORNU-
5454545454545454 ApprovalA FNOR00PPS010
5442981111111023 Refer to issuerC FNOR01-
5442981111111031 Do not honorC FNOR05-
5442981111111049 Wrong expirationC FNOR54-
5442981111111056 Insufficient fundsC FNORNU-
371449635398431 ApprovalA FNOR00PPS013
6011000995500000 ApprovalA FNOR00PPS015
6011000995511122 Refer to issuerC FNOR01-
6011000995511130 Do not honorC FNOR05-
6011000995511148 Wrong expirationC FNOR54-
6011000995511155 Insufficient fundsC FNORNU-
36438999960016 ApprovalA FNOR00PPS012
3528000000000007 ApprovalA FNORPPS007

First Data North Test Zip Codes

You can use the following zip codes on the First Data North UAT emulator to test AVS verification:

Zip CodeCard BrandAVS Response
19406 Visa Y (Address + Zip Match)
19113 Visa Z (Zip Matches, Address Does Not Match)
19111 MasterCard A (Address Matches, Zip Does Not Match)
19112 MasterCard N (Address + Zip Do Not Match)

Any zip code value returns an AVS response of Z (Zip Matches, Address Does Not Match).

First Data North Test CVV Numbers

You can use the following test CVV numbers on the First Data North Emulator to test CVV verification:

CVV ValueCVV Response
112 M (Match)
111 N (No Match)
222 P (Not Processed)
333 U (Unknown)

Physical Test Cards

Physical test cards allow you to test card-present payments.

You can obtain a complete set of EMV test cards from B2 Payment Solutions at the following URL:

Test Cases

The following topics provide information for testing specific features to obtain responses that are otherwise not returned in the UAT environment.

Testing with Amount-Driven Response Codes

This feature is only available for the First Data Rapid Connect (RPCT) emulator.

When testing your CardPointe Gateway or Bolt integration in the UAT environment, you can use amount-driven response codes to emulate processor-specific authorization responses that you might encounter in the production environment. This allows you to receive and handle response codes that you would not otherwise encounter in your test environment.

All response codes returned in the production environment are received directly from the processor.

To return a specific response code, you make an authorization request with an amount in the $1000-$1999 range. You specify the desired response code using the last three digits of the whole-dollar amount (the amount excluding cents). For example, if you want to return RPCT respcode 332, "Account locked," make an authorization request for $1332.

The following example illustrates an authorization request for $1116.95. The amount value specified is 111695 (with the decimal implied), therefore, the whole-dollar amount is $1116.

The response includes the RPCT respcode 116, which indicates that the transaction was declined due to insufficient funds.

Testing CardPointe Gateway Timeouts

This feature is only available for the First Data Rapid Connect (RPCT) and First Data North (FNOR) emulators.

Because the UAT environment does not communicate with the processing hosts, your application can not encounter a time out scenario. In production, when the CardPointe Gateway communication with the processor times out, the Gateway returns an auth response object that includes "respcode":"62" and "resptext":"Timed out"

If you want to test your application's ability to handle a time out response, you can send an auth request using one of the following test card numbers:

  • Visa: 4999006200620062
  • MC: 5111006200620062
  • Discover: 6465006200620062

You can also tokenize the card number and use the token in the auth request.

The response includes the PPS respcode 62, which indicates that the transaction was declined due to a communication timeout between the CardPointe Gateway and processor host.

Processing ACH Payments

This guide provides guidance for accepting Automated Clearing House (ACH) payments using the CardPointe Gateway API. ACH payments, also called e-check payments, are a common payment method for recurring payments as well as telephone and mail orders.

Unlike credit card payments, when a customer authorizes an ACH payment, the funds are withdrawn directly from his or her bank account. This process can take several days, so you should include a monitoring process in your integration to verify the status of the transaction.

To accept ACH payments, you must capture and handle the customer's bank account and routing number. While you can capture this information and pass it directly to the CardPointe Gateway in an authorization request, it is a best practice to instead capture this information and tokenize it using a CardSecure-integrated web form.

Using a Web Form to Gather and Tokenize ACH Payment Data

To ensure the security of your customers' data, as well as your PCI compliance, it is recommended that you use a customer-facing web form, integrated with CardSecure, to capture and tokenize bank account and routing information.

When using a web form to capture and tokenize customer bank account information, include separate fields for the routing number and account number. Send these fields in a CardSecure tokenization request in the format
"account" : "<routing number>/<account number>"

For example:

"account" : "123456789/1234123412341234"

CardSecure returns a token representing the ACH account information, which you can then use to make an authorization request to the CardPointe Gateway.

Making an ACH Authorization Request

To process an ACH payment, you make an authorization request using the CardPointe Gateway API. In addition to the fields required for all authorization requests, you must include the following information:

Payment InformationAuthorization Request ParameterDescription
Account and Routing Numbersaccount and bankabaIf you gathered and tokenized the customer's bank account and routing information using a CardSecure-integrated web form, then you can pass the token in the account field.

If you are handling the clear account number and routing number, then include them in the account and bankaba fields, respectively.
Payment OriginecomindInclude one of the following values:
  • "ecomind" : "T" for a telephone or mail order
  • "ecomind" : "R" for a recurring payment
  • "ecomind" : "E" for an eCommerce or Internet order
Account TypeaccttypeInclude one of the following values:
  • "accttype" : "ECHK" for a checking account
  • "accttype" : "ESAV" for a savings account
SSN (Last 4)ssnl4If the payment processor supports or requires ACH account verification, you can include the last four digits of the customer's Social Security Number in the ssnl4 field.
Driver's LicenselicenseIf the payment processor supports or requires ACH account verification, you can include the customer's driver's license information in the license field.

Use the format <2-char state>:<license number>.

For example "license" : "NY:12JKHQ123"

The following example illustrates an ACH authorization request and response:

Verifying ACH Transactions

ACH transactions typically take several business days to process and settle, therefore, it is a best practice to periodically check the status of the transaction to ensure that it is successfully processed and that you are credited for the authorized amount.

You can use the CardSecure Gateway API to programmatically verify the transaction status using the inquire and funding service endpoints.

Using the Inquire Endpoint

The inquire endpoint provides information on completed authorizations.

You can use the inquire endpoint if you have the retrieval reference number (retref) from the authorization response. If you don't have the retref, but you included a unique order ID in the authorization request, then you can use the inquireByOrderId endpoint instead.

The inquire response includes a settlement status (setlstat) field that displays the settlement status of the transaction. Note that the settlement status initially displays "Queued for Capture" for ACH transactions, and the value is updated once the batch is transmitted. If "setlstat" : "rejected" you can use the funding endpoint to gather more detailed information.

Using the Funding Endpoint

The funding endpoint provides additional useful information for ACH transactions. Specifically, you can use the funding endpoint to retrieve an ACH return code (achreturncode), which provides additional information for rejected ACH transactions.

To use the funding endpoint, you make a request using the merchant ID and the date of the funding event that included the transaction. The funding endpoint returns an array of transaction details for that date.

Use the retref for the ACH transaction to locate it in the txns node of the response data. For ACH transactions, the response includes an achreturncode field that includes a specific code that explains the reason for the rejection.

The following table describes the possible ACH return code values.

ACH Return Codes

The following codes are returned when an ACH transaction is rejected. 



Insufficient funds

Available balance is not sufficient to cover the amount of the debit entry


Bank account closed

Previously active amount has been closed by the customer of RDFI


No bank account/unable to locate account

Account number does not correspond to the individual identified in the entry, or the account number designated is not an open account


Invalid bank account number

Account number structure is not valid


Returned per ODFI request

ODFI requested the RDFI to return the entry


Authorization revoked by customer

Receiver has revoked authorization


Payment stopped

Receiver of a recurring debit has stopped payment of an entry


Uncollected funds

Collected funds are not sufficient for payment of the debit entry


Customer advises not authorized

Receiver has advised RDFI that originator is not authorized to debit his bank account


Check truncation entry return

To be used when returning a check truncation entry


Branch sold to another RDFI

RDFI unable to post entry destined for a bank account maintained at a branch sold to another financial institution


RDFI not qualified to participate

Financial institution does not receive commercial ACH entries


Representative payee deceased or unable to continue in that capacity

The representative payee authorized to accept entries on behalf of a beneficiary is either deceased or unable to continue in that capacity


Beneficiary or bank account holder

(Other than representative payee) deceased* - (1) the beneficiary entitled to payments is deceased or (2) the bank account holder other than a representative payee is deceased


Bank account frozen

Funds in bank account are unavailable due to action by RDFI or legal order


File record edit criteria

Fields rejected by RDFI processing (identified in return addenda)


Improper effective entry date

Entries have been presented prior to the first available processing window for the effective date.


Amount field error

Improper formatting of the amount field


Non-payment bank account

Entry destined for non-payment bank account defined by reg.


Invalid company ID number

The company ID information not valid (normally CIE entries)


Invalid individual ID number

Individual id used by receiver is incorrect (CIE entries)


Credit entry refused by receiver

Receiver returned entry because minimum or exact amount not remitted, bank account is subject to litigation, or payment represents an overpayment, originator is not known to receiver or receiver has not authorized this credit entry to this bank account


Duplicate entry

RDFI has received a duplicate entry


Addenda error

Improper formatting of the addenda record information


Mandatory field error

Improper information in one of the mandatory fields


Trace number error

Original entry trace number is not valid for return entry; or addenda trace numbers do not correspond with entry detail record


Transit routing number check digit error

Check digit for the transit routing number is incorrect


Corporate customer advises not authorized

RDFI has bee notified by corporate receiver that debit entry of originator is not authorized


RDFI not participant in check truncation program

Financial institution not participating in automated check safekeeping application


Permissible return entry (CCD and CTX only)

RDFI has been notified by the ODFI that it agrees to accept a CCD or CTX return entry


RDFI non-settlement

RDFI is not able to settle the entry


Return of XCK entry

RDFI determines at its sole discretion to return an XCK entry; an XCK return entry may be initiated by midnight of the sixtieth day following the settlement date if the XCK entry


Limited participation RDFI

RDFI participation has been limited by a federal or state supervisor


Return of improper debit entry

ACH debit not permitted for use with the CIE standard entry class code (except for reversals)

Testing ACH Authorizations

To test ACH authorizations, you can use the test Merchant ID (MID) 496160873888 in the CardPointe Gateway's UAT environment. This MID uses a routing rule to detect when "accttype" : "ECHK" and then routes ACH transactions through a separate, linked MID, 542041.

This configuration allows you to dedicate separate merchant accounts to processing credit/debit and ACH transactions, which can be helpful for testing and reporting purposes. Contact Support if you want to configure a dedicated MID for processing ACH transactions.

To test ACH transactions, you must use a valid ABA routing number (for example, 036001808 or 011401533); however any account number is accepted. 

If you test with an invalid routing number, the response returns a resptext of "The RoutingNumber (<bankaba>) is not a valid routing number."

Scheduling Recurring Payments

This guide provides information for extending your existing CardPointe Gateway API integration to add recurring billing to your payment methods.

To do this, you can use an application scheduler, like Cron, to create a schedule to run recurring transactions. The scheduled job can initiate an authorization request to the CardPointe Gateway using tokenized payment data or a stored profile.

This method gives you complete control over your recurring payment schedule with a simple API integration.

It is a violation of PCI DSS standards to store Card Verification Value (CVV) data. Neither CardConnect nor the merchant can store this data for the purpose of recurring billing.

How it Works

The following process provides a general overview of the steps required to set up a recurring payment schedule using the CardPointe Gateway. depending on your integration and business needs, your procedure may vary.

  1. Tokenize the customer's payment data.

    Depending on your existing integration, there are several ways to tokenize payment data.

    For example, you can:
    • Use the customer’s clear PAN or ACH payment data to make a CardPointe Gateway API authorization request. Include "tokenize" : "y" to retrieve a token in the response.

      Optionally, do the following: 

      • Include ”capture” : “y” to accept an initial payment.
      • include ”profile” : “y” to store the customer’s data in a profile to use in future requests.
    • Gather and tokenize the payment card data using the Hosted iFrame Tokenizer.
    • Use a Bolt terminal and the Bolt P2PE API readCard or readManual service endpoint.
  2. Store the token for reuse.

    You can either store tokens and customer data in your own database, or you can use the CardPointe Gateway API’s profile service endpoint to create and store customer profiles in CardConnect’s secure vault. You can skip this step if you created a profile in step 1.
  3. Gather your billing requirements.

    Determine the start date and length of the billing plan, the payment amount and frequency, and any additional information that you'll need to include in your requests.
  4. Build your Cron job to schedule authorization requests to the CardPointe Gateway API.

Authorization requests for recurring billing payments must include "ecomind" : "R" to flag these authorizations as recurring billing. If this parameter is not set, recurring payments will be declined.

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.

FieldContentMax LengthComments
respstatStatus1Indicates the status of the authorization request. Can be one of the following values:
  • A - Approved
  • B - Retry
  • C - Declined
retrefRetrieval reference number12CardConnect retrieval reference number from authorization response
accountAccount number19Copied from the authorization request, masked except for the last four digits.
token (if requested)Token19A token that replaces the card number in capture and settlement requests if requested
amountAmount12Authorized 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.
batchidBatch ID12Automatically created and assigned unless otherwise specified. Returned for a successful authorization with capture.
orderidOrder ID19Order ID copied from the authorization request.
merchidMerchant ID12Copied from the authorization request.
Note: If you include the merchant ID on a receipt, mask this value, except the last four digits.
respcodeResponse code- Alpha-numeric response code that represents the description of the response
resptextResponse text-Text description of response
respprocResponse 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
entrymodePOS Entry Mode25Only returned for merchants using the First Data North and RapidConnect front end platforms.
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.
emvTagDataEMV tag data2000A string of receipt and EMV tag data (when applicable) returned from the processor.

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.
receiptreceipt 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.

Returns "unknown" if the signature requirement could not be determined.
ModeIdentifies 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
Network LabelIdentifies the Authorizing Network Name, which should be printed on the receipt.IssuerString10
IAD (Issuer Application Data)9F10Contains proprietary application data for transmission to the issuer in an online transaction.Cardbinary0-32
Entry methodIndicator 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:

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 for assistance configuring the receipt printing properties for your merchant account.

A successful authorization response includes a receipt object with the following fields:

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).

Handling Timed-out Transactions

This guide provides best practices for handling CardPointe Gateway API timeout errors. The Gateway API supports synchronous communication; therefore, your application must make requests and expect responses in sync with the CardPointe Gateway services.

If you are a developer integrating your point-of-sale software with the CardPointe Gateway API, 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 information should guide you on how long to wait for a response, and actions to take if one is not returned.

CardPointe Gateway Authorization Timeout (32 Seconds)

When you use the CardPointe Gateway API's auth endpoint, to make an authorization request, the Gateway sends the request to the payment processing network and allows 31 seconds for a response. If the Gateway does not receive a response, then the request times out at the 32 second mark and returns a "Timed Out" response.

Handling CardPointe Gateway Timeouts

Whether your application is using the Bolt API authCard request, or the CardPointe Gateway API auth request, it should be designed to handle the following scenarios:

  1. A "Timed out" response returned successfully (HTTP 200) from the CardPointe Gateway auth endpoint or the Bolt API authCard endpoint.
  2. No response returned successfully from the CardPointe Gateway auth endpoint.

In this case, a response, including a retref for the transaction, is returned. The response includes "respstat": "B" which always means "Retry." The transaction attempt should be tried again.

If you need to reference the details of any particular transaction attempt, supply valid retref and merchid values in an inquire request.

Unfortunately, CardConnect can not guarantee that a retry will work. In the event of multiple retry failures, visit to see if there are system-wide issues.

No Response Returned

This scenario may include, but is not limited to, an HTTP Status 408 Request Timeout.

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

As a safeguard against losing record of the transaction attempt from your system, it is strongly recommended that you supply a unique order ID for every authorization request made to the API.

If you included an order ID in the original authorization request, then you can use the following Gateway API service endpoints to inquire on or void the transaction record:

  • inquireByOrderid

    The inquireByOrderid endpoint is used to look up a transaction record using the order ID supplied in the original authorization request. If the supplied order ID is found, then the same payload returned in the inquire response is provided.

    If the request is successful, the response includes the transaction details, including the retref. You can then use the retref to make a subsequent void or capture call.

  • voidByOrderId

    The voidByOrderId endpoint is used to look up and void a transaction record using the order ID supplied in the original authorization request. If the supplied order ID matches a transaction record, the authorization is voided and a void response is returned. See the voidByOrderId description for more information.

    voidByOrderId should be used in the event that no response is returned by an inquireByOrderId request, or if no look up is required at all.

    Note: You should attempt the voidByOrderid request three times (3x) to ensure that the transaction is voided, despite not receiving a response to indicate that the request was successful.

See the CardPointe Gateway API Developer Documentation for information on the inquireByOrderid, voidByOrderId, and capture service endpoints.

Manually Managing Gateway Batches

This guide provides information for using the CardPointe Gateway API's openBatch and closeBatch service endpoints to manually open and close Gateway batches. 

The CardPointe Gateway automatically manages transaction batches.

Exercise caution when managing batches manually. It is possible to group unrelated batches by mistakenly using the same batchsource; therefore it is a best practice to use unique batch source values, and to develop a system for categorizing grouped transactions accurately.

Using the openBatch Endpoint

A call to the openBatch service endpoint opens a new batch associated with the supplied merchid. The batchsource is used to supply a batch identifier to logically link multiple CardConnect batches together across merchant IDs. A CardConnect batch contains one merchid.

Exercise caution when specifying a batchsource value. CardConnect does not validate or use the value and it is possible for more batches to be grouped if the same batchsource is used by mistake; therefore it is a best practice to use unique batch source values, and to develop a system for categorizing grouped transactions accurately.

Additionally, the batchsource value in an openBatch request must match the batchsource value in the authorization or capture request for the transaction that you want to include in the created batch.

The REST verb GET is used for this service, which returns a JSON response containing the batchid for a new open batch.

openBatch URL

GEThttps://<site><merchid>/<batchsource>Authorization: Basic

openBatch Request

Fields in bold are required.

merchidANThe CardConnect merchant ID, required in every request.
batchsourceANReferences the batchid of a third-party system. A CardConnect batch contains one merchant ID. Use caution when attempting to use batchsource to link batches together. CardConnect does not validate the value and it is possible for more batches to be grouped if the same batchsource is used accidentally. A batchsource sent in openBatch must match that sent in the Capture service.

openBatch Response

Example openBatch Response

{"batchid":"2628", "respcode":"success"}

batchidANThe batch ID for the new batch, if the request was successful. If the value "null" is returned, the request was not successfully processed.
respcodeANIndicates whether the request succeeded or failed. If the batch is successfully opened, the value "success" is returned. If the request failed, the value "noBatch" is returned.

Using the closeBatch Endpoint

A call to the closeBatch service endpoint attempts to close the batch identified by the merchid and batchid. Provide a batchid to attempt to close a specific batch. If no batchid is supplied, the open batch with the lowest batchid is closed.

The REST verb GET is used for this service, which returns an authorization response.

closeBatch URL

GEThttps://<site><merchid>/<batchid>Authorization: Basic

closeBatch Request

Fields in bold are required.

merchidANThe CardConnect merchant ID associated with the batch that you want to close.
batchidANThe batch ID for the batch that you want to close. If no batch ID is specified, the batch with the lowest batch ID number is closed.

closeBatch Response

Example closeBatch Response

{"batchid": "2568",  "respcode":"success"}
batchidANThe batch ID of the closed batch. If the value "null" is returned, the request was not successfully processed.
respcodeANIndicates whether the request succeeded or failed.

If the batch is successfully closed, the value "success" is returned. If the request failed, the value "noBatch" is returned. This may mean the request batch does not exist or is already closed.

Using the Batch Authorization Service to Process Batch Files

This guide provides information for using CardConnect's Batch Authorization Service (BAS) to submit batch files for authorization processing. BAS is a component of CardConnect's Secure Exchange SFTP product. 

The request file submitted to BAS will contain all required data elements within an Authorization Request to the CardPointe Gateway. BAS collects the supplied data and submits all requests on behalf of the client. A response file is returned, containing data from the associated Authorization Response.

Using BAS to transmit batch files is not a drag-and-drop solution. Integrating BAS requires development work and testing.

Client Onboarding Checklist

  1. Obtain the CardConnect pgp public key. Clients must encrypt all request files using this key.
  2. Send your client pgp public key to CardConnect. CardConnect encrypts response files using your key.
  3. Obtain SFTP credentials from CardConnect. You use these to submit requests and poll for response files.
  4. Obtain your CardConnect Gateway API URL and credentials from CardConnect.

Supported Authorization Types

The Batch Authorization Service supports all data elements that the CardPointe Gateway Authorization Service supports.

Authorization TypeDetails
'capture' column set to 'N'
Authorization with Capture
'capture' column set to 'Y'
Refund without Reference
'amount' column set to a negative value
The merchant account must be configured to support this transaction type.

PGP Keys

All files that are submitted to or retrieved from Secure Exchange must be PGP encrypted. This requires two PGP key pairs:

  • Request keypair - CardConnect holds the private key and you download the public key. You must use this key to encrypt all BAS request files before uploading them to Secure Exchange.
  • Response keypair - You hold the private key and send the public key to CardConnect. CardConnect uses your key to encrypt all BAS response files before uploading them to Secure Exchange.

Click below to download the CardConnect public PGP keys for the UAT and Prod environments:

Note that these keys are "armored." Run the "gpg --dearmor" command to de-armor the keys.

For example:

$ gpg --dearmor < secureexhange_uat.txt > secureexchange_uat.gpg

BAS Request File Specifications

CardConnect Tokens

The value within each record's account field must be a valid CardConnect token. BAS does not handle clear-text card numbers.

If your integration does not yet support CardConnect tokens, contact

BAS Request File Name


Sample BAS Request File

merchid,orderid,accttype,account,expiry,amount,capture,currency,email,name,address,address2,city,region,country,postal,phone,company,ssnl4,taxexempt,items,invoiceid,ponumber,shiptozip,shipfromzip,shiptocountry,orderdate,taxamnt,frtamnt,dutyamnt,discamnt,waiver,fee_value,fee_format,gsacard081800000001,1000102424,VISA,9404077753845057,1299,100,Y,USD,,name1,add1,add2,city1,,US,19020,,,,Y,"unitcost='1.00',description='desc with no comma',uom='lb'|unitcost='1.00',description='desc with,comma',uom='lb'",,,,,,,,,,,Y,,,Y081800000001,1000102425,VISA,9404077753845057,1299,100,N,USD,,name1,add1,add2,,,,19020,111-111-11111,,,,"unitcost='1.00',description='desc with no comma',uom='lb'",,,,,,,,,,,,,,081800000001,1000102426,VISA,9404077753845057,1299,100,N,USD,,,add1,,city1,,US,19020,,,,,"unitcost='1.00',description='desc with no comma',uom='lb'|unitcost='1.00',description='desc with,comma',uom='lb'",,,,,,,,,,,,,,081800000001,1000102427,VISA,9404077753845057,1299,100,Y,USD,,name1,,add2,,,US,19020,111-111-11111,,,N,,,,,,,,,,,,,,,

BAS Request Fields

Fields in bold are required.

Fields with a # indicate these fields can be used as part of a profile. See the CardPointe Gateway API Profile description for more information.

orderid19ANSource system order number.

Populate this field with a unique value that can identify the sales order.

This value will be associated with the response record.
merchid12NCardConnect Merchant ID (MID), required for all requests
amount12NAmount with decimal or without decimal in currency minor units (for example, USD Pennies or EUR Cents),

This value identifies the authorization type:
  • Positive - Authorization request
  • Zero - Account Verification request. See AVS and CVV settings to enable. Account Verification is not available for ECHK transaction types.
  • Negative - Refund without reference (Forced Credit). Merchants must be enabled for forced credit. When referencing an existing authorization, use Refund.
currency3ANCurrency of merchant settlement
(USD for US dollars, CAD for Canadian Dollars, etc.)
expiry#4NCard Expiration in either MMYY or YYYYMMDD format, not required for ECHK.

CardSecure Token - Retrieved from the Bolt API, CardSecure API, or the Hosted iFrame Tokenizer.

The token can be generated from from either credit card or ACH (banking/routing number) data. If ACH, the merchid must be a specific Profit Stars Merchant ID.

Note: To use a CardConnect profile, omit the account field and supply the profileid. See the CardPointe Gateway API Profile description for more information.

profile1 or 16ANOptional, Y to create an account profile upon initial authorization.

Creating a profile generates a 20-digit numeric profileid / acctid (optional) value to use in authorizations when the account field is omitted. See the CardPointe Gateway API Profile description for more information.
acctid3NAccount identifier within a profile, specifies unique token
capture1AOptional, Y to capture the transaction for settlement if approved.
signature6144ANJSON-escaped, Base64-encoded, Gzipped, BMP of signature data.

If the authorization is using a token with associated signature data, then the signature from the token is used.
cvv24NCVV2/CVC/CID value
name#30ANAccount name

Optional for credit cards but required for electronic checks.
address#30ANAccount street address (required for AVS)
city#30ANAccount city
postal#9ANAccount postal code, defaults to "99999".

If country is "US", must be 5 or 9 digits; otherwise, any alphanumeric string is accepted.
region#20ANUS State, Mexican State, Canadian Province
country#2ANAccount country (2 character country code), defaults to "US."

Required for all non-US addresses.
phone#15ANAccount phone
email#30ANE-Mail address of the account holder
authcode6ANAuthorization code from original authorization (VoiceAuth).

For Voice/Capture-Only, include valid authcode.
taxexempt1AIf taxexempt is set to No for the transaction and a tax is not passed, the default configuration data is used.

If taxexempt is set to Yes, the default tax rate is used.
termid30ANTerminal Device ID
accttype#6AOne of PPAL, PAID, GIFT, PDEBIT, otherwise not required.
ecomind1AIdentifies the payment origin. Options are:
  • T - telephone or mail
  • R - recurring
  • E - ecommerce/Internet
invoiceid12ANInvoice ID, optional.

Defaults to orderid from authorization request
userfields4000 Bytes
ANThe userfields object, or array, is a series of name-value pairs that are meaningful to the merchant.

See the CardPointe Gateway API User Fields description for more information.

Example of userfields value:

"{""UDF1"": ""SomeText"", ""UDF2"": ""SomeMoreText""}"

Capture Level 2 Data

If available, the Level 2 fields can be provided in the capture request and should be provided for corporate or purchase cards to qualify for improved interchange rates.

ponumber36ANCustomer purchase order number
taxamnt12NTax amount either decimal or in currency minor units (i.e. USD Pennies, MXN Centavos), taxamnt of zero indicates tax-exempt purchaser

Note: Do not send a non-zero tax amount for a tax exempt order.

Many Level 2 protocols refer to a "Customer Code" described as "an identifier the customer would recognize". CardConnect populates this field with the ponumber. If the ponumber is not provided, then the orderid from the authorization request is used. If neither the ponumber or the orderid is available, the CardConnect-assigned Retrieval Reference Number (retref) is used.

The Level 2 protocol also requires certain fields about the merchant, such as Postal Code and Tax Identification Number. These fields are filled from the configuration table created during the merchant boarding process.

Capture Level 3 Data

If available, Level 3 line item data can be sent with the capture request, particularly for commercial or corporate payment cards. To qualify for Level 3 Interchange rates, Level 2 data (described above) must also be provided.

Level 3 data includes additional Order Level items such as freight and discount amount, as well as information from each line item of the order. These are stored as an array in the items field.

frtamnt12NTotal order freight amount, default 0
dutyamnt12NTotal order duty amount, default 0

For most industries this is the delivery date for the order

Defaults to System Date when captured
shiptozip12ANIf country is "US", must be 5 or 9 digits

Otherwise, any alphanumeric string is accepted
shipfromzip12ANSame as above
shiptocountry2AShip To Country Code, default is US
ItemsvariesArrayArray of Items

Items Field for BAS

  • The Items field must be enclosed in double quotation marks (").
  • Each item must be separated by a pipe delimiter (|).
  • Elements in each item must be a key=value pair.
  • Elements in each item must be separated by a comma (,).
  • Each value must be enclosed in single quotation marks (').
  • Values containing a single quote (') must be escaped with a backslash (\).

    For example:
description='desc with a single quote\''
  • Values containing a comma (,) must also be enclosed in double quotation marks (").

    For example:
"unitcost='1.00',description='desc with no comma',uom='lb'|unitcost='1.00',description='desc with,comma',uom='lb'"

Line Item Records

lineno4NOptional line number for each item. Line numbers do not need to be specified sequentially; however, if no lineno value is included, items are assigned sequential line numbers.
material12ANOptional material code (also referred to as a Commodity Code) for each item.
description26ANAn item description, required.
upc14NOptional UPC code for each item. If upc is included, the value must not be all zeros.

Some processors limit this value to 12 characters.
quantity12NQuantity of the item purchased. Can be a whole amount or amount with up to three decimal places.
uom8ANUnit of measure (for example, "each" or "ton").

Some processors limit this value to 4 characters.
unitcost12NOptional item cost, excluding tax as a decimal amount or in currency minor units (for example, USD Pennies or MXN Centavos formatted as 1.23 or 123 for $1.23).

When omitted, this value is calculated as netamnt/quantity.
netamnt12NNet total of unitcost x quantity, excluding tax and discount, as a decimal amount or in currency minor units.

netamnt is always a positive value, even for refunds.

Zero amounts are allowed for no-charge items, such as a manual, that are included in the order.
taxamnt12NTax amount for each item, as a decimal amount or in currency minor units. The sum total of taxamnt for all items equals the total tax amount for the order.

The total of netamnt + taxamnt - discamnt equals the order amount.

taxamnt must be zero or omitted if taxexempt is N and non-zero if taxexempt is Y.
taxexempt1true/falseIndicates whether or not the order is tax exempt.

taxexempt should be true if:
  • The payment card BIN type is GSA (government).

    Note: All GSA orders are set to taxexempt regardless of this setting.
  • The merchant is a government agency.

    In this case, you must include taxexempt = true in the request for each order.
taxexempt defaults to false.
discamnt12NOptional discount amount for each item, as a decimal amount or in currency minor units.

BAS Response File Specifications

BAS response files are pgp-encrypted with the key that you provided to CardConnect.
Response files will return one Gateway response per line.

BAS Response File Name

The response file name matches the corresponding request file name with the extension ".done" appended.

For example:


    Sample BAS Response File

    id,status,message,orderid,retref,amount,resptext,commcard,cvvresp,batchid,avsresp,respcode,merchid,token,authcode,respproc,respstat,account1,DONE,,1000102424,2345676543,2.00,Approval,C ,P,543,A,00,081800000001,9404077753845057,PPS001,FNOR,A,94040777538450572,DONE,,1000102425,2345676543,3.00,Approval,C ,P,543,A,00,081800000001,9404077753845057,PPS001,FNOR,A,94040777538450573,ERROR,401 Un-Authorized,10001024264,DONE,,1000102427,2345676543,4.00,Declined,C ,P,543,U,00,081800000001,9404077753845057,PPS063,FNOR,C,94040777538450575,LOAD_ERROR,IOException reading next record: (line 2) invalid char between encapsulated token and delimiter

    BAS Response File Fields

    FieldContentMax LenComments
    idInteger20BAS transaction ID
    10Final processing status: "DONE" or "ERROR"
    messageStringNoneDetails explaining "ERROR" or "LOAD_ERROR"
    orderidOrder ID19The orderid specified in the Request file
    retrefRetrieval reference number12CardConnect retrieval reference number from authorization response
    amountAmount12Authorized 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.
    resptextResponse text-Text description of response
    commcardCommercial card flag1Y if a Corporate or Purchase Card
    cvvrespCVV response code1Alpha-numeric CVV response.
    batchidBatch ID10Automatically created and assigned unless otherwise specified
    avsrespAVS response code2Alpha-numeric AVS response.
    respcodeResponse code-Alpha-numeric response code that represents the description of the response
    merchidMerchant ID12Copied from request
    token (if requested)Token19A token that replaces the card number in capture and settlement requests if requested
    authcodeAuthorization code6Authorization Code from the Issuer
    respprocResponse processor4Abbreviation that represents the platform and the processor for the transaction
    respstatStatus1A - Approved
    B - Retry
    C - Declined
    accountAccount number19Copied from request, masked

    Submitting a Batch File

    You submit request files and retrieve response files using Secure Exchange, via SFTP. When you log in to Secure Exchange you have access to three directories: /request, /response, and /dlc (dead-letter channel).

    The following procedure describes each folder's purpose:

    1. You upload an encrypted request file into the /request directory.

      BAS decrypts the file and runs authorization requests, logging each response in a new response file.
    2. You poll the server for encrypted responses files in the /response directory.
    3. If an error occurs when attempting to decrypt the pgp file, the encrypted request file is placed in the /dlc directory.

      Contact Support
      if you encounter this scenario.

    Viewing Batch File Transactions in CardPointe

    To view reporting details for processed batches in CardPointe, 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. Click the Front End column header and select SecureExchange to display the transactions processed by BAS.

    See the CardPointe Web App support page for more information on using CardPointe.