Get started with Kustom Checkout for Oxid

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Kustom Checkout is an embedded checkout solution for OXID eShop 7 that supports multiple payment methods, B2B purchases, and visual customization to match the store theme. With a single integration, merchants can enable all Kustom payment methods in supported markets and keep shoppers on-site in a fast checkout flow without redirects.

Legacy note: Kustom is also available for OXID eShop v6 under the name Klarna Checkout and Klarna Payments Module (composer package fatchip-gmbh/oxid-klarna-6). This module is no longer being actively developed. Merchants on OXID v6 should refer to the Fatchip Wiki for v6-specific documentation. This guide covers OXID eShop v7 only.

1. Feature Overview

What is Kustom Checkout?

Kustom Checkout replaces the standard OXID checkout with an embedded iframe that handles address collection, shipping selection, and payment in one unified flow. Customers only need to enter their email address and postal code to complete a purchase — especially powerful on mobile devices.

After installing and activating the module, customers can switch directly from the product detail page or mini-basket to the Kustom Checkout, where the purchase is completed in a single step.

Key Capabilities

• Klarna invoice, instalment, direct debit, and credit card payments (Visa / MasterCard) in one checkout
• Near one-click checkout with pre-filled customer addresses for returning shoppers
• Customer recognition across all Kustom-enabled shops
• Guest purchases without registration
• B2B transaction support (requires activation by Kustom)

Supported Countries

Kustom Checkout is available in SE, NO, FI, DE, AT, IE, CH, NL, UK, BE, IT, ES, FR, and additional countries via KCO Global (credit card payments in the Kustom Checkout iframe for most other countries worldwide).

Only activate Kustom payment options for countries covered by your Kustom contract.

2. Prerequisites

2.1 System Requirements

• OXID eShop 7.0 or higher
• PHP 8.0 – 8.4
• Active Kustom merchant account (Merchant ID + password from your Kustom welcome email)
• Server meets OXID 7 system requirements

2.2 SSL Certificate

The shop must run with a valid SSL certificate. The HTTPS address must be stored in config.inc.php under $this->sSSLShopURL. Without SSL, Kustom Checkout cannot be activated.

2.3 External Accessibility

Kustom sends callback requests to your OXID eShop for transaction validation and payment status updates. Your shop must be reachable from the internet on port 443 (HTTPS). No password protection, IP blocking, or firewall rules should prevent Kustom from reaching the callback URLs.

Development / staging note: If testing in a local environment, you will need a tunnelling service (e.g., ngrok) to expose your shop. HTTPS calls from Kustom's servers to port 443 must be allowed.

2.4 Unique Article Numbers

Article numbers (OXARTICLES.OXARTNUM) must be unique within the shop. Kustom validates these during ordering — duplicate article numbers across order lines will prevent order creation.

3. Installation

Step 1 — Install via Composer

Log in to the command line (CLI), navigate to the shop root directory, and run:

composer require fatchip-gmbh/kustom-checkout-oxid7

Step 2 — Activate the Module

In the OXID admin backend, go to Extensions → Modules → "Kustom Checkout" → Overview and click Activate.

Step 3 — Configure SSL URLs

Edit config.inc.php in the shop's /source directory and ensure the following variables are set:

$this->sShopURL     = 'https://YOUR-SHOP.URL';
$this->sSSLShopURL  = 'https://YOUR-SHOP.URL';
$this->sAdminSSLURL = 'https://YOUR-SHOP.URL/admin';

Step 4 — Activate the Payment Method

Navigate to Shop Settings → Payment Methods, activate "Kustom Checkout", and assign the appropriate countries under the Countries tab.

Step 5 — Assign Shipping Methods

Ensure "Kustom Checkout" is assigned to your shipping methods under Shop Settings → Shipping Methods → [select method] → Tab: Payment.

Step 6 — Test

Perform a test transaction using Playground (test) credentials before going live.

4. Updating the Module

Current release versions are published on the GitHub Releases page.

1. Open composer.json in the shop root and change the module version to the target version
2. Run from the command line:
   composer update

3. In the OXID admin, go to Extensions → Modules, deactivate the plugin, and reactivate it

5. Configuration

After installation, a new Kustom menu section appears in the OXID admin sidebar with several sub-menu entries. For detailed descriptions of each setting, refer to the tooltips [?] in the backend.

5.1 General Settings

5.2 Checkout Configuration

5.3 Design Settings

Customize the visual appearance of the Kustom Checkout iframe to match your shop layout. Leave all colour fields empty to use the Kustom default colour scheme.

Tip: Clicking a colour field opens a colour picker. The border radius setting previews immediately in the admin input field.

5.4 External Payment Methods

Within the Kustom Checkout iframe, additional external payment methods can be offered alongside the standard Kustom payment types. The module includes built-in support for:

• Cash on Delivery (COD)
• Prepayment (advance payment)

When activated, customers can select these methods directly within the iframe. Even for guest orders, address data is auto-filled if the customer is recognised by Kustom.

Compatible third-party modules:

• Amazon Pay & Login 4 OXID (by best it GmbH & Co. KG)
• PayPal Module (by OXID eSales AG)

Settings per external payment method:

Adding Custom External Payment Methods (Developer)

Developers can add custom external payment methods by extending:

• Controllers/KustomOrderController.php — add actions in the KustomExternalPayment() method
• Core/KustomConsts.php — register the payment method name in getKustomExternalPaymentNames()

