Document the different ways of using stripe.js Elements (dj-stripe#1038)

ryancausey · Oct 23, 2019 · cd4daee · cd4daee
1 parent 025f4df
commit cd4daee
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 0 deletions.
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -55,6 +55,12 @@ Warning about safe uninstall of jsonfield on upgrade
 .. _jsonfield: https://github.com/dmkoch/django-jsonfield/
 .. _jsonfield2: https://github.com/rpkilby/jsonfield2/
 
+Note on usage of Stripe Elements JS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+See https://dj-stripe.readthedocs.io/en/latest/stripe_elements_js.html for notes about
+usage of the Stripe Elements frontend JS library.
+
+TLDR: if you haven't yet migrated to PaymentIntents, prefer ``stripe.createSource()`` to ``stripe.createToken()``.
 
 
 2.1.1 (2019-10-01)

diff --git a/README.rst b/README.rst
@@ -89,6 +89,8 @@ Run the commands::
 
     python manage.py djstripe_sync_plans_from_stripe
 
+See https://dj-stripe.readthedocs.io/en/latest/stripe_elements_js.html for notes about
+usage of the Stripe Elements frontend JS library.
 
 Running the Tests
 ------------------

diff --git a/docs/index.rst b/docs/index.rst
@@ -21,6 +21,7 @@ Contents
 
    installation
    api_versions
+   stripe_elements_js
 
 .. toctree::
    :caption: Usage

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -53,6 +53,9 @@ Run the commands::
 
     python manage.py djstripe_sync_plans_from_stripe
 
+See https://dj-stripe.readthedocs.io/en/latest/stripe_elements_js.html for notes about
+usage of the Stripe Elements frontend JS library.
+
 Running Tests
 --------------
 

diff --git a/docs/stripe_elements_js.rst b/docs/stripe_elements_js.rst
@@ -0,0 +1,48 @@
+A note on Stripe Elements JS methods
+====================================
+
+.. note::
+  TLDR: If you haven't yet migrated to PaymentIntents,
+  prefer ``stripe.createSource()`` over ``stripe.createToken()`` for better compatibility with PaymentMethods.
+
+
+A point that can cause confusion when integrating Stripe on the web is that there
+are multiple generations of frontend JS APIs that use Stripe Elements with stripe js v3.
+
+In descending order of preference these are:
+
+Payment Intents (SCA compliant)
+-------------------------------
+
+The newest and preferred way of handling payments, which supports SCA compliance (3D secure etc).
+
+See https://stripe.com/docs/payments/payment-intents/web
+
+
+Charges using stripe.createSource()
+-----------------------------------
+
+This creates Source objects within Stripe, and can be used for various different
+methods of payment (including, but not limited to cards), but isn't SCA compliant.
+
+See https://stripe.com/docs/stripe-js/reference#stripe-create-source
+
+The `Card Elements Quickstart JS`_ example can be used, except use ``stripe.createSource`` instead of ``stripe.createToken``
+and the ``result.source``  instead of ``result.token``.
+
+See https://github.com/dj-stripe/dj-stripe/blob/master/tests/apps/example/templates/purchase_subscription.html
+in for a working example of this.
+
+
+Charges using stripe.createToken()
+----------------------------------
+
+This predates ``stripe.createSource``, and creates legacy Card objects within Stripe,
+which have some compatibility issues with Payment Methods.
+
+If you're using ``stripe.createToken``, see if you can upgrade to ``stripe.createSource``
+or ideally to Payment Intents .
+
+See `Card Elements Quickstart JS`_
+
+.. _Card Elements Quickstart JS: https://stripe.com/docs/payments/cards/collecting/web