diff --git a/docs/backends.rst b/docs/backends.rst
index d7cf1c806..83d74fc53 100644
--- a/docs/backends.rst
+++ b/docs/backends.rst
@@ -312,12 +312,9 @@ These are the community providers compatible with ``django-payments``
* - `RazorPay `_
- IN
- `NyanKiyoshi/django-payments-razorpay `_
- * - `Flow Chile `_
+ * - Common providers from Chile
- CL
- - `mariofix/django-payments-flow `_
- * - `Khipu `_
- - CL
- - `mariofix/django-payments-khipu `_
+ - `mariofix/django-payments-chile `_
Creating a New Provider Backend
diff --git a/docs/webhooks.rst b/docs/webhooks.rst
index 44afcdee4..541929688 100644
--- a/docs/webhooks.rst
+++ b/docs/webhooks.rst
@@ -1,8 +1,7 @@
.. _webhooks:
Webhooks
-=================
-
+*********
Webhooks are a crucial component in connecting your Django Payments application
with external payment gateways like Stripe, PayPal, or Braintree. They enable
@@ -20,49 +19,25 @@ application's internal state, trigger actions, or send user notifications based
on payment-related events.
-Stripe
--------
+URL Structure
+=============
+The webhook URL structure in django-payments follows this pattern:
-Setting up Webhooks in Stripe
-To receive payment notifications and updates from Stripe, you need to set up
-webhooks. Follow these steps to configure webhooks in your Stripe Dashboard:
+``{protocol}://{host}/payments/process/{variant}/``
-* Log in to your `Stripe Dashboard `_.
-* In the left sidebar, click on **Developers** and then select **Webhooks**.
-* Click on the "+ Add endpoint" button to create a new webhook listener.
-* In the "Endpoint URL" field, enter the URL for the Stripe variant in your
- Django Payments application. This URL should be the endpoint where Stripe
- will send the webhook events. Make sure the URL is accessible from the
- internet. Example: ``https://your-app.com/payments/stripe/``.
-* From the "Events to send" dropdown, choose the specific events you want to
- receive notifications for. You need (at least) these events:
- * checkout.session.async_payment_failed
- * checkout.session.async_payment_succeeded
- * checkout.session.completed
- * checkout.session.expired
-* Click on the "Add endpoint" button to save your webhook listener.
-* Once the webhook is created, you will see its details in the "Webhooks"
- section. Take note of the "Signing secret" provided by Stripe as you will
- need it later when configuring the webhook handler in your Django application
-* Test the webhook by sending a test event to your endpoint. Stripe provides a
- "Send test webhook" button on the webhook details page. Use this feature to
- ensure your endpoint is correctly configured and can receive and process
- events from Stripe.
+Where:
-.. note::
+- ``{protocol}``: Configured in ``PAYMENT_PROTOCOL`` (typically "http" or "https")
+- ``{host}``: Configured in ``PAYMENT_HOST``
+- ``{variant}``: The name you've configured in PAYMENT_VARIANTS
- It's essential to secure your webhook endpoint and verify the authenticity of
- the events sent by Stripe. It's it not recomended to use `secure_endpoint`
- set to false in production.
-Make sure to replace **https://your-app.com/payments/stripe/** with the actual
-URL for your Stripe webhook endpoint. In this case, ``stripe`` is the `variant`
-of the configured provider. E.g.:
+For example, with this configuration:
.. code-block:: python
PAYMENT_VARIANTS = {
- 'stripe': ( # <-- This value
+ 'stripe': ( # <-- This is your variant name
'payments.stripe.StripeProviderV3',
{
'api_key': 'sk_test_123456',
@@ -72,3 +47,78 @@ of the configured provider. E.g.:
}
)
}
+
+ PAYMENT_HOST = 'your-app.com'
+ PAYMENT_PROTOCOL = 'https'
+
+Your webhook URL would be:
+``https://your-app.com/payments/process/stripe/``
+
+.. note::
+
+ Make sure the URL matches exactly, including the trailing slash. A common source
+ of 404 errors is using the wrong URL pattern or forgetting the trailing slash.
+
+
+Stripe
+======
+
+Setting up Webhooks in Stripe
+To receive payment notifications and updates from Stripe, you need to set up
+webhooks. Follow these steps to configure webhooks in your Stripe Dashboard:
+
+1. Log in to your `Stripe Dashboard `_.
+#. In the left sidebar, click on **Developers** and then select **Webhooks**.
+#. Click on the "+ Add endpoint" button to create a new webhook listener.
+#. In the "Endpoint URL" field, enter the URL for the Stripe variant in your
+ Django Payments application. This URL should follow the pattern:
+ ``https://your-app.com/payments/process/{variant}/``, where ``{variant}`` is
+ the name you've configured in your PAYMENT_VARIANTS setting.
+ For example: ``https://your-app.com/payments/process/stripe/``
+#. From the "Events to send" dropdown, choose the specific events you want to
+ receive notifications for. You need (at least) these events:
+
+ - checkout.session.async_payment_failed
+ - checkout.session.async_payment_succeeded
+ - checkout.session.completed
+ - checkout.session.expired
+
+#. Click on the "Add endpoint" button to save your webhook listener.
+#. Once the webhook is created, you will see its details in the "Webhooks"
+ section. Take note of the "Signing secret" provided by Stripe as you will
+ need it later when configuring the webhook handler in your Django application
+#. Test the webhook by sending a test event to your endpoint. Stripe provides a
+ "Send test webhook" button on the webhook details page. Use this feature to
+ ensure your endpoint is correctly configured and can receive and process
+ events from Stripe.
+
+
+Testing with Stripe CLI
+----------------------
+
+The `Stripe CLI `_ provides a simple
+way to test webhooks during local development by forwarding Stripe events to
+your local server. After installing and running ``stripe login``, you can start
+forwarding events to your local Django server with
+``stripe listen --forward-to localhost:8000/payments/process/stripe/``
+Use the webhook signing secret provided by the CLI in your development settings.
+
+.. code-block:: bash
+
+ # Start webhook forwarding
+ stripe listen --forward-to localhost:8000/payments/process/stripe/
+
+ # In another terminal, trigger test events
+ stripe trigger checkout.session.completed
+
+
+.. note::
+
+ It's essential to secure your webhook endpoint and verify the authenticity of
+ the events sent by Stripe. It's not recommended to use `secure_endpoint`
+ set to false in production.
+
+.. warning::
+
+ Remember to setup ``PAYMENT_HOST`` and ``PAYMENT_PROTOCOL`` in your settings file,
+ otherwise the webhooks won't work, as defined in :ref:`settings`.