Commit 32f62b4c authored by Rich's avatar Rich Committed by mattwire
Browse files

WIP notes on custom integrations

parent a37c5ffe
......@@ -23,3 +23,128 @@ For recurring payments make sure that:
1. You have either "Number of installments" or "Interval of installments" element on the same "page" as the payment.
2. The elements are either visible or hidden (hidden element) - do NOT select hidden (secure value) as it won't work.
## Custom integrations
These notes cover how to create Stripe payments and subscriptions without using CiviCRM's Contribution pages.
### Create a new recurring contribution / subscription.
In your front end, collect the card details using Stripe Elements, and using Stripe's JS APIs get a `paymentMethodID`.
In the back end:
#### Create a pending ContributionRecur and a pending Order (Contribution).
e.g.
```php
<?php
$contributionRecurID = civicrm_api3('ContributionRecur', 'create', [
'amount' => 1.00,
'contact_id' => 12345,
'contribution_status_id' => "Pending",
'currency' => 'GBP',
'financial_type_id' => 1,
'frequency_interval' => 1,
'frequency_unit' => "month",
'is_test' => 1,
'payment_processor_id' => $stripeTestPayProcessorID,
])['id'];
$orderCreateParams = [
'receive_date' => date('Y-m-d H:i:s'),
'total_amount' => 1.00,
'contact_id' => 12345,
"payment_instrument_id" => 1,
'currency' => 'GBP',
'financial_type_id' => 1,
'contribution_recur_id' => $contributionRecurID,
'contribution_status_id' => 'Pending',
'is_test' => 1,
'line_items' => [
[
'line_item' => [[
'line_total' => 1
'unit_price' => 1,
"price_field_id" => 1,
'financial_type_id' => 1,
'qty' => 1,
]]
]
],
];
civicrm_api3('Order', 'create', $orderCreateParams);
```
#### Call `CRM_Core_Payment_Stripe::doPayment()`
Then assemble the inputs for Stripe's `doPayment()` in a PropertyBag and call it.
This will create all the Stripe-specific structures that are needed: a
Customer, a Plan and a Subscription. It will also save the card
(paymentMethodID) to the customer.
The subscription, (unless you set a future start date) will have an invoice,
and that invoice will have a payment intent.
The payment intent is automatically captured, if possible.
e.g.
```php
<?php
/** @var CRM_Core_Payment_Stripe */
$paymentProcessor = getTheStripePaymentObject();
/** @var array */
$input = getTheInputData();
$doPaymentParams = new \Civi\Payment\PropertyBag();
$doPaymentParams->setCustomProperty('paymentMethodID', $input['paymentMethodID']);
$doPaymentParams->setContactID($input['contactID']);
$doPaymentParams->setContributionID($input['contributionID']);
$doPaymentParams->setIsRecur(TRUE);
$doPaymentParams->setRecurFrequencyUnit('month');
$doPaymentParams->setContributionRecurID($input['contributionRecurID']);
$doPaymentParams->setAmount($input['amount']);
$doPaymentParams->setEmail($input['email']);
$doPaymentParams->setDescription($input['description']);
$result = $paymentProcessor->doPayment($doPaymentParams);
```
##### Observations I suspect need discussion
`doPayment` does not notice if the payment is captured (it assumes not)
and will record only the invoice ID as the Contribution's `trxn_id`.
`doPayment` returns an array of fairly mixed stuff:
- Some Contribution fields which may or may not be up-to-date (e.g.
`contribution_status_id` is set to the value for *Pending*, unless a
different value was passed in, yet the contribution status may have since
been updated to *Completed* by IPN or `StripePaymentintent.process`)
- Some left-over API parameters (e.g. `skipCleanMoney`).
- To get the real result you'll need to disregard the data returned from
`doPayment` and reload the objects, just using their IDs. From there you can
see whether you have a payment intent yet, and what state it is in.
#### Check for SCA requirements
If you’re lucky (and if you didn't set a future start date), everything will
have gone through. But often you’ll need to do Secure Customer Authentication (SCA).
This is identified by the payment intent having a status of `requires_action`
and you’ll need to pass `paymentIntentID` and `paymentIntentClientSecret` back to
your Javascript which will need to use the Stripe APIs to handle that.
In this case, after handling the SCA, assuming successful, the payment intent
at Stripe will have moved on, possibly to status `needs_capture`, or
`completed`. CiviCRM will be told about this by an IPN call. As we need to
allow for the `needs_capture` case, your Javascript must now call
`StripePaymentintent.process`, passing the `paymentIntentID`. This will see
what needs doing, do it, and update CiviCRM records.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment