Developer Resource Center

Batch Pay


The EdgePay BatchPay Service extends the payment services defined in the Application Protocol Interface to be sent to us as a file for processing instead of real-time. This may be a convenient method for businesses that either cannot transmit in real-time or because of the business function it makes more sense to process in batch. One example is sending capture-only transactions after the product is shipped.

Uploading Batches

To upload a batch of payments to process, the user will log into the EdgePay Processing Center with their username and password and navigate to BatchPay. From there, they will either browse to or drop the .CSV file to the "Upload Batch File" box and select "Upload."

Screenshot of the BatchPay Upload screen in EdgePay

The service will perform field-level validation on the file to ensure performance. Errors will display in real-time if found.

Provided the file passes field-level validation edits, the service will run approximately every 5 minutes and the result file will be provided in the reports section BatchPay.

File Format

The EdgePay batch file format is a fixed .CSV file with CR/LF at the end of each row. Below are the available fields and their associated properties.

Field Name Max Size Attribute Notes
externalReferenceID 16 N Required - unique transaction ID you assign
cardNumber 19 N Conditional - supply this for manually entered cards
cardExpirationDate 4 N Conditional - if card number used this is required
tokenID 16 N Conditional - may supply in place of track data or card data or eCheck data from previously tokenized transaction
token 3 A "Yes" returns a tokenID value for your local storage in the response (report)
eCheckRoutingNumber 9 N Conditional - required for eCheck - route number for the bank
eCheckAccountNumber 19 N Conditional - required for eCheck - account number for the check writer
eCheckTransactionType 3 A Conditional - required for eCheck - the standard entry classification for echeck
  • ARC - accounts receivable truncation
  • CCD - cash concentration and disbursement
  • PPD - prearranged payment and deposit
  • POP - point of purchase
  • WEB - web-initiated transaction
  • TEL - telephone-initiated transaction
eCheckSerialNumber 15 N Conditional - required for ARC & POP
eCheckAccountType 1 AN Conditional - required for eCheck
  • "C" - checking (default)
  • "G" - general ledger account
  • "S" - savings
goodsOrServices 10 AN Optional - description for eCheck - check writer's statement
eCheckReceivingCompanyName 50 A Conditional - required for CCD transactions
paymentTypeCode 1 A eCheck recurring only - "S" = single, "R" = recurring
paymentDataInput 14 AN Required - defines the point of sale entry mode
  • Phone
  • Mail
  • Internet
  • Swipe
  • NFC
  • EMV
  • EMV contactless
  • Fallback swipe
  • Barcode
  • Manual entry
amount 12 N Total amount charged, with or without decimal. All minor units after decimal. No decimal amount is processed as major units (dollars, euros, etc.)
currencyCode 3 N Optional - assume USD unless otherwise specified. Requires multi-currency option if other currency is specified
customerName 30 AN Conditional - required for eCheck, optional otherwise
customerNumber 17 AN Conditional - required for eCheck CCD, optional otherwise
captureOnly 3 A Conditional - "Yes" for capture-only transaction. Must include transactionID and amount if different from authorization
captureToo 3 A Conditional - "Yes" - no additional sub-fields beyond authorization requirements
processor 10 AN Future use
billingAddress 200 AN Conditional - not required but may improve interchange rate for card-not-present transactions
billingCity 50 AN Same as above
billingState 2 A Same as above - 2-letter state code
billingZip 10 AN Same as above - "-" allowed
merchantField1 200 AN Optional field for echo back
merchantField2 200 AN Optional field for echo back
posData - - Future use
CVV2 4 N Optional - security code from credit card
adjust 3 A "Yes" to adjust the amount of a previously captured transaction prior to settlement. Requires amount, tip and tax optional
refund 3 A "Yes" to refund a previously approved transaction. Required transactionID. Supply amount if refund is less than original transaction amount. May supply cardNumber and cardExpirationDate if account is set up for refund without offsetting transaction debit
tip 12 N Optional - send if tip amount needs to be adjusted
tax 12 N Optional - send if tax amount needs to be adjusted
healthCare 3 A "Yes" to process payment as a healthcare transaction
healthCareAccountType 3 AN "FSA" or "HSA" required
prescriptionAmt 12 N Conditional - at least 1 amount field is needed in the healthcare section. Total of all amounts must be less than or equal to the payment amount
visionAmt 12 N Same as above
dentalAmt 12 N Same as above
clinicAmt 12 N Same as above
posQualified 6 AN Purchase is qualified by the POS. Valid values are: "yes", "no", "exempt"
rxNumber 19 AN Optional - customer number
level2 3 A "Yes" invokes level 2 processing
level2Auth 3 A "Yes" is required for authorizations only
level2Capture 3 A "Yes" is required if "captureToo" or "captureOnly"
taxAmount 12 N Conditional - required for level 3
taxCategory 10 AN Conditional - level 3. Valid values are:
  • DUTY
  • VAT
