Define return parameters for doPayment

See #135 (closed), https://github.com/civicrm/civicrm-core/pull/18150 and https://github.com/civicrm/civicrm-core/pull/18178

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.

Ping @eileen @artfulrobot @KarinG