Add method for to extract a transaction's settlement date

[timeverts]

In various projects we've developed we often need to retrieve the settlement date (if it's available) for a transaction from within its response data and pass that onto a third-party (through a custom plugin). In the past we've achieved this by creating a custom method in our plugin that extracts the settlement date from a transaction response. Considering the response for each Gateway is very different, our plugin could only account for the gateways we knew the site would be using and implement relevant code to extract the settlement date from that gateway's transaction response data.

It would be much nicer if there was a common method that each gateway could (optionally) implement that could provide the settlement date for a transaction extracted from the response data.

So could you consider adding a new method to craft\commerce\omnipay\base\Gateway for extracting the settlement date from a transaction's response?

For example:

    /**
     * Extracts the transaction settlement date from a response.
     *
     * @param ResponseInterface $response
     * 
     * @return null|\DateTime
     */
    protected function extractTransactionSettlementDate(ResponseInterface $response)
    {
        return null;
    }

I'm happy to submit a pull request if you're happy with the idea.

[andris-sevcenko]

Wouldn't that essentially be the same as dateCreated field on the transaction?

[lukeholder]

Or rather, when we capture a transaction in Commerce 2, a new transaction is created that is a child of the parent transaction with a dateCreated as @andris-sevcenko mentioned.

[timeverts]

@lukeholder and @andris-sevcenko, in my experience the settlement date of a transaction is not always necessarily equivalent to the actual transaction date, since the settlement date is the date when the funds will be settled into the merchant's account. So the settlement date is usually determined by the transaction processor and often varies depending on the payment instrument type, non-banking days, daily cut-off times etc.

As an example, take a look at the Paystream/Fat Zebra API example here: https://www.paystream.com.au/developer-guides/ (click on the 'Direct API' tab and view the successful purchase response). As you'll see there, the settlement date and transaction date are different.

A further indication of this can be found in the SecurePay XML Integration guide on page 25 when it describes the <settlementDate> parameter in the XML response from the gateway:

Bank settlement date when the funds will be settled into the merchant’s account. This will be the current date mostly, however after the bank’s daily cut-off time, or on non-banking days, the settlement date will be the next business day. Will not be returned if the bank did not receive the transaction. (A settlement date may be returned for declined transactions.)

When dealing with the Braintree payment gateway, settlement date even varies depending on what payment instrument was used (e.g. PayPal transactions have a specific cut-off time of day for being processed on the same day, Amex transactions also have one etc.).