docs: add a troubleshooting section on creating a payment session with zero total (#12974)
This commit is contained in:
Shahed Nasser
@@ -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/).
|
||||
|
||||
@@ -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)
|
||||
@@ -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 />
|
||||
@@ -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"
|
||||
}
|
||||
@@ -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"
|
||||
|
||||
@@ -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": []
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -149,6 +149,11 @@ export const troubleshootingSidebar = [
|
||||
path: "/troubleshooting/s3",
|
||||
title: "S3 Module Provider Errors",
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
path: "/troubleshooting/payment",
|
||||
title: "Payment Provider Errors",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user