WIP notes on custom integrations

docs/integration.md

@@ -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.
+