Add method for gateways to return a transaction's settlement date

[timeverts]

In various projects we've developed we often need to retrieve the settlement date for a transaction (if it's available) and pass that onto a third-party (through a custom plugin) together with other transaction details. 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 for each gateway that could provide the settlement date for a transaction (if it can be determined and is applicable for the transaction type).

So could you consider adding a new method to craft\commerce\base\Gateway for returning the settlement date of a transaction?

For example:

    /**
     * Returns the settlement date of the specified transaction or null if it cannot be determined or is not applicable for the transaction.
     *
     * @param Transaction $transaction
     * @return null|\DateTime
     */
    public function getTransactionSettlementDate(Transaction $transaction)
    {
        return null;
    }

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

[timeverts]

FYI: See also craftcms/commerce-omnipay#8

[lukeholder]

@timeverts Is the settlement date always found in the gateway response data (even if just for your gateway), and if so, are you asking that it is shown on the transaction row itself?

[timeverts]

@lukeholder, sorry for the delayed response.

Yes, usually if the settlement date is known, it would normally be returned as part of the gateway response data.

Some examples are:

• Fatzebra/Paystream - Direct Post API

{
  "successful": true,
  "response": {
    "authorization": 1384819815,
    "id": "071-P-HZGZ9C4U",
    "card_number": "512345XXXXXX2346",
    "card_holder": "Jim Smith",
    "card_expiry": "2023-05-31",
    "card_token": "1tyyuywf",
    "amount": 1000,
    "decimal_amount": 10.0,
    "successful": true,
    "message": "Approved",
    "reference": "ORD9897615716",
    "currency": "AUD",
    "settlement_date": "2013-11-20",  // <== SETTLEMENT DATE
    "transaction_date": "2013-11-19T11:10:15+11:00",
  },
  "errors": [

  ],
  "test": true
}

• SecurePay - Secure XML API Integration

<?xml version="1.0" encoding="UTF-8"?>
<SecurePayMessage>
   <MessageInfo>
      <messageID>8af793f9af34bea0cf40f5fb750f64</messageID>
      <messageTimestamp>20162201113316084000+660</messageTimestamp>
      <apiVersion>xml4.2</apiVersion>
   </MessageInfo>
   <RequestType>Payment</RequestType>
   <MerchantInfo>
      <merchantID>ABC0001</merchantID>
   </MerchantInfo>
   <Status>
      <statusCode>000</statusCode>
      <statusDescription>Normal</statusDescription>
   </Status>
   <Payment>
      <TxnList count="1">
         <Txn ID="1">
            <txnType>0</txnType>
            <txnSource>23</txnSource>
            <amount>200</amount>
            <currency>AUD</currency>
            <purchaseOrderNo>test</purchaseOrderNo>
            <approved>Yes</approved>
            <responseCode>00</responseCode>
            <responseText>Approved</responseText>
            <settlementDate>20160122</settlementDate>  // <== SETTLEMENT DATE
            <txnID>374389</txnID>
            <CreditCardInfo>
               <pan>444433...111</pan>
               <expiryDate>09/10</expiryDate>
               <cardType>6</cardType>
               <cardDescription>Visa</cardDescription>
            </CreditCardInfo>
         </Txn>
      </TxnList>
   </Payment>
</SecurePayMessage>

As mentioned earlier, some responses will not contain a settlement date at all because the gateway simply doesn't return anything about it or the payment may not have settled yet.

On a side note (but not necessarily required), in cases where the settlement date cannot be directly retrieved from the response data, but the strategy for calculating the settlement date is known, the getTransactionSettlementDate() (implemented in the Commerce gateway) could do a manual calculation to return a settlement date. We've considered that in the past for a custom implementation, but it's not bullet proof!

With regards to showing the settlement date in the transaction row, I wasn't specifically asking for that to be done, but it would be useful if it were possible to show it there. Perhaps if there was some sort of template hook perhaps to allow adding custom columns into the transaction row.

[timeverts]

Hi @lukeholder, just picking up this discussion again (after a long time!) as I'll be needing to retrieve the settlement date of a transaction for an upcoming project. What further information do you require to investigate this request?