Spryker Documentation

Install the Purchasing Control feature

Fri, 17 Apr 2026 14:22:26 +0000

{% info_block warningBox "Experimental feature" %} Experimental feature - not recommended for production use. {% endinfo_block %} This document describes how to install the [Purchasing Control feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/purchasing-control-feature-overview.html). ## Install feature core Follow the steps below to install the Purchasing Control feature core. ### Prerequisites To start feature integration, review and install the necessary features: | NAME | VERSION | INSTALLATION GUIDE | | --- | --- | --- | | Spryker Core | {{page.release_tag}} | [Install the Spryker Core feature](/docs/pbc/all/miscellaneous/latest/install-and-upgrade/install-features/install-the-spryker-core-feature.html) | | Company Account | {{page.release_tag}} | [Install the Company Account feature](/docs/pbc/all/customer-relationship-management/latest/base-shop/install-and-upgrade/install-features/install-the-company-account-feature.html) | | Checkout | {{page.release_tag}} | [Install the Checkout feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-checkout-feature.html) | | Approval Process | {{page.release_tag}} | [Install the Approval Process feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-approval-process-feature.html) | ### 1) Install the required modules ```bash composer require spryker-feature/purchasing-control:"^0.1.0" spryker-shop/checkout-page:"^3.40.0" --update-with-dependencies ``` ### 2) Set up database schema and transfer objects Apply database changes and generate entity and transfer changes: ```bash console propel:install console transfer:generate ``` {% info_block warningBox "Verification" %} Make sure the following changes have been applied in the database: | DATABASE ENTITY | TYPE | EVENT | | --- | --- | --- | | spy_cost_center | table | created | | spy_cost_center_to_company_business_unit | table | created | | spy_budget | table | created | | spy_budget_consumption | table | created | | spy_quote.fk_cost_center | column | created | | spy_quote.fk_budget | column | created | | spy_sales_order.fk_cost_center | column | created | | spy_sales_order.fk_budget | column | created | Make sure the following changes have been applied in transfer objects: | TRANSFER | TYPE | EVENT | PATH | | --- | --- | --- | --- | | CostCenter | class | created | src/Generated/Shared/Transfer/CostCenterTransfer.php | | CostCenterCollection | class | created | src/Generated/Shared/Transfer/CostCenterCollectionTransfer.php | | CostCenterCriteria | class | created | src/Generated/Shared/Transfer/CostCenterCriteriaTransfer.php | | CostCenterResponse | class | created | src/Generated/Shared/Transfer/CostCenterResponseTransfer.php | | Budget | class | created | src/Generated/Shared/Transfer/BudgetTransfer.php | | BudgetCollection | class | created | src/Generated/Shared/Transfer/BudgetCollectionTransfer.php | | BudgetCriteria | class | created | src/Generated/Shared/Transfer/BudgetCriteriaTransfer.php | | BudgetResponse | class | created | src/Generated/Shared/Transfer/BudgetResponseTransfer.php | | BudgetConsumption | class | created | src/Generated/Shared/Transfer/BudgetConsumptionTransfer.php | | Quote.idCostCenter | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.idBudget | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.costCenter | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | | Quote.budget | property | created | src/Generated/Shared/Transfer/QuoteTransfer.php | {% endinfo_block %} ### 3) Set up behavior Enable the following behaviors by registering the plugins. #### Set up Zed plugins | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | BudgetCheckoutPreConditionPlugin | Validates the cart grand total against the remaining budget before checkout proceeds. Blocks checkout or triggers the approval flow depending on the budget enforcement rule. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | CostCenterOrderSaverPlugin | Saves the selected cost center and budget references to the sales order during checkout. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | ConsumeBudgetCheckoutPostSavePlugin | Records budget consumption immediately after the order is saved so the remaining budget balance is accurate for concurrent buyers. Does nothing when no budget is selected on the quote. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Checkout | | CostCenterQuoteExpanderPlugin | Expands the quote with the default cost center assigned to the buyer's business unit when no cost center is already set. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Quote | | CostCenterQuoteFieldsAllowedForSavingProviderPlugin | Adds `idCostCenter` and `idBudget` to the list of quote fields persisted to the database. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Quote | | RestoreBudgetOmsCommandPlugin | Deletes all budget consumption records for a sales order when the order is cancelled, restoring the consumed budget amount. | None | SprykerFeature\Zed\PurchasingControl\Communication\Plugin\Oms | **src/Pyz/Zed/Checkout/CheckoutDependencyProvider.php** ```php */ protected function getCheckoutPreConditions(Container $container): array { return [ // ... new BudgetCheckoutPreConditionPlugin(), #PurchasingControlFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\Checkout\Dependency\Plugin\CheckoutSaveOrderInterface|\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutDoSaveOrderInterface> */ protected function getCheckoutOrderSavers(Container $container): array { return [ // ... new CostCenterOrderSaverPlugin(), #PurchasingControlFeature ]; } /** * @param \Spryker\Zed\Kernel\Container $container * * @return list<\Spryker\Zed\CheckoutExtension\Dependency\Plugin\CheckoutPostSaveInterface> */ protected function getCheckoutPostHooks(Container $container): array { return [ // ... new ConsumeBudgetCheckoutPostSavePlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} When a buyer places an order with a budget selected, verify the following: - Checkout is blocked when the order exceeds a budget with the **Block** enforcement rule. - An approval request is triggered when the order exceeds a budget with the **Require Approval** rule. - A warning is displayed when the order exceeds a budget with the **Warn** rule. - A `spy_budget_consumption` record is created after the order is successfully placed. - The cost center and budget IDs are saved on the `spy_sales_order` record. {% endinfo_block %} **src/Pyz/Zed/Quote/QuoteDependencyProvider.php** ```php */ protected function getQuoteExpanderPlugins(): array { return [ // ... new CostCenterQuoteExpanderPlugin(), #PurchasingControlFeature ]; } /** * @return array<\Spryker\Zed\QuoteExtension\Dependency\Plugin\QuoteFieldsAllowedForSavingProviderPluginInterface> */ protected function getQuoteFieldsAllowedForSavingProviderPlugins(): array { return [ // ... new CostCenterQuoteFieldsAllowedForSavingProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} When a buyer with an assigned business unit opens a cart, make sure the quote is automatically expanded with the default cost center of their business unit. Make sure `idCostCenter` and `idBudget` are persisted to the `spy_quote` table when the quote is saved. {% endinfo_block %} **src/Pyz/Zed/Oms/OmsDependencyProvider.php** ```php extend(self::COMMAND_PLUGINS, function (CommandCollectionInterface $commandCollection) { // ... $commandCollection->add(new RestoreBudgetOmsCommandPlugin(), 'CostCenter/RestoreBudget'); #PurchasingControlFeature return $commandCollection; }); return $container; } } ``` {% info_block warningBox "Verification" %} When an order transitions to a cancelled state and the `CostCenter/RestoreBudget` OMS command runs, make sure the corresponding `spy_budget_consumption` records are deleted and the budget balance is restored. {% endinfo_block %} ### 4) Configure Back Office navigation Add the Purchasing Control section to the Back Office navigation: **config/Zed/navigation.xml** ```xml ... ... Purchasing Control Purchasing Control purchasing-control cost-center index ``` Rebuild the navigation cache: ```bash console navigation:build-cache ``` {% info_block warningBox "Verification" %} In the Back Office, under **Customers**, make sure the **Purchasing Control** menu item is displayed and links to the cost center list page. {% endinfo_block %} ### 5) Configure the OMS process Add the `CostCenter/RestoreBudget` command to the `cancel` event in your OMS process XML. The following example uses `DummyPayment01`: **config/Zed/oms/DummyPayment01.xml** ```xml ... ... ``` {% info_block warningBox "Verification" %} In the Back Office, open a placed order and trigger the **cancel** event. Make sure the `spy_budget_consumption` records for the order are deleted and the budget balance is restored. {% endinfo_block %} ## Install feature frontend Follow the steps below to install the Purchasing Control feature frontend. ### 1) Import data Import the following glossary keys for Storefront translations: **data/import/common/common/glossary.csv** ```csv purchasing_control.selector.placeholder,Select cost center,en_US purchasing_control.selector.placeholder,Kostenstelle wählen,de_DE purchasing_control.budget.selector.label,Budget,en_US purchasing_control.budget.selector.label,Budget,de_DE purchasing_control.budget.selector.placeholder,Select budget,en_US purchasing_control.budget.selector.placeholder,Budget wählen,de_DE purchasing_control.budget.remaining,Remaining budget,en_US purchasing_control.budget.remaining,Verbleibendes Budget,de_DE purchasing_control.summary.cost_center_label,Cost Center,en_US purchasing_control.summary.cost_center_label,Kostenstelle,de_DE purchasing_control.summary.budget_label,Budget,en_US purchasing_control.summary.budget_label,Budget,de_DE purchasing_control.summary.budget_remaining,remaining,en_US purchasing_control.summary.budget_remaining,verbleibend,de_DE purchasing_control.validation.block,"Your order exceeds the allocated budget. Please adjust your order or contact your manager.",en_US purchasing_control.validation.block,"Ihre Bestellung überschreitet das zugewiesene Budget. Bitte passen Sie Ihre Bestellung an oder kontaktieren Sie Ihren Manager.",de_DE purchasing_control.validation.warn,Your order exceeds the allocated budget.,en_US purchasing_control.validation.warn,Ihre Bestellung überschreitet das zugewiesene Budget.,de_DE purchasing_control.validation.require-approval,This order exceeds the budget. Please send it for approval.,en_US purchasing_control.validation.require-approval,Diese Bestellung überschreitet das Budget. Bitte senden Sie sie zur Genehmigung.,de_DE purchasing_control.validation.required,"Please select a cost center and budget before placing your order.",en_US purchasing_control.validation.required,"Bitte wählen Sie vor der Bestellung eine Kostenstelle und ein Budget aus.",de_DE ``` Import data: ```bash console data:import:glossary ``` {% info_block warningBox "Verification" %} Make sure that, in the database, the configured data has been added to the `spy_glossary_key` and `spy_glossary_translation` tables. {% endinfo_block %} ### 2) Set up widgets Register the following global widgets: | WIDGET | DESCRIPTION | NAMESPACE | | --- | --- | --- | | CostCenterSelectorWidget | Renders the cost center and budget selection UI in the cart or checkout. | SprykerFeature\Yves\PurchasingControl\Widget | **src/Pyz/Yves/ShopApplication/ShopApplicationDependencyProvider.php** ```php */ protected function getGlobalWidgets(): array { return [ // ... CostCenterSelectorWidget::class, #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} Make sure the `CostCenterSelectorWidget` widget is available in Twig templates. {% endinfo_block %} ### 3) Extend the checkout summary template Add the `CostCenterSelectorWidget` to the checkout summary page, placing it directly above the `QuoteApprovalWidget` call: **src/SprykerShop/CheckoutPage/src/SprykerShop/Yves/CheckoutPage/Theme/default/views/summary/summary.twig** ```twig