taxRate 12 N Level 3 - with or without decimal
transactionDate 19 AN Required - the transaction date and time for this transaction - YYYY-MM-DD-hh-mm-ss
level3 3 A "Yes" invokes level 3 processing
level3Auth 3 A "Yes" is required if authorization only
level3Capture 3 A "Yes" is required if "captureToo" or "captureOnly" required
shipZipCode 10 AN The ship-from zip. Space or "-" allowed
destinationZipCode 10 AN The ship-to zip. Space or "-" allowed
invoiceNumber - - Future use
itemCode 20 AN - Level 3 only
itemCommunityCode 12 AN - Level 3 only
itemDescription 50 AN - Level 3 only
itemQuantity 12 N - Level 3 only
itemUnitOfMeasure 20 AN See table - Level 3 only
itemExtendedAmount 21 N - Level 3 only
freightAmount 12 N - Level 3 only
dutyAmount 12 N - Level 3 only
purchaseOrder 17 AN - Level 3 only
customerVATNumber 17 AN - Level 3 only
summaryCommodityCode 4 AN Level 3 - call GET
vatInvoice 15 AN Level 3
itemDiscountName 50 ANC Level 3 - name applied to discount
itemDiscountAmount 12 N Level 3 - discount applied
itemDiscountPercent 3 N Level 3 - discount percentage applied
itemDiscountType 20 AN Level 3 - transaction types discount applies
destinationCountryCode 3 AN Level 3 - the code used to describe destination country
supplierReferenceNumber - - Level 3 - call for details
transactionID 17 AN Generated by EdgePay - used in capture or refund transactions - "CS" for card, "AS" for ACH
cardOnFile 1 A "Y" indicated you will be storing the card on file for future payments
recurring 3 A "Yes" indicates a recurring payment to issuer. Used on all subsequent transactions after "cardOnFile"
billingType 25 AC Required for billing transactions. Allowed values are:
paymentCount 4 N Conditional for recurring payment. Required if billingType = installment. The count of payments in a recurring schedule of payments. Send either the end date or count
currentPaymentCount 3 N Conditional - required if billingType = installment. Indicates current payment count
chargeDescriptor 40 AN Level 3 - AmEx only - additional descriptor
transDiscountName   AN Level 3 - Name of discount applied
transDiscountAmount 12 N Level 3 - The dollar amount of the discount applied
authCode 6 AN Required for previously authorized transactions


After processing the uploaded file, BatchPay will display the results of processing (approved, declined, or error) in the BatchPay reports screens located in the Processing Center.

The reports are maintained for both viewing and download for 10 days, then archived at the summary view. We provide the date/time the file was processed, file name, total transactions submitted and any error transactions that failed. The date/time hyperlink drills down to a detail view, providing totals and individual transaction information. From here the user can download a .CSV of the report. 

Report Format

The results report format for the BatchPay processing is a fixed .CSV file with the CR/LF at the end of each row. Below are the fields and their associated properties. The first row contains header information and may be ignored. Null is a valid value for most fields if we are unable to process a record.

Field Name Max Size Attribute Notes
dateTime 19 Calendar YYYY-MM-DD-hh-mm-ss
amount 12 N Total amount charged. Returned with decimal
customerNumber 17 AN Echo back. Null is valid
maskedAccount 19 N Masked account data. Card first 6 and last 4 unmasked, eCheck last 4 unmasked
type - AN Visa, MasterCard, American Express, Discover
transactionID 19 AN Unique identifier assigned by EdgePay
customerName 30 AN Echo back
recurring 5 AN True or false
currency 3 A USD default
status   A The current status of the transaction: authorized, captured, declined, refunded, verified.