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 host site for the test or production environment, provided by CardConnect.
  • port - Set this value to the port number for the test or production environment, provided by CardConnect.
  • url - The {{url}} variable is used to set the base url (https://{{site}}.cardconnect.com:{{port}}/cardconnect/rest/) for the CardPointe Gateway REST web services. {{site}} and {{port}} are populated with the values you set for those variables.
  • csurl - The {{csurl}} variable is used to set the url  https://{{site}}.cardconnect.com:{{port}}/cardsecure/api/v1/ccn/tokenize for the CardSecure tokenize REST web service. {{site}} and {{port}} are populated with the values you set for those variables.
  • 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.

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
data=<routing number>/<account number>.

For example, https://<host>.cardconnect.com:<port>/cardsecure/cs?action=CE&data=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 bankaba If 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 OriginecomindEnter one of the following values:
  • "ecomind" : "T" for telephone or mail order
  • "ecomind" : "R" for recurring payment
  • "ecomind" : "E" for eCommerce or Internet order
Account TypeaccttypeInclude "accttype" : "ECHK" to specify that the payment account type is ACH.
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. 

CodeDescriptionDetails

R01

Insufficient funds

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

R02

Bank account closed

Previously active amount has been closed by the customer of RDFI

R03

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

R04

Invalid bank account number

Account number structure is not valid

R06

Returned per ODFI request

ODFI requested the RDFI to return the entry

R07

Authorization revoked by customer

Receiver has revoked authorization

R08

Payment stopped

Receiver of a recurring debit has stopped payment of an entry

R09

Uncollected funds

Collected funds are not sufficient for payment of the debit entry

R10

Customer advises not authorized

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

R11

Check truncation entry return

To be used when returning a check truncation entry

R12

Branch sold to another RDFI

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

R13

RDFI not qualified to participate

Financial institution does not receive commercial ACH entries

R14

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

R15

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

R16

Bank account frozen

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

R17

File record edit criteria

Fields rejected by RDFI processing (identified in return addenda)

R18

Improper effective entry date

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

R19

Amount field error

Improper formatting of the amount field

R20

Non-payment bank account

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

R21

Invalid company ID number

The company ID information not valid (normally CIE entries)

R22

Invalid individual ID number

Individual id used by receiver is incorrect (CIE entries)

R23

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

R24

Duplicate entry

RDFI has received a duplicate entry

R25

Addenda error

Improper formatting of the addenda record information

R26

Mandatory field error

Improper information in one of the mandatory fields

R27

Trace number error

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

R28

Transit routing number check digit error

Check digit for the transit routing number is incorrect

R29

Corporate customer advises not authorized

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

R30

RDFI not participant in check truncation program

Financial institution not participating in automated check safekeeping application

R31

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

R32

RDFI non-settlement

RDFI is not able to settle the entry

R33

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

R34

Limited participation RDFI

RDFI participation has been limited by a federal or state supervisor

R35

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.

Field Content Max Length Comments
respstat Status 1 Indicates the status of the authorization request. Can be one of the following values:
  • A - Approved
  • B - Retry
  • C - Declined
retref Retrieval reference number 12 CardConnect retrieval reference number from authorization response
account Account number 19 Copied from the authorization request, masked except for the last four digits.
token (if requested) Token 19 A token that replaces the card number in capture and settlement requests if requested
amount Amount 12 Authorized amount. Same as the request amount for most approvals.
The amount remaining on the card for prepaid/gift cards if partial authorization is enabled.
Not relevant for declines.
batchid Batch ID 12 Automatically created and assigned unless otherwise specified. Returned for a successful authorization with capture.
orderid Order ID 19 Order ID copied from the authorization request.
merchid Merchant ID 12 Copied from the authorization request.
Note: If you include the merchant ID on a receipt, mask this value, except the last four digits.
respcode Response code - Alpha-numeric response code that represents the description of the response
resptext Response text - Text description of response
respproc Response processor4Abbreviation that represents the platform and the processor for the transaction
bintypeType of BIN16Possible Values:
  • Corp
  • FSA+Prepaid
  • GSA+Purchase
  • Prepaid
  • Prepaid+Corp
  • Prepaid+Purchase
  • Purchase
entrymode POS Entry Mode 25 Only returned for merchants using the First Data North 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.
emvTagData EMV tag data 2000 A 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.
receipt receipt data - An object that includes additional fields to be printed on a receipt.

Refer to Receipt Data below for a list of the fields returned.

EMV Tag Data

If the card used in the authorization request was an EMV (chip or contactless) card, then the response data includes an emvTagData object with the following fields:

NameTagDetailsSourceFormatMax Length
TVR (Terminal Verification Results)95Status of the different functions as seen from the terminalTerminalbinary5
ARC (Authorization Response Code)8AIndicates the transaction disposition of the transaction received from the issuer for online authorizations.Issuer/Terminalan 22
PIN (CVM Results)9F34Indicates the results of the last CVM performed. If PIN was entered, returns "Verified by PIN"TerminalString15
Signature (CVM Results)9F34Indicates the results of the last CVM performed. If "true" then CVM supports signature and signature line may be applicable. However, card brands have moved away from requiring signature for EMV transactions.

Returns "unknown" if the signature requirement could not be determined.
TerminalString7
Mode
Identifies the mode used to authorize (or decline) the transaction. Always "Issuer"CardConnectString6
TSI (Transaction Status Information)9BIndicates the functions performed in a transactionTerminalb2
Application Preferred Name9F12Preferred mnemonic associated with the AID. If unavailable, use Application Label.Cardans1-16
AID (Application Identifier, Terminal)9F06Identifies the application as described in ISO/IEC 7816-5Terminalbinary 40-1285-16
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 Method
Indicator identifying how the card information was obtained.TerminalString11
Application Label50Mnemonic associated with the AID according to ISO/IEC 7816-5. If unavailable, use the Application Preferred Name.Cardans with the special character limited to space1-16

Receipt Data

The receipt object, included in the authorization response, provides merchant account information. The merchant account information is populated using the merchant properties configured for the MID.

Additionally, this object includes additional transaction details from the authorization response. You can optionally include a custom order note (orderNote) and item details (items), by including a userFields object in the authorization request.

You can specify the following fields in a userFields object to include an order note or item details, or to override the merchant properties:

FieldDescription
receiptOrderNoteUse this field to provide a custom note to include on the receipt.
receiptItemsUse this field to provide custom item descriptors to include on the receipt.
receiptHeaderUse this field to override the header configured for your MID.
receiptFooterUse this field to override the footer configured for your MID.
receiptDbaUse this field to override the DBA name configured for your MID.
receiptPhoneUse this field to override the phone number configured for your MID.
receiptAddress1Use this field to override the address (line 1) configured for your MID.
receiptAddress2Use this field to override the address (line 1) configured for your MID.

Each value can be any string and the total length of user defined fields (URL/JSON-encoded) is limited to 4000 bytes. See the description of userFields in the CardPointe Gateway API documentation for more information.

Contact isvhelpdesk@cardconnect.com for assistance configuring the receipt printing properties for your merchant account.

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

FieldFormatDescription
headerANA customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement.
footerANA customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement.
dbaANThe merchant's Doing Business As (DBA) name.
address1ANLine 1 of the merchant's address.
address2ANLine 2 of the merchant's address.
phoneNThe merchant's phone number.
dateTimeNThe date and time of the transaction (YYYYMMDDHHMMSS).
nameOnCardAThe Cardholder's name, if included in the authorization request.
orderNoteANA custom order note, if included in the userFields in the authorization request.
itemsANA custom item descriptor, if included in the userFields in the authorization request.

Printing a Receipt

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

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

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.

Timed Out Response

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

In this case, a response, including a retref for the transaction, is returned. The response includes  "repstat": "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 status.cardconnect.com 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

MethodURLHeaders
GEThttps://hostname:port/cardconnect/rest/openbatch/<merchid>/<batchsource>Authorization: Basic

openBatch Request

Fields in bold are required.

FieldTypeComments
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"
}
FieldTypeComments
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

MethodURLHeaders
GEThttps://hostname:port/cardconnect/rest/closebatch/<merchid>/<batchid>Authorization: Basic

closeBatch Request

Fields in bold are required.

FieldTypeComments
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"
}
FieldTypeComments
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
Authorization
'capture' column set to 'N'
Authorization with Capture
'capture' column set to 'Y'
Refund without Reference
'amount' column set to a negative value
Note:
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 integrationdelivery@cardconnect.com.

BAS Request File Name

<merchantname>_<yymmdd>_<sequence#>.csv.pgp

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,gsacard
081800000001,1000102424,VISA,9404077753845057,1299,100,Y,USD,test@test.com,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,,,Y
081800000001,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,test@test.com,,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,test@test.com,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.

FieldSizeTypeComments
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.
account#19N

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.

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

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

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

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

    <name>_<yymmdd>_<seq>.csv.pgp.done

    Sample BAS Response File

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

    BAS Response File Fields

    FieldContentMax LenComments
    idInteger20BAS transaction ID
    statusString
    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.