{% raw %}{% widget 'CostCenterSelectorWidget' args [data.cart] only %}{% endwidget %}{% endraw %} {% raw %}{% widget 'QuoteApprovalWidget' args [data.cart] only %}{% endwidget %}{% endraw %}

``` {% info_block warningBox "Verification" %} On the checkout summary page, make sure the cost center and budget selector is displayed above the approval widget. {% endinfo_block %} ### 4) Set up routes Register the following route provider plugin: | PLUGIN | SPECIFICATION | PREREQUISITES | NAMESPACE | | --- | --- | --- | --- | | CostCenterRouteProviderPlugin | Adds the `POST /cost-center/update-quote` route, which handles cost center and budget selection form submissions from the cart or checkout. | None | SprykerFeature\Yves\PurchasingControl\Plugin\Router | **src/Pyz/Yves/Router/RouterDependencyProvider.php** ```php */ protected function getRouteProvider(): array { return [ // ... new CostCenterRouteProviderPlugin(), #PurchasingControlFeature ]; } } ``` {% info_block warningBox "Verification" %} Make sure the route `cost-center-update-quote` is accessible and that submitting the cost center selector form in the cart updates the quote with the selected cost center and budget. {% endinfo_block %}

Purchasing Control feature overview

Fri, 17 Apr 2026 14:20:09 +0000

The *Purchasing Control* feature lets B2B companies track and control procurement spending by assigning orders to cost centers and enforcing configurable budget rules. It extends the existing [Approval Process](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/approval-process-feature-overview.html) with a second dimension of spending governance: per-department or per-project budget limits that work alongside the existing per-person permission limits. {% info_block infoBox "Info" %} This feature is available in the Back Office and on the Storefront. {% endinfo_block %} ## Cost centers A *cost center* is an organizational unit within a company that incurs costs but does not directly generate revenue. Companies use cost centers to track and control spending by department, project, location, or function. **Common examples:** - **Departmental:** Marketing, Engineering, HR, Facilities - **Project-based:** Office Renovation Q2 2026, Trade Show Berlin - **Location-based:** Warehouse Berlin, Office London Every purchase a buyer makes is charged to a cost center so the company can track where money is being spent. In ERP systems such as SAP, Oracle, and Microsoft Dynamics, cost centers are a foundational accounting concept - orders flow into the ERP tagged with a cost center code, enabling financial reporting and cost allocation. ## Budgets A *budget* is a spending limit assigned to a cost center for a defined period - monthly, quarterly, or annually. It represents the maximum amount that a department or project is authorized to spend in that period. **Example:** The Marketing department has a quarterly procurement budget of €50,000 for office supplies and event materials. Once that budget is consumed, further purchases are either blocked, flagged for review, or escalated for approval. ### Budget enforcement rules Each budget is configured with one of three enforcement rules: | RULE | DESCRIPTION | | --- | --- | | Block | The order is rejected outright when the budget is exceeded. The buyer cannot proceed to checkout. | | Warn | A warning is displayed to the buyer, but they can proceed. | | Require Approval | The order is sent for approval when the budget is exceeded. The buyer cannot complete checkout until an approver accepts the order. | ## Relationship to the Approval Process Spryker's existing Approval Process triggers a workflow when a buyer's order exceeds their *Buy up to grand total* permission. The Purchasing Control feature adds a parallel check: an order might be within a buyer's personal permission limit but still exceed the cost center's remaining budget. Both checks run independently at checkout. If either the permission limit or the budget rule is triggered, the configured action - block, warn, or require approval - is applied. This gives companies layered spending governance: per-person limits *and* per-department or per-project limits. {% info_block warningBox "Approvals within a business unit" %} Approvers can only approve orders of employees within their own business unit. This constraint applies to both permission-based and budget-based approval requests. {% endinfo_block %} ## Cost centers and budgets in the procurement workflow The typical B2B procurement flow involving cost centers and budgets: 1. **Finance sets budgets.** At the start of a fiscal period, finance allocates budgets to each cost center. 2. **Buyers are assigned to cost centers.** Buyers are linked to one or more cost centers they are authorized to purchase against. Cost centers are linked to company business units, so all users in a business unit are automatically assigned to the corresponding cost centers. 3. **Orders are tagged.** At checkout, the buyer selects which cost center the purchase is charged to. The system automatically selects the active budget for that cost center: - If exactly one active budget is available - it is selected automatically. - If multiple budgets are available - the buyer selects from a dropdown. 4. **Budget is validated.** The system checks whether the order total fits within the remaining budget for the selected cost center. 5. **Enforcement rules apply.** Based on the configured rule, the order is blocked, a warning is shown, or approval is required. 6. **Budget is consumed.** Once the order is confirmed, the budget balance is reduced by the order amount. 7. **Budget is restored.** If the order is cancelled, the consumed amount is returned to the budget balance. ## Checkout validation outcomes | SCENARIO | OUTCOME | | --- | --- | | Within budget and within permission limit | Buyer completes checkout without additional steps. | | Exceeds budget - Warn rule | A warning is displayed; the buyer proceeds but the order requires approval. | | Exceeds budget - Require Approval rule | The order is sent for approval; the buyer cannot complete checkout until approved. | | Exceeds Buy up to grand total permission limit | The order is sent for approval, same as the standard Approval Process. | | Exceeds budget - Block rule | Checkout is blocked; no approval option is available. | ## Quote lock When an order is sent for approval - whether triggered by a budget rule or a permission limit - the quote is locked to preserve the order state during the approval review. Neither the buyer nor the approver can modify the quote while it is pending approval. For details, see [Quote lock functionality](/docs/pbc/all/cart-and-checkout/latest/base-shop/feature-overviews/approval-process-feature-overview.html#quote-lock-functionality). ## Roles and capabilities | ROLE | CAPABILITIES | | --- | --- | | Company Admin (Back Office) | Create, update, activate, and deactivate cost centers. Assign cost centers to business units. Create and manage budgets with amount, period, currency, and enforcement rule. View spend-vs-budget reports. Export reports to CSV. Review the audit log. | | Buyer (Storefront) | Select a cost center and budget at checkout. View remaining budget for the selected cost center. Submit orders for approval when required. | | Approver (Storefront) | Review locked quotes pending approval. Approve or reject orders, including those triggered by budget rules. | ## Related Developer documents | INSTALLATION GUIDES | | --- | | [Install the Purchasing Control feature](/docs/pbc/all/cart-and-checkout/latest/base-shop/install-and-upgrade/install-features/install-the-purchasing-control-feature.html) |

Stripe

Thu, 16 Apr 2026 13:59:55 +0000

[Stripe](https://stripe.com/en-de) is a financial infrastructure platform that enables businesses to accept payments, grow their revenue, and accelerate new business opportunities. The Stripe integration in Spryker is part of [Spryker ecosystem](/docs/integrations/eco-modules) and supports both the default Storefront Yves and Spryker GLUE APIs. ## Supported business models The Stripe module supports B2B, B2C, and Marketplace models. ## Stripe features - Interface within the Back Office to configure API keys. - Support of test (sandbox) or live credentials. - Storefront Payment Page: when the Stripe payment method is configured, after order submission end users are presented with the Stripe Elements payment form where they can select and complete their payment. This works both on the web and mobile. - Viewing the activated payment methods in the Stripe dashboard. - GLUE API support: Support for customers using Spryker headless. - Authorize payments and capture later: The default OMS configuration lets you authorize cards and capture the order amount either after shipping or based on the established business logic. - Default OMS Configuration: We provide default OMS configurations (for regular ecommerce sites and marketplaces) that you can use as an example or modify to align with your business logic. ## Stripe payment methods The Stripe module supports all payments enabled by Stripe in your region. For more information, see [Payment methods in Stripe](https://stripe.com/docs/payments/payment-methods/overview). However, our team only tested the following payment methods: - Cards: including Visa and Mastercard - Debit card - Bank transfer: supported in some regions, see [Bank transfer payments](https://stripe.com/docs/payments/bank-transfers) - PayPal - Klarna - Apple Pay - Google Pay - Direct Debit (SEPA) / Sofortüberweisung - iDEAL - Link - Przelewy24 - Giropay - US, UK, CA, AU, NZ: AfterPay ## Current limitations - Partial capture of payment for orders with multiple items isn't covered (Stripe allows only one capture per PaymentIntent). One payment intent is created per order, and the payment for the order can either be authorized, captured, or cancelled from Stripe's side. - Payments can't be partially canceled. - Items canceled after capture are handled via refunds. ## Browser back button handling Using the browser back button at the Stripe payment form may lead to issues with order persistence and stock management. For instructions on configuring your application to handle this scenario and prevent duplicate orders, see [Configure handling of browser back button action at payment page](/docs/pbc/all/payment-service-provider/latest/base-shop/configure-handling-of-browser-back-button-action-at-hosted-payment-page.html). ## Next step [Integrate Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/install-and-configure-stripe-prerequisites.html)

Stripe OMS configuration for marketplaces

Thu, 16 Apr 2026 13:59:55 +0000

This document provides guidelines for projects using Stripe in marketplaces. ## OMS configuration The complete default payment OMS configuration for marketplaces is available in `vendor/spryker-eco/stripe/config/Zed/oms/StripeManualMarketplace01.xml`. The payment flow of the default OMS involves authorizing the initial payment, which means that the amount is temporarily blocked when the payment method permits. Then, the OMS sends requests to capture, that is, transfer of the previously blocked amount from the customer's account to the store account. For more information about the base shop OMS configuration, see [OMS configuration for Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/project-guidelines-for-stripe/oms-configuration-for-stripe.html). In addition to the base shop implementation, the Stripe module in Marketplaces requires the following OMS configuration: - The `MerchantCommission/Calculate` command triggers the calculation of the commission for the merchant. By default, this command is initiated when an order is moved to the `payment captured` state. This command calculates the commission based on your projects settings. For more details on configuration, see [Marketplace Merchant Commission feature overview](/docs/pbc/all/merchant-management/latest/marketplace/marketplace-merchant-commission-feature-overview.html). - The `SalesPaymentMerchant/Payout` command initiates the payout to merchant action. By default, this command is initiated after the OMS is in the `delivered` state and the commission was calculated. - The `SalesPaymentMerchant/ReversePayout` command initiates the reversal of the payout to the merchant action. By default, this command is initiated after the OMS is in the `payment refunded` state. - The validation of the payout status is done by the `SalesPaymentMerchant/IsMerchantPaidOut` condition. By default, this condition is triggered after a payout is done. When a payout is successful, the OMS moves to the `closed` state. If a payout fails, the OMS moves to the `payout failed` state. - The `SalesPaymentMerchant/IsMerchantPayoutReversed` condition validates the reverse payout status. By default, this condition is triggered after the reverse payout is done. When a reverse payout is successful, the OMS moves to the `canceled` state. If a reverse payout fails, the OMS moves to the `reverse payout failed` state. You can change and configure your own payment OMS based on `StripeManualMarketplace01.xml` from the Stripe eco package. For more information about the OMS feature and its configuration, see [Install the Order Management feature](/docs/pbc/all/order-management-system/latest/base-shop/install-and-upgrade/install-features/install-the-order-management-feature.html). To configure your payment OMS based on `StripeManualMarketplace01.xml`, copy `StripeManualMarketplace01.xml` with the `Subprocess` folder to the project root `config/Zed/oms`. Then, change the file's name and the value of `

Payout subprocess example

```xml merchant payout ready closed payout merchant merchant payout ready payout failed payout merchant payout failed merchant payout ready retry payout merchant ```

Reverse Payout subprocess

```xml merchant payout reverse ready canceled reverse payout merchant payout reverse ready reverse payout failed reverse payout reverse payout failed merchant payout reverse ready retry reverse payout ```

## Processing payouts In the default OMS configuration, a payout to merchants is initiated after the OMS is in `delivered` state and the commission was calculated. This command sends a direct API call to Stripe to initiate the payout to the merchant. The payout status is tracked in the Back Office, and the OMS can either move to `payout failed` or `closed` state. The `payout failed` state is used to track the payout status and inform the Back Office user about the failure. The `closed` state is used to track the successful payout. ### Payout process 1. A customer pays for an order. 2. The money is transferred from the customer's account, like a bank account, to the marketplace Stripe account. - The marketplace calculates the commission for the merchant. - The marketplace initiates a payout to the merchant. - The money is transferred from the marketplace Stripe account to the merchant's Stripe account. ### When a payout fails A payout can fail for many reasons. Examples: - The merchant's account isn't verified - The merchant's account isn't connected to the marketplace Stripe account - The merchant's account isn't active You can identify the cause of a failure in the Stripe Dashboard. After resolving the issue, the payout can be reinitiated. ## Processing refunds as reverse payout In the default OMS configuration, a reverse payout can be done for an order or an individual item. The reverse payout action is initiated by a Back Office user triggering the `SalesPaymentMerchant/ReversePayout` command. The selected item or items are used to find the previously made payout in the database and the amount that was paid out to the merchant and make a direct API call to Stripe which does the reverse payout. Based on the response the items go either into `canceled` or `reverse payout failed` state. ### Reverse Payout process 1. A customer returns an item. 2. The money is transferred from the marketplace Stripe account to the customers account, like a bank account. 3. The marketplace initiates a reverse payout from a merchant. 4. The money is transferred from the merchant's Stripe account to the marketplace Stripe account. ### Reverse payout failures A reverse payout can fail for many reasons, for example — the merchant's Stripe account doesn't have the funds to cover a reverse payout. You can identify the cause of a failure in the Stripe Dashboard. After resolving the issue, the reverse payout can be reinitiated again.

Stripe for Marketplace

Thu, 16 Apr 2026 13:59:55 +0000

[Stripe](https://stripe.com/en-de) is a financial infrastructure platform that enables businesses to accept payments, grow their revenue, and accelerate new business opportunities. The Stripe integration in Spryker is part of the Spryker ecosystem and supports both the default Storefront Yves and Spryker GLUE APIs. This section contains the guides related to running Stripe with Marketplace projects. For more information about Stripe, see [Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/stripe.html). ## Understanding the Marketplace design with Stripe Payments are a crucial component of any commerce platform, including marketplaces. Spryker offers an out-of-the-box integration with Stripe, enabling marketplaces to seamlessly collect payments from customers and remit payments to the merchants selling on the platform. The payment flow is built using [separate charges and transfers](https://docs.stripe.com/connect/separate-charges-and-transfers). This is summarized in the following four steps: 1. A buyer makes a single payment to the platform (Marketplace) for a purchase involving multiple sellers. 2. The platform (Marketplace) receives the funds in its Stripe account and pays the associated Stripe fees. 3. Transfers are made to the merchants separately, depending on the Marketplace's operating model. 4. The balances in the merchants' connected accounts are paid out to their respective bank accounts. ![marketpalce-funds-flow](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/payment-service-providers/marketplace/stripe-third-party-integration/stripe-for-marketplace.md/marketplace-funds-flow.png) ## User journey The image below outlines the user journey for how the Stripe module functions in marketplaces built with Spryker. ![user-journey](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/payment-service-providers/marketplace/stripe-third-party-integration/stripe-for-marketplace.md/marketplace-payment-user-journey.png) Before using the Stripe module in your marketplace, make sure the [prerequisites are met](/docs/pbc/all/payment-service-provider/latest/marketplace/stripe-third-party-integration/install-and-configure-stripe-prerequisites-for-marketplace.html).

Stripe for Marketplace Overview

Thu, 16 Apr 2026 13:59:55 +0000

This document describes how Stripe marketplace payments and merchant payouts are administered and managed. ## Marketplace personas The Marketplace payment experience affects merchants, buyers, and the marketplace operator. ***Merchant*** An entity selling goods in a marketplace. ***Buyer*** An entity that buys products in a marketplace. ***Marketplace Operator*** The owner of a marketplace who can optionally sell products. For more information about personas, see [Marketplace personas](/docs/about/all/spryker-marketplace/marketplace-personas.html) ## Setting up and onboarding to Stripe This section describes how the marketplace operator can set up and onboard themself and merchants to Stripe. ### Marketplace operator's onboarding to Stripe After [prerequisites are installed](/docs/pbc/all/payment-service-provider/latest/marketplace/stripe-third-party-integration/install-and-configure-stripe-prerequisites-for-marketplace.html), to connect Spryker to Stripe via the Stripe module, the operator needs to follow [Configure Stripe for Marketplace](/docs/pbc/all/payment-service-provider/latest/marketplace/stripe-third-party-integration/connect-and-configure-stripe-for-marketplace.html). Once the marketplace is connected to Stripe, we recommend that the Operator does the following before going live: - In the Stripe Dashboard, enable the needed payment methods. - Test the payment flow. - Complete [Stripe's account checklist](https://docs.stripe.com/get-started/account/checklist). - Adhere to [Stripe's risk management best practices](https://docs.stripe.com/connect/risk-management/best-practices#fraud). ### Onboarding merchants to Stripe The merchant onboarding to Stripe is part of the general merchant onboarding process. Depending on your marketplace setup, merchant users will receive information on accessing the Merchant Portal via email or other means. We recommend using the same communication channel to inform merchants about Stripe and how to onboard to it. They can use Stripe as a payment method only after onboarding, so make sure to make this process clear to them. Onboarding happens in the following steps: 1. To connect to the Marketplace Stripe account, a merchant follows [Onboard to Stripe in the Merchant Portal](/docs/pbc/all/payment-service-provider/latest/marketplace/stripe-third-party-integration/onboard-to-stripe-in-the-merchant-portal.html). 2. A Stripe Express account is created for the merchant. 3. Stripe verifies the merchant's KYC details. 4. If the verification is successful, the status of the connection changes in the Stripe Dashboard. #### Notes for the Marketplace Operator about merchant onboarding - Merchants disabled in the Spryker Marketplace aren't automatically removed from the Stripe module. If you need to disable a merchant from receiving payouts, you need to do it in the Stripe Dashboard. - A merchant needs to onboard once to enable Stripe for all merchant users. - All merchant users belonging to a merchant have access to the **Payment Setting** page with Stripe onboarding. ## Marketplace payments and merchant payouts This section describes the marketplace payment flow and how to set up commissions and payouts. ### Marketplace payments The Stripe module in the marketplace uses separate charges and transfers fund flow. This fund flow works great for marketplaces that need to split payments between multiple merchants. With this flow, Stripe requires that the marketplace operator and the merchants are in the same region. If they're not in the same region, payments will result in errors. If you want to set up a marketplace with merchants in different regions, contact your customer success representative to set up a proper fund flow. The payment flow is as follows: - For an order in the marketplace, a customer make a single payment. - Refunds are handled by Spryker Marketplace because the payment contract is between the marketplace operator and the customer. - Payouts to merchants fulfilled through them are issued later. ### Managing merchant payouts using Spryker's commissions engine The terms *payouts* and *transfers* are interchangeable in Spryker's context. However, they have different meanings in Stripe's context: ***Transfer*** Refers to the movement of money from a Marketplace Stripe account to the Merchant's Stripe account, meaning the connected account. ***Payout*** Refers to the movement of money from the merchant's Stripe account to their bank account. The Stripe module lets you configure how you want to manage payouts (also called transfers). An example OMS configuration is provided as a reference. To use Spryker's marketplace commissions engine, you need to [install the Marketplace Merchant Commissions feature](/docs/pbc/all/merchant-management/latest/marketplace/install-and-upgrade/install-features/install-the-marketplace-merchant-commission-feature.html). Payouts with Spryker's commissions engine work as follows: 1. Set up the marketplace merchant commissions feature and the Stripe module. 2. Configure OMS to suit your business logic. 4. Set up a trigger for transfers using a timeout or [set up cronjobs that trigger transfers on a schedule](/docs/pbc/all/payment-service-provider/latest/marketplace/stripe-third-party-integration/configure-merchant-transfers-for-stripe.html). 5. Test that the commissions are applied to the transfer amount. ## Important notes about Stripe - Actions performed on a payment, such as cancellation or capture, must be triggered from Spryker either using the Back Office or OMS. Because OMS information is stored in Spryker, triggering such actions from Stripe Dashboard will result in failures. - The Marketplace business model doesn't support multi-capture. Before transfers can be made to merchants, the marketplace owner must capture a payment. For more information on multi-capture, see [Capture a payment multiple times](https://docs.stripe.com/payments/multicapture). ## Next step [Install and configure Stripe prerequisites for marketplace](/docs/pbc/all/payment-service-provider/latest/marketplace/stripe-third-party-integration/install-and-configure-stripe-prerequisites-for-marketplace.html)

Sending additional data to Stripe

Thu, 16 Apr 2026 13:59:55 +0000

Stripe accepts metadata passed using API calls. To send additional data to Stripe, the `QuoteTransfer::PAYMENT::ADDITIONAL_PAYMENT_DATA` field is used; the field is a key-value array. When sending requests using Glue API, pass the `additionalPaymentData` field in the `POST /checkout` request. ```text POST https://api.your-site.com/checkout Content-Type: application/json Accept-Language: en-US Authorization: Bearer {{access_token}} { "data": { "type": "checkout", "attributes": { "customer": { ... }, "idCart": "{{idCart}}", "billingAddress": { ... }, "shippingAddress": { ... }, "payments": [ { "paymentMethodName": "Stripe", "paymentProviderName": "Stripe", "additionalPaymentData": { "custom-field-1": "my custom value 1", "custom-field-2": "my custom value 2" } } ], "shipment": { "idShipmentMethod": {{idMethod}} } } } } ``` The metadata sent using the field must meet the following criteria: | ATTRIBUTE | MAXIMUM VALUE | | - | - | | Key length | 40 characters | | Value length | 500 characters | | Key-value pairs | 50 pairs | When you pass metadata to Stripe, it's stored in the payment object and can be retrieved later. For example, this way you can pass an external ID to Stripe. When a `PaymentIntent` is created on the Stripe side, you can see your passed `additionalPaymentData` in the Stripe Dashboard.

Project guidelines for Stripe

Thu, 16 Apr 2026 13:59:55 +0000

This document provides comprehensive guidelines for integrating and utilizing the Stripe module in your projects. Whether you are looking to implement Stripe for checkout using Spryker's default storefront or a headless application via Glue API, this guide has you covered. Additionally, you will find detailed instructions on sending additional data to Stripe, retrieving and using payment details, and configuring the Order Management System (OMS). Each section is designed to help you maximize the potential of the Stripe module in your projects. Explore the links below to dive into the detailed guides and enhance your Stripe implementation with best practices and advanced techniques. - [OMS configuration for Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/project-guidelines-for-stripe/oms-configuration-for-stripe.html) - [Processing refunds with Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/project-guidelines-for-stripe/processing-refunds-with-stripe.html) - [Sending additional data to Stripe](/docs/pbc/all/payment-service-provider/latest/base-shop/third-party-integrations/stripe/project-guidelines-for-stripe/sending-additional-data-to-stripe.html)

Processing refunds with Stripe

Thu, 16 Apr 2026 13:59:55 +0000

In the default OMS configuration, a refund can be done for an order or an individual item. The refund action is initiated by a Back Office user triggering the `Stripe/Refund` command. The selected item enters the `payment refund pending` state, awaiting the response from Stripe. During this period, Stripe attempts to process the request, which results in success or failure: - Success: the items transition to the `payment refund succeeded` state, although the payment isn't refunded at this step. - Failure: the items transition to the `payment refund failed` state. These states are used to track the refund status and inform the Back Office user. In a few days after an order is refunded in the Back Office, Stripe finalizes the refund, causing the item states to change accordingly. Previously successful refunds may be declined and the other way around. If a refund fails, the Back Office user can go to the Stripe Dashboard to identify the cause of the failure. After resolving the issue, the item can be refunded again. In the default OMS configuration, seven days are allocated to Stripe to complete successful payment refunds. This is reflected in the Back Office by transitioning items to the `payment refunded` state.

Onboard to Stripe in the Merchant Portal

Thu, 16 Apr 2026 13:59:55 +0000

{% info_block infoBox %} For merchants to be redirected to the Merchant Portal from third-party websites, make sure that, in the web server public folder of your Merchant Portal, there is a `redirect.php` file: [/public/MerchantPortal/redirect.php](https://github.com/spryker-shop/b2c-demo-marketplace/blob/master/public/MerchantPortal/redirect.php). {% endinfo_block %} To onboard to Stripe as a merchant, follow the steps: 1. In the Merchant Portal, go to **Payment Settings**. 2. On the **Payment Settings** page, click **Start Onboarding**. This opens Stripe's onboarding page 3. To complete the onboarding, follow the prompts to fill in merchant information. Once you finish onboarding, the **Payment Settings** page is opened. Stripe needs to approve your onboarding request before you can start using it. You can check the status of onboarding in the Stripe dashboard. ## Stripe onboarding statuses - **Pending**: The Merchant started the onboarding process but did not complete it. - **Enabled**: The Merchant completed the onboarding process and is ready to receive payments. - **Restricted**: Additional data from the Merchant are required. When not updated the payouts will be paused after some period of time. - **Restricted Soon**: Additional data from the Merchant are required. When not updated the payouts will be paused in the near future. - **Rejected**: The Merchant onboarding was rejected and need to contact you to clarify the issue.