Important
You are browsing documentation for version 5.0 of OroCommerce, supported until January 2025. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Manage Stripe Payment Service in the Back-Office
Hint
The Stripe payment service is available starting from OroСommerce v5.0.9. To check which application version you are running, see the system information.
Hint
This section is part of the Payment Configuration topic that provides a general understanding of the payment concept in OroCommerce.
Stripe is a payment service provider that helps accept online payments from customers in the OroCommerce storefront and manage all transactions in the OroCommerce back-office. It also provides a solution to expose suspicious and fraudulent behavior and fight it on the website. Stripe also supports order splitting, enabling you to capture, cancel, or refund (fully or partially) payments for each sub-order separately.
Integration Prerequisites
Note
Stripe Integration comes as a separate OroCommerce package and requires installation of the Stripe Integration package.
To start using Stripe with the OroCommerce application:
Register with Stripe to receive the test credentials.
To get the live credentials and start accepting payments, you need to add your business details to view live keys.
Configure Integration Settings in the Back-Office
To configure the integration between Stripe and OroCommerce, follow the steps outlined below:
Navigate to System > Integrations > Manage Integrations in the main menu of the OroCommerce back-office.
Click Create Integration on the top right.
Provide the following information in the form:
Type - Select Stripe from the drop-down list.
Name - Provide the payment method name that is shown as an option for payment configuration in the OroCommerce back-office.
Labels - The payment method name/label displayed as a payment option for the buyer in the OroCommerce storefront during the checkout. To translate the label into other languages, click on the icon next to the field.
Short labels - The payment method name/label that is shown in the order details in the OroCommerce back-office and storefront after the order is submitted. To translate the label into other languages, click on the icon next to the field.
Apple Pay/Google Pay Labels (available starting from OroCommerce v5.0.14) - This label is used at checkout in the storefront, and in the order history and payment rules in the back-office for the optional Apple Pay/Google Pay payment method. When using Apple Pay, please make sure to upload the Apple Pay domain verification file in the configuration of the website(s) where Apple Pay will be used (see Apple Pay Domain Verification). Please note that Apple Pay is a payment method exclusive to the Safari browser and Google Pay is exclusive for the Chrome browser.
API Public Key - An identifier that helps authenticate your account. It refers to Publishable key on the Stripe side. You must use separate keys for the test and production environments.
API Secret Key - A pre-shared key used to cipher payment information. It refers to Secret key on the Stripe side. You must use separate keys for the test and production environments.
Webhook Signing Secret - A key that helps identify your webhook endpoints. Webhooks are used to notify the Oro application when an event happens in the Stripe account (e.g., capturing the payment).
Hint
To obtain the Signing secret:
Navigate to Developers > Webhooks in the Stripe dashboard and click Add an endpoint.
Provide the endpoint URL and select the three events to listen to, charge.refunded, payment_intent.canceled, and payment_intent.succeeded. Keep in mind that Oro supports only these three events. Click Add events.
Click Add endpoint and copy the generated Signing secret to your Stripe integration creation field.
Payment Actions — Select one of the options for credit cards:
Manual (Authorize) — The payment gateway checks with the cardholder’s issuing bank that the submitted card is valid and that there are sufficient funds to cover the transaction. The required amount is placed on hold on the card for 7 days but not yet charged. When you click Capture in the order details (Sales > Orders), the customer is charged the given amount. Payment status changes from Payment Authorized to Paid in Full. If you do not capture the funds within 7 days, the funds are returned to the customer, and the payment status changes to Canceled.
Automatic (Capture) — The payment gateway checks the card with the cardholder’s issuing bank and, if everything is OK, initiates a money transfer from the card to your account. The customer is charged the given amount in full automatically.
User Monitoring — Select the option to enable Stripe to fight fraud by detecting suspicious behavior. When enabled, the Stripe.js script is loaded on all storefront pages to provide real-time fraud protection.
Automatically Re-Authorize Every 6 Days 20 Hours — By default, you need to capture the reserved funds within 7 days, otherwise, the funds are released. Select the option to enable Oro to automatically re-authorize the payments placed on hold every 6 days 20 hours to prevent payment cancellation if the authorization expires. Keep in mind that expired payments can only be re-authorized once. If re-authorization fails, such payment transaction cannot be re-authorized again.
Re-Authorization Errors Notification Email — The email address which is used to send notifications on failed re-authorization attempts.
Status — Set the status to Active to enable the integration.
Default Owner - A user who is responsible for this integration and manages it.
Click Save and Close.
Important
Once the integration with Stripe is created, the next step is to set up a payment rule under System > Payment Rules and add your integration to it to display this method to the customers at checkout.
Checkout with Stripe
Once the payment methods are linked to a payment rule, they become available at checkout in the OroCommerce storefront.
A customer must enter a card number, expiration date, CVC, and a ZIP code (if required) to be able to process the payment via the Stripe service.
The system assigns a reference code to each submitted order. The code is used to identify the order on the Stripe side. You can find the reference code on the order details page, under the Payment History menu.
Sub-Order Checkout with Stripe
If the order split is enabled for the application, then each sub-order is processed separately by Stripe. You can charge, cancel, or refund (full or partially) each individual sub-order independently from their primary order.
A customer must enter a card number, expiration date, CVC, and a ZIP code (if required) to be able to process the payment via the Stripe service.
Once submitted, the system splits the order to the respective sub-orders, assigning them the corresponding reference codes. The codes are used to identify the order on the Stripe side. You can find the details on the primary or sub-order details page, under the Payment History menu.
To capture an authorized payment:
From the primary order details page — Select the sub-order tab under the Sub-Orders Payment History menu and click .
From the sub-order details page — Click at the end of the row under the Payment History menu.
To cancel an authorized payment:
From the primary order details page — Select the sub-order tab under the Sub-Orders Payment History menu and click X.
From the sub-order details page — Click X at the end of the row under the Payment History menu.
To refund (partially or fully) any successful payment:
Find the payment that you want to refund.
Click at the end of the row to open the refund dialog.
By default, you’ll issue a full refund. For a partial refund, enter a different refund amount.
Provide an internal note with the reason for the refund under the Notes section.
Select another refund reason from the dropdown. It will be recorded on the Stripe side.
Click Yes. Refund Payment.
You can issue more than one refund, but you cannot refund a total greater than the original charge amount.
Related Topics