docs: add a troubleshooting section on creating a payment session with zero total (#12974)

2025-07-16 14:26:40 +03:00
parent 1797f0298b
commit 5527d95b5c
11 changed files with 129 additions and 6 deletions
@@ -278,6 +278,23 @@ In the `Fetch API` example, the `handlePayment` function implements this flow by

 ---

+## Troubleshooting
+
+### Unknown Error for Zero Cart Total
+
+If your cart has a total of `0`, you might encounter an `unknown error` when trying to create a payment session.
+
+Some payment providers, such as Stripe, require a non-zero amount to create a payment session. So, if your cart has a total of `0`, the error will be thrown on the payment provider's side.
+
+In those cases, you can either:
+
+- Make sure the payment session is only initialized when the cart has a total greater than `0`.
+- Use payment providers like the Manual System Payment Provider, which doesn't create a payment session with a third-party provider.
+    - The Manual System Payment Provider is available by default in Medusa and can be used to handle payments without a third-party provider. It allows you to mark the order as paid without requiring any additional actions from the customer.
+    - Make sure to configure the Manual System Payment Provider in your store's region. Learn more in the [Manage Region](!user-guide!/settings/regions#edit-region-details) user guide.
+
+---
+
 ## Stripe Example

 If you're integrating Stripe in your Medusa application and storefront, refer to the [Stripe guide](./stripe/page.mdx) for an example of how to handle the payment process using Stripe.
@@ -250,6 +250,23 @@ const getPaymentUi = useCallback(() => {

 ---

+## Troubleshooting
+
+### Unknown Error for Zero Cart Total
+
+If your cart has a total of `0`, you might encounter an `unknown error` when trying to create a payment session.
+
+Stripe requires a non-zero amount to create a payment session. So, if your cart has a total of `0`, the error will be thrown on Stripe's side.
+
+In those cases, you can either:
+
+- Make sure the payment session is only initialized when the cart has a total greater than `0`.
+- Use payment providers like the Manual System Payment Provider, which doesn't create a payment session with a third-party provider.
+    - The Manual System Payment Provider is available by default in Medusa and can be used to handle payments without a third-party provider. It allows you to mark the order as paid without requiring any additional actions from the customer.
+    - Make sure to configure the Manual System Payment Provider in your store's region. Learn more in the [Manage Region](!user-guide!/settings/regions#edit-region-details) user guide.
+
+---
+
 ## More Resources

 - [Stripe's documentation](https://docs.stripe.com/).