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 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.
Using BAS to transmit batch files is not a drag-and-drop solution. Integrating BAS requires development work and testing.
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:
The Batch Authorization Service supports all data elements that the CardPointe Gateway Authorization Service supports.
Authorization Type | Details |
---|---|
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. |
All files that are submitted to or retrieved from Secure Exchange must be PGP encrypted. This requires two PGP key pairs:
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
The value within each record's account field must be a valid CardConnect token. This service does not handle clear-text card numbers.
If your integration does not yet support CardConnect tokens, contact integrationdelivery@cardconnect.com.
<merchantname>_<yymmdd>_<sequence#>.csv.pgp
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,,,,,,,,,,,,,,,
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.
Field | Size | Type | Comments |
---|---|---|---|
orderid | 19 | AN | Source 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. Note the following requirements:
|
merchid | 12 | N | CardConnect Merchant ID (MID), required for all requests |
amount | 12 | N | Amount 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. |
currency | 3 | AN | Currency of merchant settlement (USD for US dollars, CAD for Canadian Dollars, etc.) |
expiry# | 4 | N | Card Expiration in either MMYY or YYYYMMDD format, not required for ECHK. |
account# | 19 | N | 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 Note: To use a CardConnect profile, omit the |
profile | 1 or 16 | AN | Optional, 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. |
acctid | 3 | N | Account identifier within a profile, specifies unique token |
capture | 1 | A | Optional, Y to capture the transaction for settlement if approved. |
signature | 6144 | AN | JSON-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. |
cvv2 | 4 | N | CVV2/CVC/CID value |
name# | 30 | AN | Account name Optional for credit cards but required for electronic checks. |
address# | 30 | AN | Account street address (required for AVS) |
city# | 30 | AN | Account city |
postal# | 9 | AN | Account postal code, defaults to "99999". If country is "US", must be 5 or 9 digits. Otherwise any alphanumeric string is accepted. |
region# | 20 | AN | US State, Mexican State, Canadian Province |
country# | 2 | AN | Account country (2 character country code), defaults to "US." Required for all non-US addresses. |
phone# | 15 | AN | Account phone |
email# | 30 | AN | E-Mail address of the account holder |
authcode | 6 | AN | Authorization code from original authorization (VoiceAuth). For Voice/Capture-Only, include valid authcode . |
taxexempt | 1 | A | If 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. |
termid | 30 | AN | Terminal Device ID |
accttype# | 6 | A | One of PPAL, PAID, GIFT, PDEBIT, otherwise not required. |
ecomind | 1 | A | Identifies the payment origin. Options are: T - telephone or mail R - recurring E - ecommerce/Internet |
invoiceid | 12 | AN | Invoice ID, optional, defaults to orderid from authorization request |
userfields | 4000 Bytes |
AN | The userfields object, or array is a series of name-value pairs that are meaningful to the merchant. See details here. Example of userfields value: "{""UDF1"": ""SomeText"", ""UDF2"": ""SomeMoreText""}" |
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.
Field | Size | Type | Comments |
---|---|---|---|
ponumber | 36 | AN | Customer purchase order number |
taxamnt | 12 | N | Tax amount either decimal or in currency minor units (i.e. USD Pennies, MXN Centavos), taxamnt of zero indicates tax-exempt purchaserNote: 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.
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.
Field | Size | Type | Comments |
---|---|---|---|
frtamnt | 12 | N | Total order freight amount, default 0 |
dutyamnt | 12 | N | Total order duty amount, default 0 |
orderdate | 8 | N | YYYYMMDD For most industries this is the delivery date for the order Defaults to System Date when captured |
shiptozip | 12 | AN | If country is "US", must be 5 or 9 digits Otherwise, any alphanumeric string is accepted |
shipfromzip | 12 | AN | Same as above |
shiptocountry | 2 | A | Ship To Country Code, default is US |
Items | varies | Array | Array of Items |
description='desc with a single quote\''
"unitcost='1.00',description='desc with no comma',uom='lb'|unitcost='1.00',description='desc with,comma',uom='lb'"
Line Item Records
Field | Size | Type | Comments |
---|---|---|---|
lineno | 4 | N | Optional 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. |
material | 12 | AN | Optional material code (also referred to as a Commodity Code) for each item. |
description | 26 | AN | An item description, required. |
upc | 14 | N | Optional UPC code for each item. If upc is included, the value must not be all zeros. Some processors limit this value to 12 characters. |
quantity | 12 | N | Quantity of the item purchased. Can be a whole amount or amount with up to three decimal places. |
uom | 8 | AN | Unit of measure (for example, "each" or "ton"). Some processors limit this value to 4 characters. |
unitcost | 12 | N | Optional 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 . |
netamnt | 12 | N | Net 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. |
taxamnt | 12 | N | Tax 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. |
taxexempt | 1 | true/false | Indicates whether or not the order is tax exempt.taxexempt should be true if:
taxexempt defaults to false. |
discamnt | 12 | N | Optional discount amount for each item, as a decimal amount or in currency minor units. |
BAS response files are pgp encrypted with the key that you provided to CardConnect.
Response files will return one Gateway response per line.
The response file name matches the corresponding request file name with the extension ".done" appended.
For example:
<name>_<yymmdd>_<seq>.csv.pgp.done
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
Field | Content | Max Len | Comments |
---|---|---|---|
id | Integer | 20 | BAS transaction ID |
status | String |
10 | Final processing status: "DONE" or "ERROR" |
message | String | None | Details explaining "ERROR" or "LOAD_ERROR" |
orderid | Order ID | 19 | The orderid specified in the Request file |
retref | Retrieval reference number | 12 | CardConnect retrieval reference number from authorization response |
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. |
resptext | Response text | - | Text description of response |
commcard | Commercial card flag | 1 | Y if a Corporate or Purchase Card |
cvvresp | CVV response code | 1 | Alpha-numeric CVV response. |
batchid | Batch ID | 10 | Automatically created and assigned unless otherwise specified |
avsresp | AVS response code | 2 | Alpha-numeric AVS response. |
respcode | Response code | - | Alpha-numeric response code that represents the description of the response |
merchid | Merchant ID | 12 | Copied from request |
token (if requested) | Token | 19 | A token that replaces the card number in capture and settlement requests if requested |
authcode | Authorization code | 6 | Authorization Code from the Issuer |
respproc | Response processor | 4 | Abbreviation that represents the platform and the processor for the transaction |
respstat | Status | 1 |
A - Approved
B - Retry C - Declined |
account | Account number | 19 | Copied from request, masked |
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:
To view reporting details for processed batches in CardPointe do the following:
See the CardPointe Web App support page for more information on using CardPointe.