diff --git a/www/apps/api-reference/specs/store/openapi.full.yaml b/www/apps/api-reference/specs/store/openapi.full.yaml index 471cf38111..68058fe97e 100644 --- a/www/apps/api-reference/specs/store/openapi.full.yaml +++ b/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.' diff --git a/www/apps/api-reference/specs/store/paths/store_payment-collections_{id}_payment-sessions.yaml b/www/apps/api-reference/specs/store/paths/store_payment-collections_{id}_payment-sessions.yaml index 39c8f7fc80..d92626515c 100644 --- a/www/apps/api-reference/specs/store/paths/store_payment-collections_{id}_payment-sessions.yaml +++ b/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 diff --git a/www/apps/resources/app/storefront-development/checkout/payment/page.mdx b/www/apps/resources/app/storefront-development/checkout/payment/page.mdx index 35fff0fc44..7a3161c7ab 100644 --- a/www/apps/resources/app/storefront-development/checkout/payment/page.mdx +++ b/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. diff --git a/www/apps/resources/app/storefront-development/checkout/payment/stripe/page.mdx b/www/apps/resources/app/storefront-development/checkout/payment/stripe/page.mdx index cd2f5d4159..f66e60450c 100644 --- a/www/apps/resources/app/storefront-development/checkout/payment/stripe/page.mdx +++ b/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/). diff --git a/www/apps/resources/app/troubleshooting/_sections/payment/zero-total.mdx b/www/apps/resources/app/troubleshooting/_sections/payment/zero-total.mdx new file mode 100644 index 0000000000..5bd1c14c9e --- /dev/null +++ b/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) \ No newline at end of file diff --git a/www/apps/resources/app/troubleshooting/payment/page.mdx b/www/apps/resources/app/troubleshooting/payment/page.mdx new file mode 100644 index 0000000000..1c495deef5 --- /dev/null +++ b/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 + + diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index 150620ef3b..20b9fb366c 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/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" } \ No newline at end of file diff --git a/www/apps/resources/generated/files-map.mjs b/www/apps/resources/generated/files-map.mjs index a16f665673..3150c15870 100644 --- a/www/apps/resources/generated/files-map.mjs +++ b/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" diff --git a/www/apps/resources/generated/generated-troubleshooting-sidebar.mjs b/www/apps/resources/generated/generated-troubleshooting-sidebar.mjs index 0c3dc4f321..a95a5c923d 100644 --- a/www/apps/resources/generated/generated-troubleshooting-sidebar.mjs +++ b/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": [] } ] }, diff --git a/www/apps/resources/sidebars/troubleshooting.mjs b/www/apps/resources/sidebars/troubleshooting.mjs index b153cc6067..940ae9015a 100644 --- a/www/apps/resources/sidebars/troubleshooting.mjs +++ b/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", + }, ], }, { diff --git a/www/utils/generated/oas-output/operations/store/post_store_payment-collections_[id]_payment-sessions.ts b/www/utils/generated/oas-output/operations/store/post_store_payment-collections_[id]_payment-sessions.ts index 1fe83bad56..42c2b32c37 100644 --- a/www/utils/generated/oas-output/operations/store/post_store_payment-collections_[id]_payment-sessions.ts +++ b/www/utils/generated/oas-output/operations/store/post_store_payment-collections_[id]_payment-sessions.ts @@ -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."