Credits and Debits Report Guide
Merchant Reconciliation
Introduction
Many integrators will have a need to keep their accounting system up to date on the transactions they have processed. Merchant customers need to know what transactions were deposited, and in which batch and day they appear for reconciliation. The Transaction Reporting API provides a way to do this with credits and debits methods. These methods can be used to report on the movement of funds in/out of the merchant settlement account by EPS, along with the transaction details that make up a settlement. This will include both credits (for originations) and debits (for chargebacks/returns or refunds). The objective in this guide will be to show the basics for creating such a report.
Getting Started
Here’s what you’ll do in this guide
- Create a report that can be used to reconcile deposits and or withdrawals on a merchant settlement account made through the EPS SmartPay system.
Prerequisites needed before continuing
- You will want to obtain your test credentials in order to try any of the examples in this guide. You should have received these from your Implementation Coordinator.
- Download the Transaction Reporting WSDL file from the Downloads menu
Create a Reconciliation Report with Credits and Debits Workflow Guide
For this guide we will walk through an example where we will create a report of money settling in our merchant account to reconcile against. In this example we will pull all locations for the merchant represented by the value of 0, and we will pull data for the last 3 days.
- Step 1 The first thing we will need to do is send a CreditandDebitReports Request to pull the batch information we require to fit our example.
note
The end date specified does not include batches on that date. In this example, any batches with an effective date of the 25th will not be included. Also, batch effective dates represent the day the deposits are settled and will hit the merchant bank statement and not the transactions effective dates. Notice how in the soap examples, the batch effective date is after the effective dates of the transactions.
Here is what our completed CreditandDebitReports Request will look like for this example.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:pv="https://ssl.selectpayment.com/PV">
<soap:Header/>
<soap:Body>
<pv:CreditandDebitReports>
<pv:storeId>your storeid</pv:storeId>
<pv:storeKey>your storekey</pv:storeKey>
<pv:entityId>your entityid</pv:entityId>
<pv:locationIds>
<pv:int>0</pv:int>
</pv:locationIds>
<pv:beginDate>2019-10-22</pv:beginDate>
<pv:endDate>2019-10-25</pv:endDate>
</pv:CreditandDebitReports>
</soap:Body>
</soap:Envelope>
- Step 2 Once this request is sent to the endpoint, we should get a successful response. In this example 2 batches have returned based on our criteria. Each of these batches represents a settlement amount of either a credit or a debit to the merchant account. Each of these batches are processed which means they have been sent out in processing files. Save the BatchIds for the next step.
Here is what our successful response looks like for this example.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<CreditandDebitReportsResponse xmlns="https://ssl.selectpayment.com/PV">
<CreditandDebitReportsResult>
<xs:schema id="NewDataSet" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xs:element name="NewDataSet" msdata:IsDataSet="true" msdata:UseCurrentLocale="true">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="Table">
<xs:complexType>
<xs:sequence>
<xs:element name="BatchStatus" type="xs:string" minOccurs="0"/>
<xs:element name="EffectiveDate" type="xs:dateTime" minOccurs="0"/>
<xs:element name="BatchID" type="xs:long" minOccurs="0"/>
<xs:element name="Description" type="xs:string" minOccurs="0"/>
<xs:element name="Amount" type="xs:decimal" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
<diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
<NewDataSet xmlns="">
<Table diffgr:id="Table1" msdata:rowOrder="0">
<BatchStatus>Processed</BatchStatus>
<EffectiveDate>2019-10-22T00:00:00-5:00</EffectiveDate>
<BatchID>6559193077</BatchID>
<Description> Withdrawal fc662e50-6d29-4a33-bfa8-0cbad2533915</Description>
<Amount>-2.0000</Amount>
</Table>
<Table diffgr:id="Table2" msdata:rowOrder="1">
<BatchStatus>Processed</BatchStatus>
<EffectiveDate>2019-10-24T00:00:00-05:00</EffectiveDate>
<BatchID>6941886333</BatchID>
<Description>Deposit 1981102c-c313-48b3-b67f-cb5338fee0df</Description>
<Amount>403.0000</Amount>
</Table>
</NewDataSet>
</diffgr:diffgram>
</CreditandDebitReportsResult>
</CreditandDebitReportsResponse>
</soap:Body>
</soap:Envelope>
- Step 3 For the next part of this report we will gather the specific transactions that make up the totals for the batches. To do that we will need to send a CreditsandDebitsTransactionDetailReport using the BatchIds from the previous response. It is important in this step to have logic that prevents sending requests that we already have data for. For this example, we will say that we already have transaction detail records for BatchId 6559193077 and will not need to send a detail request for it. However, BatchId 6941886333 we have not yet gathered transaction records for and will require a details request.
Here is what our CreditsandDebitsTransactionDetailReport request looks like to retrieve records for BatchId 6941886333.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:pv="https://ssl.selectpayment.com/PV">
<soap:Header/>
<soap:Body>
<pv:CreditsandDebitsTransactionDetailReport>
<pv:storeId>your storeid</pv:storeId>
<pv:storeKey>your storekey</pv:storeKey>
<pv:entityId>your entityid</pv:entityId>
<pv:batchId>6941886333</pv:batchId>
</pv:CreditsandDebitsTransactionDetailReport>
</soap:Body>
</soap:Envelope>
- Step 4 The details response will give us all transactions that make up batch 6941886333. In this example there are three ACH debit transactions making up the total deposit of 403.00 dollars. With this more detailed view we get key pieces of data like, the ReferenceNumber or TransactionNumber to log or use in other web methods.
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<CreditsandDebitsTransactionDetailReportResponse xmlns="https://ssl.selectpayment.com/PV">
<CreditsandDebitsTransactionDetailReportResult>
<WSSettlementBatch>
<EntryType>Sale</EntryType>
<BatchDescription>Jack Henry & Associates</BatchDescription>
<Reason/>
<Amount>400.0000</Amount>
<transactionDetails>
<EntityId>12345</EntityId>
<LocationId>102030</LocationId>
<CustomerNumber/>
<PaymentOrigin>Internet</PaymentOrigin>
<AccountType>Checking</AccountType>
<OperationType>Sale</OperationType>
<TransactionStatus>Processed</TransactionStatus>
<SettlementStatus>Settled</SettlementStatus>
<EffectiveDate>2019-10-23T00:00:00</EffectiveDate>
<TransactionDate>2019-10-23T08:57:43.12</TransactionDate>
<Description/>
<SourceApplication>Web_Service</SourceApplication>
<OriginatingAs>ACH</OriginatingAs>
<AuthResponse>Success</AuthResponse>
<TotalAmount>400.0000</TotalAmount>
<ReferenceNumber>T:W44F65VKLA2</ReferenceNumber>
<TransactionNumber>1031</TransactionNumber>
<Field1/>
<Field2/>
<Field3/>
<DisplayAccountNumber>1111</DisplayAccountNumber>
<EmailAddress/>
<NotificationMethod>Merchant_Notify</NotificationMethod>
<FaceFeeType>Face</FaceFeeType>
<ShippingAmount>0.0000</ShippingAmount>
</transactionDetails>
</WSSettlementBatch>
<WSSettlementBatch>
<EntryType>Sale</EntryType>
<BatchDescription>Jack Henry & Associates</BatchDescription>
<Reason/>
<Amount>1.0000</Amount>
<transactionDetails>
<EntityId>12345</EntityId>
<LocationId>102030</LocationId>
<CustomerNumber/>
<PaymentOrigin>Internet</PaymentOrigin>
<AccountType>Checking</AccountType>
<OperationType>Sale</OperationType>
<TransactionStatus>Processed</TransactionStatus>
<SettlementStatus>Settled</SettlementStatus>
<EffectiveDate>2019-10-23T00:00:00</EffectiveDate>
<TransactionDate>2019-10-23T16:49:46.42</TransactionDate>
<Description>test</Description>
<SourceApplication>Web_Service</SourceApplication>
<OriginatingAs>ACH</OriginatingAs>
<AuthResponse>Success</AuthResponse>
<TotalAmount>1.0000</TotalAmount>
<ReferenceNumber>T:2JMW65VKLA4</ReferenceNumber>
<TransactionNumber>1032</TransactionNumber>
<Field1>test</Field1>
<Field2/>
<Field3/>
<DisplayAccountNumber>1111</DisplayAccountNumber>
<EmailAddress/>
<NotificationMethod>Merchant_Notify</NotificationMethod>
<FaceFeeType>Face</FaceFeeType>
<ShippingAmount>0.0000</ShippingAmount>
</transactionDetails>
</WSSettlementBatch>
<WSSettlementBatch>
<EntryType>Sale</EntryType>
<BatchDescription>Jack Henry & Associates</BatchDescription>
<Reason/>
<Amount>2.0000</Amount>
<transactionDetails>
<EntityId>12345</EntityId>
<LocationId>102030</LocationId>
<CustomerNumber/>
<PaymentOrigin>Internet</PaymentOrigin>
<AccountType>Checking</AccountType>
<OperationType>Sale</OperationType>
<TransactionStatus>Processed</TransactionStatus>
<SettlementStatus>Settled</SettlementStatus>
<EffectiveDate>2019-10-23T00:00:00</EffectiveDate>
<TransactionDate>2019-10-23T16:50:29.607</TransactionDate>
<Description/>
<SourceApplication>Web_Service</SourceApplication>
<OriginatingAs>ACH</OriginatingAs>
<AuthResponse>Success</AuthResponse>
<TotalAmount>2.0000</TotalAmount>
<ReferenceNumber>T:KTNH65VKLA2</ReferenceNumber>
<TransactionNumber>1033</TransactionNumber>
<Field1/>
<Field2/>
<Field3/>
<DisplayAccountNumber>1111</DisplayAccountNumber>
<EmailAddress>jdoe@domain.com</EmailAddress>
<NotificationMethod>Merchant_Notify</NotificationMethod>
<FaceFeeType>Face</FaceFeeType>
<ShippingAmount>0.0000</ShippingAmount>
</transactionDetails>
</WSSettlementBatch>
</CreditsandDebitsTransactionDetailReportResult>
</CreditsandDebitsTransactionDetailReportResponse>
</soap:Body>
</soap:Envelope>
Here is how the CreditsandDebitsTransactionDetailReport example looks for this example represented as a complete workflow diagram. Click on the method boxes to be taken to the specific API reference.
Integrator Payment Flow | EPS Web Service Flow | ||||
EPS Web Service | |||||
| 1. | |||||
| 2. | |||||
| 3. | Log and Display results from the previous two requests as needed to keep accounting systems up to date to meet business needs. | ||||
| |||||
Handling Errors and Failed Requests
Not all requests will be successful, so we will need to run through a few common errors you should be ready to handle.
- Timeout waiting for response – Systems should be designed to wait 10 minutes for reporting requests to receive a response before timing out.
- If a timeout occurs, the request can be attempted a second time but should not be set to a retry loop.
- The timeout may be a result of attempting to pull back large amounts of data at once and scaling back the request parameters may be successful. Repeated timeouts on a reporting request should be followed up by contacting us through your normal support channels.
- Login failed – This error will indicate that something is wrong with your login credentials. These errors cannot be retried as multiple failures will result in a complete lockout. Check your credentials and verify nothing has changed on your end before proceeding. Login failures often require customer support assistance to resolve, so please do contact us through your normal support channels should this occur.
On all reporting requests there are some guidelines and restrictions that must be adhered to for quality purposes. Each of the following items will be validated during your web service certification to ensure that EPS standards are met before production use.
- No more than 5 threads at a time should be used by the sending application.
- Failed credential scenarios should not continuously retry in a loop.
- Health check monitors hitting the system will not be permitted.
- Reports should not exceed retrieving data for the previous 3 business days.
- Reports should only repeat calls on batches or items in cases of no response or timeout of the original request.
- Reports should be limited by employing logic to only retrieve data on batches or items you do not already have.
Next steps
- Customize the workflows to fit your specific business needs.
You can apply the principles shown in this example and customize the requests using the API Reference to suit your needs. You may only need to capture the batch information and not transaction information, or would like to retrieve each location individually instead of all at once. You can also substitute this other method in place of CreditandDebitReports.- GetCreditandDebitReports – Will return the same data as CreditandDebitReports in an array instead of a data set.
- Review the API Reference This guide is just a starting point to show a common use case scenario for building a reconciliation report. Please review the API Reference to see all APIs and their technical specifications.
- Explore other guides We have other guides to show how to leverage our APIs in other common use cases so if this one doesn’t cover what you are looking for, give another guide a try.
- Get certified and move into production
Ready to put your new code into production use? Refer to this process guide that explains our certification steps and how to contact us to get started.