Overview

The Batch Authorization Service (BAS) is a component of CardConnect's Secure Exchange SFTP product. BAS allows integrating clients to submit batch files for authorization processing. 

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.

This details within this article are broken down into the following sections:

• Client Onboarding Checklist
• Supported Authorization Types
• PGP Keys
• Request File Specifications
• Response File Specifications
• Submitting a Batch File
• Viewing Batch File Transactions in CardPointe

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.

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

Request File Specifications

CardConnect Tokens

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

Request File Name

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

Sample 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,,,,,,,,,,,,,,,

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. 

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.

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

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

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.

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

Fields

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 using the BAS.

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