Configuration

Make the module Stripe Payment for OXID operational for your OXID eShop.

General procedure

1. Make sure the module is activated.

2. Enable communication with Stripe:

   1. Connect your OXID eShop to Stripe via OAuth.

   2. Create a webhook so that Stripe can send status notifications to your OXID eShop.

3. Configure the payment methods provided by Stripe as payment types in your eShop:

   • Activate the countries you want to cover.

   • Assign the payment types to your shipping methods and shipping cost rules.

4. Run test payments and adjust the configuration until all payment processes work as desired.

5. To operate Stripe Payment for OXID in live mode, repeat the process accordingly.

Activate Stripe Payment

Make sure that Stripe Payment for OXID is activated in every subshop where you want to use the module.

Procedure

1. Go to Extensions ‣ Modules.

2. Select the module Stripe Payment.

3. If the module is not yet activated, choose Overview ‣ Activate.

Configure Stripe Payment

Start the configuration.

Prerequisites

• You have activated Stripe Payment.

Procedure

Go to Extensions ‣ Modules ‣ Stripe Payment ‣ Settings.

Note

Clear cache if needed

If the configuration settings are not displayed correctly, clear the cache.

For more information, see Installation at step Clear cache.

Set up basic configuration

Connect Stripe Payment with Stripe.

Prerequisites

• You have contacted Stripe and have access to your Stripe Dashboard at dashboard.stripe.com/dashboard.

• Your test environment has SSL.

Procedure

1. Sign in to the Stripe Dashboard (at dashboard.stripe.com/dashboard).

2. In the OXID eShop admin area, go to Extensions ‣ Modules ‣ Stripe Payment ‣ Settings.

3. Under Basic Configuration, in the field Live or Test API, select the mode Test.

4. Next to the field Test API Key, click the button Connect with .
   You will be prompted to select or create the Stripe account you want to connect with your OXID eShop (Fig.: Select Stripe account).

   

   Fig.: Select Stripe account

5. Select the desired account and confirm with Connect (Fig.: Select Stripe account, Pos. 1).
   The system confirms the onboarding (Fig.: Onboarding confirmed).

   

   Fig.: Onboarding confirmed

6. Click the button Go to Admin Area (Fig.: Onboarding confirmed, Pos. 1).

7. Go to Extensions ‣ Modules ‣ Stripe Payment ‣ Settings.
   Under Basic Configuration, the fields Test API Key and Test API Publishable Key are automatically populated. Next to the field Test API Key, Connection successful is displayed (Fig.: Basic configuration after successful connection).

   

   Fig.: Basic configuration after successful connection

8. Save your settings.

Note

API key conflict

If the test and live keys originate from different Stripe accounts, the system displays a warning. In this case, correct the affected Publishable Key fields manually or re-establish the connection.

Configure additional basic settings

Configure the additional settings under Basic Configuration.

Procedure

1. Under Capture Mode, select how payments should be processed:

   • Automatic (capture immediately): The amount is captured immediately when the customer completes the checkout.

   • Manual (authorize only, capture later): The payment is only authorized. You must capture the payment manually within 7 days on the order detail page in the Stripe tab.

2. Optional: Enable the checkbox Send customer email address to Stripe if Stripe should send notifications to the customer’s email address (instead of the Stripe account email address).

3. Recommended: Leave the following checkboxes enabled:

   • Log transaction processing results

   • Remove payment methods not supported for billing country

   • Remove payment methods not supported for currency

4. Save your settings.

Reconcile orders with Stripe

Reconcile the payment status of your orders with Stripe to identify orders that appear as unpaid due to failed or delayed webhooks.

Background

In rare cases, an order in the OXID eShop may appear as unpaid even though the customer has successfully paid via Stripe. The typical cause is failed or delayed webhooks.

For this reconciliation, Stripe Payment provides the console command stripe:reconcile-oxpaid.

Procedure

Set up a cron job on your server that runs the console command regularly, e.g. daily:

# Reconcile orders from the last 7 days (default)
vendor/bin/oe-console stripe:reconcile-oxpaid

# Reconcile orders from the last 14 days
vendor/bin/oe-console stripe:reconcile-oxpaid --max-age=14

# Dry run without changes (preview)
vendor/bin/oe-console stripe:reconcile-oxpaid --dry-run

Result

The command checks all orders within the specified time period that are marked as unpaid in the OXID eShop, and reconciles them with the payment status at Stripe. Successfully paid orders are automatically marked as paid.

The result is logged in the log file log/stripe/stripe_reconciliation_YYYY-MM-DD.log.

Create webhook

Create a webhook. This allows Stripe to contact your OXID eShop and deliver real-time status notifications, for example about completed transactions.

Prerequisites

• You have completed the basic configuration (see Set up basic configuration).

  Otherwise, the error message Your private Stripe key has not been configured yet is displayed.

Procedure

Under Webhooks, click the button Create Webhooks and save.

Result

The webhook endpoint and the associated security key are configured automatically.

Note

Regenerate webhook

If the webhook is misconfigured, enable the checkbox Force webhook update and save again.

Run test payments

To verify the connection, run test payments.

Test the payment types provided by Stripe Payment.

Procedure

1. Under Shop Settings ‣ Payment Methods, activate the desired Stripe payment types.

2. Verify the assignment of payment types to shipping methods and shipping cost rules.

3. Place an order using, for example, Stripe Credit Card as the payment type and complete the test payment (Fig.: Complete test payment with credit card).

   

   Fig.: Complete test payment with credit card

4. To verify the order, go to Administer Orders ‣ Orders ‣ <Order> and view the payment details on the Stripe tab (Fig.: Check payment details of the test order, Pos. 1).

   

   Fig.: Check payment details of the test order

5. Verify the test orders in the Stripe Dashboard under Payments (dashboard.stripe.com/test/payments, Fig.: Verify test order in Stripe Dashboard).

   

   Fig.: Verify test order in Stripe Dashboard

6. Recommended: Check the transaction logs at <root directory of your OXID eShop>/log/stripe/, e.g. stripe_requests_YYYY-MM-DD.log.

7. Optional: Check whether your payment types and currency settings are configured as desired.
   To do this, generate possible error cases that the system by default automatically suppresses.

   1. To generate these possible error cases, temporarily disable the following checkboxes under Basic Configuration:

      • Remove payment methods not supported for billing country

      • Remove payment methods not supported for currency

   2. Use test payments to check whether errors occur and adjust your configuration as needed.

   3. Recommended: After your tests, make sure the checkboxes are enabled again.

8. Optional: Disable the recording of transaction logs if you consider this necessary, for example for security or data minimization reasons.
   To do this, disable the checkbox Log transaction processing results.

Configure country assignment for Stripe payment methods

Ensure that certain Stripe Payment for OXID payment methods are only available in the countries you want.

Background

Most Stripe payment methods cover multiple countries. The payment method Credit Card, for example, is available to customers worldwide, while the payment method iDeal is available to your customers in the Netherlands, for example.

For more information about the country coverage of individual Stripe payment methods, see Market coverage by payment methods.

The basic rule is: The billing address, not the shipping address of a customer, determines whether a Stripe payment method is available to the customer.
Example: Only customers with a billing address in Poland are offered the payment method Stripe Przelewy24.

Procedure

To restrict the availability of a Stripe payment method to certain countries, go to Shop Settings ‣ Payment Methods ‣ <Payment Method> ‣ Countries ‣ Assign Countries.