From 2e4fc675ef15748225939cac901ef58f8da63450 Mon Sep 17 00:00:00 2001 From: Eileen McNaughton Date: Sun, 20 Oct 2019 11:37:10 +1300 Subject: [PATCH] Add documentation about how to migrate off transact api --- docs/financial/OrderAPI.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/financial/OrderAPI.md b/docs/financial/OrderAPI.md index 5594f74a..e6680557 100644 --- a/docs/financial/OrderAPI.md +++ b/docs/financial/OrderAPI.md @@ -327,3 +327,37 @@ Notes: Here is how to create an order for a membership, an event registration, and two separate contribution line items. [ Rich to provide] + +## Transitioning from Contribution.transact api to Order api + +Contribution.transact api was a v2 api that we left in place in v3. It has never had unit tests & has never been supported. Unfortunately by not being more aggressive about deprecating it some sites have adopted it. + +The Contribution.transact api will create a 'simple' contribution and process a payment. It will not create the line items correctly for anything other than a straight forward donation and does not follow our practice of creating a pending contribution and then adding a payment. It's likely there are other unknown gaps in how it works. + +The simplest first step to migrate off it is to replace the order api call with a call that follows the recommended flow but still does not address the line item creation gaps & it is recommended you look at the patterns above to do that. This first step looks like + +``` +# start with the same parameters as Contribution.transact. +$params = $transactParams; +# it would be better just to include the relevant params but.... +$paymentParams = $transactParams; +$params['contribution_status_id'] = 'Pending'; +if (!isset($params['invoice_id')) { + // Set an invoice_id here if you have not already done so. + // Potentially Order api should do this https://lab.civicrm.org/dev/financial/issues/78 +} +if (!isset($params['invoiceID']) { + // This would be required prior to https://lab.civicrm.org/dev/financial/issues/77 + $params['invoiceID'] = $params['invoice_id']; +} +$order = civicrm_api3('Order', 'create' $params); +try { + civicrm_api3('PaymentProcessor', 'pay', ['contribution_id' => $order['id']]); + civicrm_api3('Payment', 'create', ['contribution_id' => $order['id'], 'amount' => $params['amount']]); +} +catch { + // it failed +} +``` + +The above is a few more lines but it is an important step towards transitioning to a supported method and away from a flawed api.