Reconciliation Files

While a postback serves as a notification of a single specific activity occurring with payments, a reconciliation file is on the opposite end of the spectrum. Reconciliation files are machine-readable files generated and transmitted daily at scheduled times to cover every bit of payment activity that occurred over a specific 24 hour period. This covers all types of activity including payments, reversals, chargebacks, etc.

A reconciliation file can serve as the ultimate backstop in ensuring that all payment activity is accounted for in both systems. The generated files can be picked up using secure means (via SFTP) from PaymentExpress systems, or under some conditions can be transmitted in secure fashion (via SFTP) to destinations in the client system.

File Format

A standard reconciliation file is a comma separated values (CSV) file with one line for each payment action, but can be separated by locations or charge status as well. The following fields are provided by default in a standard reconciliation file:

timestamp - A RFC3339 compliant timestamp of when the payment was completed.
paymentId - The PaymentExpress unique identifier for the payment that was collected. This value is communicated to the end user in their receipt as well as recorded as the primary identifier for the payment in the PaymentExpress system.
clientTransactionId - The unique transaction identifier supplied by your system when the cart was created in the PaymentExpress system, to allow for the identification of the transaction in your system.
status - The status of this payment at the time of file generation. Possible values include charged, voided, reversed.
primaryAmount - The amount that the customer was charged for this transaction, excluding any applicable transaction fees. This is the amount that will make its way to your bank account and matches the amount that was transmitted at cart creation.
feeAmount - The amount that the customer was charged as a fee for processing this transaction, in addition to the primary amount which is remitted to the payee.
tenderType- The tender type (CreditCard, eCheck, Paypal, etc) used to complete the transaction.
cardBrand - A string value representing the brand of card that was used to complete this payment.

There are other fields about the transaction which can be included in the reconciliation file, especially including any fields which were transmitted in the meta sections of the cart creation request.

Example File

Below is an example reconcilation file in this standard format.

timestamp,paymentId,clientTransactionId,status,primaryAmount,feeAmount,tenderType,cardBrand
2023-08-14 00:00:42Z,H1234567890,ec8ccd54-3c4c-11ee-be56-0242ac120002,charge,21.00,1.00,CreditCard,Visa
2023-08-14 00:03:20Z,P2468013579,1d66f98d-092e-4f0e-8114-ae374379db61,charge,26.00,1.00,CreditCard,MasterCard
2023-08-14 00:06:02Z,N0987654321,0c4f0c9f-7a3c-4360-bd89-4036639771a9,charge,26.00,1.00,CreditCard,Discover Card

Under some circumstances, it may be preferable to break down a reconciliation file by paid items, rather than by payment, which is also supported.

For any further details about reconciliation files, please reach out to us and we'd be happy to discuss.