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

Author: shahednasser

www/apps/api-reference/specs/store/openapi.full.yaml

@@ -5114,7 +5114,11 @@ paths:
       operationId: PostPaymentCollectionsIdPaymentSessions
       summary: Initialize Payment Session of a Payment Collection
       x-sidebar-summary: Initialize Payment Session
-      description: Initialize and add a payment session to a payment collection. This is used during checkout, where you create a payment collection for the cart, then initialize a payment session for the payment provider that the customer chooses.
+      description: |
+        Initialize and add a payment session to a payment collection. This is used during checkout, where you create a payment collection for the cart, then initialize a payment session for the payment provider that the customer chooses.
+        It's highly recommended to have an amount greater than `0` in the payment collection, as some payment providers, such as Stripe, require a non-zero amount to create a payment session. Otherwise, an error will be thrown on the payment provider's side.
+        In cases where you want to create a payment session for a payment collection with an amount of `0`, you can use the Manual System Payment Provider instead of third-party payment providers. The Manual System Payment Provider is built into Medusa and allows you to create payment sessions without interacting with an external payment provider.
+        Make sure to configure the Manual System Payment Provider in your store's region. Learn more in the [Manage Region](https://docs.medusajs.com/user-guide/settings/regions#edit-region-details) user guide.
       externalDocs:
         url: https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment
         description: 'Storefront guide: How to implement payment during checkout.'

www/apps/api-reference/specs/store/paths/store_payment-collections_{id}_payment-sessions.yaml

@@ -2,11 +2,27 @@ post:
   operationId: PostPaymentCollectionsIdPaymentSessions
   summary: Initialize Payment Session of a Payment Collection
   x-sidebar-summary: Initialize Payment Session
-  description: >-
+  description: >
     Initialize and add a payment session to a payment collection. This is used
     during checkout, where you create a payment collection for the cart, then
     initialize a payment session for the payment provider that the customer
     chooses.
+
+    It's highly recommended to have an amount greater than `0` in the payment
+    collection, as some payment providers, such as Stripe, require a non-zero
+    amount to create a payment session. Otherwise, an error will be thrown on
+    the payment provider's side.
+
+    In cases where you want to create a payment session for a payment collection
+    with an amount of `0`, you can use the Manual System Payment Provider
+    instead of third-party payment providers. The Manual System Payment Provider
+    is built into Medusa and allows you to create payment sessions without
+    interacting with an external payment provider.
+
+    Make sure to configure the Manual System Payment Provider in your store's
+    region. Learn more in the [Manage
+    Region](https://docs.medusajs.com/user-guide/settings/regions#edit-region-details)
+    user guide.
   externalDocs:
     url: >-
       https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment

www/apps/resources/app/storefront-development/checkout/payment/page.mdx

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

www/apps/resources/app/storefront-development/checkout/payment/stripe/page.mdx

@@ -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/).

www/apps/resources/app/troubleshooting/_sections/payment/zero-total.mdx

@@ -0,0 +1,31 @@
+If your cart has a total of `0`, you might encounter an `unknown error` when trying to create a payment session.
+
+## Why this Error Occurred
+
+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.
+
+## Solutions
+
+### Initialize Payment Session Only for Non-Zero Totals
+
+Make sure the payment session is only initialized when the cart has a total greater than `0`. You can add a check before creating the payment session:
+
+```ts
+if (cart.total > 0) {
+  // TODO Initialize payment session
+}
+```
+
+### Use Manual System Payment Provider
+
+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.
+
+---
+
+## Additional Resources
+
+- [Payment Providers](../../../commerce-modules/payment/payment-provider/page.mdx)

www/apps/resources/app/troubleshooting/payment/page.mdx

@@ -0,0 +1,11 @@
+import ZeroTotalError from "../_sections/payment/zero-total.mdx"
+
+export const metadata = {
+  title: `Payment Provider Errors`,
+}
+
+# {metadata.title}
+
+## Unknown Error for Zero Cart Total
+
+<ZeroTotalError />

www/apps/resources/generated/edit-dates.mjs

@@ -143,8 +143,8 @@ export const generatedEditDates = {
   "app/storefront-development/checkout/address/page.mdx": "2025-03-27T14:47:14.265Z",
   "app/storefront-development/checkout/complete-cart/page.mdx": "2025-03-27T14:47:14.277Z",
   "app/storefront-development/checkout/email/page.mdx": "2025-03-27T14:47:14.283Z",
-  "app/storefront-development/checkout/payment/stripe/page.mdx": "2025-05-20T07:51:40.724Z",
-  "app/storefront-development/checkout/payment/page.mdx": "2025-03-27T14:47:14.274Z",
+  "app/storefront-development/checkout/payment/stripe/page.mdx": "2025-07-16T10:18:44.916Z",
+  "app/storefront-development/checkout/payment/page.mdx": "2025-07-16T10:18:47.607Z",
   "app/storefront-development/checkout/shipping/page.mdx": "2025-03-27T14:47:14.270Z",
   "app/storefront-development/checkout/page.mdx": "2024-06-12T19:46:06+02:00",
   "app/storefront-development/customers/addresses/page.mdx": "2025-03-27T14:47:14.252Z",
@@ -6556,5 +6556,6 @@ export const generatedEditDates = {
   "references/types/interfaces/types.UpdatePaymentOutput/page.mdx": "2025-06-25T10:11:39.945Z",
   "app/how-to-tutorials/tutorials/gift-message/page.mdx": "2025-06-26T09:13:19.296Z",
   "app/how-to-tutorials/tutorials/re-order/page.mdx": "2025-06-26T12:38:24.308Z",
-  "app/commerce-modules/promotion/promotion-taxes/page.mdx": "2025-06-27T15:44:46.638Z"
+  "app/commerce-modules/promotion/promotion-taxes/page.mdx": "2025-06-27T15:44:46.638Z",
+  "app/troubleshooting/payment/page.mdx": "2025-07-16T10:20:24.799Z"
 }

www/apps/resources/generated/files-map.mjs

@@ -1383,6 +1383,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/page.mdx",
     "pathname": "/troubleshooting"
   },
+  {
+    "filePath": "/www/apps/resources/app/troubleshooting/payment/page.mdx",
+    "pathname": "/troubleshooting/payment"
+  },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/query/expression-type-error/page.mdx",
     "pathname": "/troubleshooting/query/expression-type-error"

www/apps/resources/generated/generated-troubleshooting-sidebar.mjs

@@ -223,6 +223,14 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
           "path": "/troubleshooting/s3",
           "title": "S3 Module Provider Errors",
           "children": []
+        },
+        {
+          "loaded": true,
+          "isPathHref": true,
+          "type": "link",
+          "path": "/troubleshooting/payment",
+          "title": "Payment Provider Errors",
+          "children": []
         }
       ]
     },

www/apps/resources/sidebars/troubleshooting.mjs

@@ -149,6 +149,11 @@ export const troubleshootingSidebar = [
         path: "/troubleshooting/s3",
         title: "S3 Module Provider Errors",
       },
+      {
+        type: "link",
+        path: "/troubleshooting/payment",
+        title: "Payment Provider Errors",
+      },
     ],
   },
   {