Skip to main content

Returns Reports for Rcodes

Introduction​

Many integrators will have a need to keep their third-party system up to date by capturing any returns that may have processed back through the SmartPay system. Merchant customers need to know what transactions were returned, and on what day they returned with the R-Code reason to take necessary action. The Transaction Reporting API provides a way to do this with historical events methods. 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 capture returns for a merchant 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 Transaction Returns Report with Get Historical Events Workflow Guide​

For this guide we will walk through an example where we will create a daily report of transactions that have returned for the past 24 hours on one of our merchants. In this example we will pull all locations for the merchant represented by the value of 0, and we will be sure to capture the return reason code from the response to store in the third-party system.

  • Step 1 The first thing we will need to do is send a GetHistoricalEvents Request to pull the information we require to fit our example. We will say that our return report is set to a daily schedule that runs shortly after 12pm central time. To avoid overlap and duplicate information we will set “beginTransDate” to start from the last time this report ran. The “endTransDate” will be set to the present time.
note

Returns are processed each business day by noon central time. The beginTransDate and endTransDate represent the event date/time, not the transaction date/time. Using these fields allows you to provide the window of time to pull back only “new” events since the last call.

note

For both the “beginTransDate” and “endTransDate”, events will be returned that have a time value equal to the search time value. Notice in the example, the EventDateTime of T17:01:00 was returned when using T17:01:00 in the “endTransDate”. A “beginTransDate” of T17:01:00 would also return this event. Keep this in mind to avoid pulling duplicate events.

  • Step 2 We will use 0 in the “LocationIds” property to pull all locations.
  • Step 3 Using “wsdisplayFields”, we can limit the fields we want to see in the response. For our returns report we want to be sure to include “ReturnCode”. The “ReturnCode” field will provide the return reason (R-Code) for why the transaction was returned.
note

A list of R-Codes and their corresponding descriptions can be found here. It is recommended that a lookup table be created in your database based on these definitions for the purpose of showing a friendly return description to users of the front end.

  • Step 4 Using the “wstransEvents”, we will only report events that are applicable for returned transactions which are the five types listed below. For all other properties we will return the defaults.
    • Disputed
    • Returned_NSF
    • Returned_Bad_Account
    • Unauthorized
    • Other_Check21_Returns (only applicable to C21 returns, not applicable to ACH returns)

Here is what our completed GetHistoricalEvents 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:GetHistoricalEvents>
            <pv:storeId>your storeid</pv:storeId>
            <pv:storeKey>your storekey</pv:storeKey>
            <pv:entityId>your entityid</pv:entityId>
            <pv:wsdisplayFields>
                <pv:WSDisplayFields>ReturnCode</pv:WSDisplayFields>
                <pv:WSDisplayFields>Event_Type_Name</pv:WSDisplayFields>
                <pv:WSDisplayFields>Transaction_Status_Name</pv:WSDisplayFields>
                <pv:WSDisplayFields>Payment_Type_Name</pv:WSDisplayFields>
                <pv:WSDisplayFields>Transaction_Number</pv:WSDisplayFields>
                <pv:WSDisplayFields>Reference_Number</pv:WSDisplayFields>
                <pv:WSDisplayFields>Operation_Type_Name</pv:WSDisplayFields>
                <pv:WSDisplayFields>Location_Display_Name</pv:WSDisplayFields>
                <pv:WSDisplayFields>Total_Amount</pv:WSDisplayFields>
                <pv:WSDisplayFields>Payment_Origin_Name</pv:WSDisplayFields>
                <pv:WSDisplayFields>Settlement_Status_Name</pv:WSDisplayFields>
                <pv:WSDisplayFields>Event_DateTime</pv:WSDisplayFields>
            </pv:wsdisplayFields>
            <pv:locationIds>
                <pv:int>0</pv:int>
            </pv:locationIds>
            <pv:wstransEvents>
                <pv:WSTransactionEvent>Disputed</pv:WSTransactionEvent>
                <pv:WSTransactionEvent>Returned_NSF</pv:WSTransactionEvent>
                <pv:WSTransactionEvent>Returned_Bad_Account</pv:WSTransactionEvent>
                <pv:WSTransactionEvent>Unauthorized</pv:WSTransactionEvent>
                <pv:WSTransactionEvent>Other_Check21_Returns</pv:WSTransactionEvent>
            </pv:wstransEvents>
            <pv:wstransStatus>
                <pv:WSTransactionStatus>__NONE</pv:WSTransactionStatus>
            </pv:wstransStatus>
            <pv:wssettlementType>
                <pv:WSSettlementType>None</pv:WSSettlementType>
            </pv:wssettlementType>
            <pv:wspaymentType>__NONE</pv:wspaymentType>
            <pv:wspaymentOrigin>
                <pv:WSPaymentOrigin>__NONE</pv:WSPaymentOrigin>
            </pv:wspaymentOrigin>
            <pv:wssettlementStatus>
                <pv:WSSettlementStatus>__NONE</pv:WSSettlementStatus>
            </pv:wssettlementStatus>
            <pv:wsauthResponseCode>__NONE</pv:wsauthResponseCode>
            <pv:wsopType>__NONE</pv:wsopType>
            <pv:beginTransDate>2021-02-16T12:30:00</pv:beginTransDate>
            <pv:endTransDate>2021-02-17T17:01:00</pv:endTransDate>
            <pv:fromAmount></pv:fromAmount>
            <pv:toAmount></pv:toAmount>
        </pv:GetHistoricalEvents>
    </soap:Body>
