Batch Pay
Overview
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."
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
|
| eCheckSerialNumber | 15 | N | Conditional - required for ARC & POP |
| eCheckAccountType | 1 | AN | Conditional - required for eCheck
|
| 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
|
| 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:
|
| 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 |
Results
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. |