asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Shahed Nasser
2025-07-16 14:26:40 +03:00
committed by GitHub
parent 1797f0298b
commit 5527d95b5c
11 changed files with 129 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

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

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

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

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

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

31
www/apps/resources/app/troubleshooting/_sections/payment/zero-total.mdx Normal file
View File

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

11
www/apps/resources/app/troubleshooting/payment/page.mdx Normal file
View File

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

7
www/apps/resources/generated/edit-dates.mjs
View File

@@ -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"
}

4
www/apps/resources/generated/files-map.mjs
View File

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

8
www/apps/resources/generated/generated-troubleshooting-sidebar.mjs
View File

@@ -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": []
}
]
},

5
www/apps/resources/sidebars/troubleshooting.mjs
View File

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

11
www/utils/generated/oas-output/operations/store/post_store_payment-collections_[id]_payment-sessions.ts
View File

@@ -3,8 +3,17 @@
* 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
* 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."