Configuration

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

Basic procedure

1. Make sure that the module is activated.

2. Enable communication with Stripe:

   1. To connect your OXID eShop with Stripe, generate keys.

   2. Optional: Map the order statuses used by Stripe to your order management folders.

   3. Create cronjobs to, for example, submit shipping status to Stripe or complete unfinished orders.

   4. To allow Stripe to send status messages to your OXID eShop, create a webhook.

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

   • Enable the countries you want to cover.

   • Link the payment methods to your shipping methods and shipping rules.

4. Make test payments and adjust the configuration until all payment processes work as you want.

5. To run Stripe Payment for OXID in live mode, repeat the process analogously.

Activating Stripe for OXID

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

Procedure

1. Choose Extensions ‣ Modules.

2. Choose the Stripe Payment module.

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

Configuring Stripe Payment

Start the configuration.

Prerequisites

• You have activated Stripe Payment.

Procedure

Choose Extensions ‣ Modules ‣ Stripe Payment ‣ Settings.

Note

Clear the cache if necessary

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

For more information, under Installation see the Clear cache step.

Setting up the basic configuration

Connect Stripe Payment to 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. Log in to the Stripe Dashboard (at dashboard.stripe.com/dashboard).

2. In the OXID eShop admin area, choose Extensions ‣ Modules ‣ Stripe Payment.

3. Under Basic Configuration, choose Connect with stripe.
   You are prompted to choose or create the account you want to connect your OXID eShop to (Fig.: Choosing a Stripe account).

   

   Fig.: Choosing a Stripe account

4. Choose Connect (Fig.: Choosing a Stripe account, item 1).
   The system confirms the onboarding (Fig.: Onboarding confirmed).

   

   Fig.: Onboarding confirmed

5. Choose the Zum Admin-Bereich button (Fig.: Onboarding confirmed, item 1).

6. Choose Extensions ‣ Modules ‣ Stripe Payment ‣ Settings.
   Under Basic Configuration you see that the connection is established (Fig.: Verifying the connection and entering the private API key, item 1).

7. Enter your private API key.

   1. In the Stripe dashboard, choose Entwickler ‣ API-Schlüssel.

   2. Choose the Geheimschlüssel erstellen button.

      

      Fig.: Creating a private API key

      The private API key is displayed (Fig.: Copying the private API key).

      

      Fig.: Copying the private API key

   3. Follow the instructions to save your private API key and go back to the administrator area of your OXID eShop.

   4. In the Test API Private Key input field (Fig.: Verifying the connection and entering the private API key, item 2), enter your private API key.

   5. Save your settings (Fig.: Verifying the connection and entering the private API key, item 3).

      

      Fig.: Verifying the connection and entering the private API key

Mapping transaction statuses

Map the Stripe payment transaction statuses to the folders in your order administration that you have configured under Master Settings ‣ Core Settings ‣ Settings ‣ Administration.

Procedure

Optional: Assign the following order statuses used by Stripe to the folders in your order administration:

• Stripe status Pending: Order status before the customer is redirected to the payment gateway.

• Stripe status Processing: Order status for completed payments

• Stripe status Cancelled: Order status for cancelled orders

Result