</soap:Envelope>
  • Step 5 Once this request is sent to the endpoint, we should get a successful response. In this example one event has returned which represents a single returned transaction. There are a few key items that are important to log with this response.
    • ReferenceNumber – EPS generates this value for you to use for pulling reporting information on the transaction later. You will want to use this number to lookup the transaction stored in your database to keep the most current status.
    • ReturnCode – Reason for the return. This will need to be cross referenced with the code definitions discussed earlier.
    • Amount – Amount of the return.
    • SettlementStatus – Returns will be charged back to the merchant.
    • TransactionStatus – Represents the state the transaction is in overall.

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>
    <GetHistoricalEventsResponse xmlns="https://ssl.selectpayment.com/PV">
        <GetHistoricalEventsResult>
            <WSEventReport>
                <TransactionStatus>Uncollected NSF</TransactionStatus>
                <PaymentType>Checking</PaymentType>
                <TransactionNumber>111</TransactionNumber>
                <ReferenceNumber>T:WNSNJ49MLA1</ReferenceNumber>
                <OperationType>Sale</OperationType>
                <LocationName>General Account</LocationName>
                <TransactionDateTime>0001-01-01T00:00:00</TransactionDateTime>
                <TotalAmount>5.0000</TotalAmount>
                <PaymentOrigin>Internet</PaymentOrigin>
                <SettlementStatus>Charged Back</SettlementStatus>
                <OwnerAppReferenceId>0</OwnerAppReferenceId>
                <ReturnCode>R01</ReturnCode>
                <EventDateTime>2021-02-17T17:01:00</EventDateTime>
                <EventType>Returned NSF</EventType>
            </WSEventReport>
        </GetHistoricalEventsResult>
    </GetHistoricalEventsResponse>
    </soap:Body>
</soap:Envelope>

Here is how the GetHistoricalEvents report for returns will look 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.

Send a GetHistoricalEvents Request.

  • Use (0) for all locations
  • Data range of 1 day beginning from the last time the report was run to present.
  • Include 'ReturnCode' in 'wsdisplayFields' along with any other fields that are needed.
  • Include 'Disputed', 'Returned_NSF', 'Returned_Bad_Account', 'Unauthorized', 'Other_Check21_Returns' in the 'wstransEvents'.

Successful Key Return Information GetHistoricalEvents Response

  • ReferenceNumber = EPS generated transaction reference.
  • ResponseCode = Reason for the return. Cross reference with 'Return Events/Codes' provided in the portal.
  • Amount = Amount of the return.
  • SettlementStatus = Status of the chargeback to the merchant.
2.

Log and Display results from GetHistoricalEvents as needed to keep third-party 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. For example, you may wish to apply other filters, add different display fields to the request or retrieve each location individually instead of all at once. You can also substitute this other method in place of GetHistoricalEvents.
    • GetHistoricalEventReport – Will return the same information as GetHistoricalEvents but must send only one event type per request.
    • HistoricalEventReport – Operates the same as GetHistoricalEventReport but will return a data set instead of an array.
  • Review the API Reference
    This guide is just a starting point to show a common use case scenario for building a transaction returns 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.