GitLab

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() returns an array.
• It must contain:
  • payment_status_id. Either Completed or Pending. We would like to transition to returning payment_status = Completed|Pending (1) so you should define that when setting return values for doPayment() now.
• 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. Currently will be set on contribution (but won't in future or will be added as comma separated list, deprecated). Will be set on Payment.trxn_id.
  • order_reference: This is a new parameter added around CiviCRM 5.20(?check), it will be set on the Payment.order_reference and is used to represent the invoice/order number from the payment processor.
  • fee_amount: The amount (in same currency as contribution) of the fee taken by the payment processor for processing the payment.
• Parameters that will be ignored (but may not be currently, needs investigation):
  • total_amount: It is not supported to change this during doPayment() and the calling code should use the value it passes in rather than the return value.

(1): It might be preferable to use constants instead of strings? eg. CRM_Core_Payment::COMPLETED, ::PENDING. These will only ever be for internal use.

Ping @eileen @artfulrobot @KarinG