Orders processed with Stripe are sorted and classified into the appropriate folders according to their Stripe status (Fig.: Displaying Stripe orders categorized by status.

Fig.: Displaying Stripe orders categorized by status

Setting up cronjobs

Set up and enable a cronjob to complete unfinished orders daily, for example.

If you call the cronjob via URL, make sure to add a secureKey GET parameter.

Procedure

1. Set up a cronjob on your server that points to the file /source/modules/fc/stripe/Application/Model/Cronjob.php in the module directory.
   Result: The scripts in the /source/modules/fc/stripe/Application/Model/Cronjob directory are scheduled to be executed once a day, for example, depending on the cronjob settings.

2. Under Cronjobs, enable the scripts to actually run.

   • Completion of paid but unfinished order (FinishOrders.php)

     Finalize orders where the customer has successfully paid but does not appear to have returned to the store for completion of the order process.

     To avoid changing orders that have probably already been processed manually, the cronjob only finalizes orders from the last 24 hours.

   • Dispatch of payment reminder email (SecondChance.php)

     Automatically send payment reminder emails if a payment has not yet been made. Your customer will get back to the payment process and can complete the order.

     If required, change the subject line in the modules/fc/stripe/Application/translations/en/stripe_lang.php file.

     If required, change the cover letter text of the e-mail under Customer Info ‣ CMS Pages ‣ Main in the Stripe Second Chance Email module (Fig.: Customizing the e-mail template for Stripe payment reminders).

     

     Fig.: Customizing the e-mail template for Stripe payment reminders

     The sender -email address used is the e-mail address configured under Master Settings ‣ Core Settings ‣ Main ‣ Order e-mails to.

   • Transmission of shipping status to Stripe (OrderShipment.php)

     If you set the shipping status in your store via an external system and not manually via the Ship Now button in the order administration of your OXID eShop under Administer Orders ‣ Orders, submit the shipping status automatically via cronjob.

     Example: You process the transactions via an ERP system.

3. If you activate the Dispatch of payment reminder email script, in the Time window after which payment reminder email is sent input field, enter the appropriate value.

4. If you need to call the cronjob via URL (instead of using the PHP command line), do the following:

   1. Add the secureKey GET parameter to the call to the cronjob.

      Example: https://YOUR-SHOP-URL-HERE/modules/fc/stripe/cron.php?secureKey=YOUR-SECURE-KEY

   2. Enter the value of the secureKey parameter into the Cronjob secure key field.

5. Save your entries.

Creating a webhook

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

Prerequisites

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

  Otherwise, the error message Your private Stripe key has not been configured yet will appear.

Procedure

Under Webhooks, choose the Create Webhook button.

Result

The system indicates that the webhook endpoint is configured (Fig.: Webhook endpoint configured, item 1).

Fig.: Webhook endpoint configured

Making test payments

To verify the connection, perform test payments.

Test the payment types provided with Stripe Payment.

Procedure

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

2. Verify the mapping of the payment types to the shipping types and shipping rules.

3. Run an order with, for example, Stripe GiroPay as the payment type and authorize the test payment (Fig.: Authorizing a test payment).

   

   Fig.: Authorizing a test payment

4. To verify the order, under Manage Orders ‣ Orders ‣ <Order> on the Stripe tab (Fig.: Verifying the test order, item 1), display the payment details.

5. To check the cronjobs, make an order without completing it.

   

   Fig.: Verifying the test order

6. Verify the test orders in your Stripe dashboard under payments (dashboard.stripe.com/test/payments, Fig.: Verifying test orders in the Stripe dashboard).

   

   Fig.: Verifying test orders in the Stripe dashboard

7. Recommended: Check the transaction log under <root directory of your OXID eShop>/log/StripeTransactions.log.

8. Optional: Check if you have configured your payment methods and currency settings as desired.
   To do so, create possible error cases which by default are automatically suppressed:

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

      • Remove payment types not supported by billing country.

      • Remove not supported payment types by basket currency.

   2. Check for errors with test payments and adjust your configuration if necessary.

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

9. Optional: Disable the recording of transaction logs if you feel that this is necessary, for example, for security or data-saving reasons.
   To do this, uncheck the Log results of transaction processing checkbox.

Configuring the country mapping of Stripe payment methods

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

Background

Most Stripe payment methods cover multiple countries. For example, the credit card payment method is available to customers worldwide, while the iDeal payment method is available to your customers in the Netherlands, for example.

For more information about the country coverage of each Stripe payment method, see Market coverage by payment method.

As a general rule, it is the billing address and not the shipping address of a customer that determines whether a Stripe payment method is available to the customer.
Example: Only customers with a billing address in Poland will be offered the Stripe Przelewy24 payment method.

Procedure

To restrict the accessibility of a Stripe payment method to certain countries, choose Shop settings ‣ Payment methods ‣ <payment method> ‣ Country ‣ Assign countries.