Only names approved by Kustom may be used. Contact your Kustom Integration Manager for details.

5.5 Extra Merchant Data (Attachments)

Only enable these settings if instructed by your Kustom Integration Manager.

These settings allow additional customer information to be transmitted for enhanced risk assessment:

• Customer Account Info — transmits account creation and last-update dates
• Payment History Full — transmits purchase counts, sums, first/last purchase dates, and payment method types

Metadata (Pass-Through Field)

The merchant_data field allows transmitting custom information per order. Override the getPassThroughField() method in a custom module:

class your_module_pass_through extends your_module_pass_through_parent
{
    public function getPassThroughField()
    {
        $mainData = "any custom string";
        return $mainData;
    }
}

Register your module via Metadata.php.

Custom Attachments

For complex data (travel, event, voucher, subscription), extend the EMD class:

class your_module_Kustom_emd extends your_module_Kustom_emd_parent
{
    public function getAttachments($oxUser)
    {
        $mainData = parent::getAttachments($oxUser);
        $myEMDData = array(
            'your_custom_info' => array(
                'example_field' => 'example data'
            )
        );
        return array_merge($mainData, $myEMDData);
    }
}

5.6 Shipping Methods

Map your OXID shipping methods to predefined Kustom shipping types (e.g., mapping "Pick-up" to "PickUpStore"). This mapping is optional but improves Kustom's risk assessment and simplifies customer service.

DHL Packstation: If you offer Packstation deliveries, this assignment is required. Choose "Postal + DHLPackstation". Otherwise, choose "Postal".

5.7 Payment Method Configuration in OXID Shop Settings

In Shop Settings → Payment Methods, the Kustom Checkout payment method can be assigned to countries and user groups.

Important rules:

• Do not assign user groups to "Kustom Checkout" — it must remain available to guest users
• Do not use the "Price increase / discount" field for the Kustom Checkout payment method
• Ensure at least one Shipping Method and one Shipping Cost Rule are not restricted to user groups
• Only assign countries for which you have a signed Kustom contract

6. Order Management

After installation, a new Kustom tab appears in the order detail view under Administer Orders.

6.1 Capturing Orders

During checkout, Kustom creates a payment reservation. To receive payment, inform Kustom when goods have been shipped by clicking "Capture complete order" on the Kustom tab. This activates the claim (e.g., triggers a credit card charge).

6.2 Order Modifications

Changes to orders made via the OXID admin (e.g., adding/deleting items or discounts) are transmitted to Kustom where possible. However, for complex operations use the Kustom Merchant Portal (a direct link is available on each order's Kustom tab):

• Partial captures — not available from OXID admin
• Refunds / returns — not available from OXID admin
• Complex order adjustments — recommended via the Portal

6.3 Address Updates

Address updates are blocked in the OXID admin for Kustom orders. The original risk assessment was based on the address provided at checkout.

6.4 Status Synchronisation

Order status is displayed in green when OXID and Kustom Portal data match. In case of discrepancies, check the Kustom Merchant Portal directly — only the data there is authoritative.

7. Template Modifications

If you use custom or heavily modified templates (rather than the standard OXID themes), verify that all required template blocks and modifications are present and functional.

Key template areas to check:

• Footer — Kustom logo display
• Product detail page — Kustom-related buttons and interactions
• Checkout page — Kustom Checkout iframe integration
• Order overview page — correct order summary display
• Order confirmation email — Kustom order information

Recommendation: Compare your templates against the screenshots and template blocks documented in the module's wiki to ensure all legally required and functional modifications are implemented.

8. Known Limitations

9. Local Development Setup

When developing locally, Kustom's servers cannot reach your callbacks. To test the full checkout flow, expose your local environment using a tunnelling service:

ngrok http 443

Update your OXID shop's config.inc.php to use the tunnel URL:

$this->sSSLShopURL  = 'https://abc123.ngrok-free.app';
$this->sAdminSSLURL = 'https://abc123.ngrok-free.app/admin';

Note: Free tunnelling URLs change on each restart — update the shop's base URL accordingly.

10. Troubleshooting

Enable Debug Logging

Enable the logging function under Kustom → General → Enable logging. All API communication is recorded in the tcKustom_logs MySQL table. Disable in production.

Common Issues

Checkout iframe does not load:

• Verify that $this->sSSLShopURL is correctly set in config.inc.php
• Ensure the shop is accessible from the internet on port 443
• Check that Merchant ID and password are correctly configured
• Confirm the Kustom Checkout payment method is activated and assigned to countries and shipping methods

Orders fail due to duplicate article numbers:

• Ensure all OXARTICLES.OXARTNUM values are unique within the shop

Callbacks not received:

• Verify no firewall, IP blocking, or password protection prevents external access
• Check that the shop URL stored in Kustom's system matches the actual accessible URL

Payment methods not displayed:

• Confirm payment methods are assigned to user groups, countries, and shipping methods
• Verify your Kustom contract covers the selected countries
• Check that the currency matches the country's expected national currency

11. Testing and Go-Live

1. Configure Playground mode — use your test Merchant ID and password
2. Perform test transactions — test each payment method you plan to offer
3. Verify callbacks — confirm that order status updates flow correctly between Kustom and OXID
4. Check order management — test capture, cancellation, and verify data in the Kustom Merchant Portal
5. Contact Kustom — prior to go-live, coordinate with the Kustom integrations team for an approval cycle
6. Switch to Live mode — only after successful testing and Kustom approval

12. Support