Define return parameters for doPayment

We need to clearly define what the return parameters for doPayment() should be as it's important, it's unclear and it's not defined anywhere.

My proposal:

doPayment($params) returns an array.
It must contain:
- payment_status_id: (deprecated) Numeric value of Contribution Status option value Completed or Pending. Eg. 1. Must be set but make sure you set payment_status as well because this value will be ignored in the future.
- payment_status: Text field - Either Completed or Pending.
It may contain (and the code that calls doPayment() will update these values on the contribution/payment:
- trxn_id: The transaction ID from the payment processor. This will be recorded in the Contribution.trxn_id field and the Payment.trxn_id field. We do not return order_reference here because that is usually filled in by an IPN callback from the payment processor if required.
- fee_amount: The amount (in same currency as contribution) of the fee taken by the payment processor for processing the payment.

Historically $params was passed by reference. This is deprecated and only the return values should be used.

Edited Aug 01, 2021 by mattwire

To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information