# Get started with Kustom Checkout for Oxid

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](https://wiki.fatchip.de/public/klarna-en) for v6-specific documentation. This guide covers **OXID eShop v7 only**.


|  |  |
|  --- | --- |
| **Module name** | Kustom Checkout for OXID eShop 7 |
| **Current version** | 1.1.0 |
| **Composer package** | `fatchip-gmbh/kustom-checkout-oxid7` |
| **OXID versions** | 7.0 and higher |
| **PHP versions** | 8.0 – 8.4 |
| **Module developer** | [Fatchip GmbH](https://www.fatchip.de) (`kontakt@fatchip.de`) |
| **Kustom support** | [support@kustom.co](mailto:support@kustom.co) |


## 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](https://docs.oxid-esales.com/eshop/de/7.1/installation/neu-installation/server-und-systemvoraussetzungen.html)


### 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:


```bash
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:


```php
$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](https://github.com/FATCHIP-GmbH/kustom-checkout-oxid7/releases).

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

```bash
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

| Setting | Description |
|  --- | --- |
| **Mode** | Switch between **Playground** (test) and **Live** (production). Only switch to Live after successful integration tests and consultation with your Kustom Integration Manager. |
| **Merchant ID / API Username** | Your Kustom Merchant ID from the welcome email. Applies globally unless country-specific credentials are added below. |
| **Password / API Password** | The password matching your Merchant ID. |
| **Country-specific credentials** | Optional. Add separate Merchant ID and password for individual countries if you received different credentials from Kustom. |
| **Enable logging** | Records all API communication in the MySQL table `tcKustom_logs`. Useful for troubleshooting. Disable in production due to data volume and sensitivity. |
| **Product URLs** | Send product detail page URLs to Kustom so they can link to your articles from the Kustom Portal. |
| **Image URLs** | Send product image URLs for display in the Kustom Portal. |
| **Enable anonymization** | Hide product names from Kustom (recommended for pharmacies). Only activate after consultation with Kustom. |
| **Allowed customer types** | B2C only (default), B2B only, or both. B2B must be activated by Kustom for your account. |
| **Kustom Checkout Delivery Method** | Select the shipping method to be used for Kustom Checkout. |
| **Terms and Conditions URI** | **Mandatory.** URL to your general terms and conditions. |
| **Cancellation Rights URI** | **Mandatory.** URL to your cancellation / withdrawal policy. |
| **Shipping Details URI** | **Mandatory.** URL to your shipping information page. |


### 5.2 Checkout Configuration

| Setting | Description |
|  --- | --- |
| **Default Shop Country** | Country loaded by default in the Kustom Checkout until the customer specifies their own. |
| **Allow separate shipping address** | Enable delivery to a different address than the billing address. |
| **Phone number mandatory** | Require phone number. Enable this if your OXID shop also requires it in user registration (Admin → Master Data → Basic Settings → Must fields). |
| **Date of birth mandatory** | Require date of birth. Necessary for invoice / instalment purchases. Enable if your OXID shop requires it in registration. |
| **Enable autofocus on iframe** | Automatically focus the Kustom Checkout iframe when the page loads. |
| **Custom checkbox** | Add an optional checkbox inside the iframe for: creating a customer account, subscribing to the newsletter, or both. Text adjusts automatically if the customer already has an account or subscription. |
| **Order validation** | Validate cart availability when the order is submitted. Options: No validation, Validate but ignore timeouts, or **Require successful validation** (recommended). |
| **Enable pre-filling** | Pre-fill the iframe with data from logged-in OXID customers. |
| **Pre-filling notice** | Show a data protection notice when pre-filling is active (required in some countries). |
| **Terms and Conditions URI** | Per-language URL to your GTCs, linked inside the iframe. Must start with `https://`. |
| **Cancellation Rights URI** | Per-language URL to your withdrawal policy. Must start with `https://`. |
| **Shipping details** | Per-language shipping notes displayed on the thank-you page after order completion. |


### 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.

| Setting | Description |
|  --- | --- |
| **Footer** | Choose whether to display the Kustom logo in the shop footer. |
| **Button** | Background colour of the pay button inside the iframe. |
| **Button Text** | Text colour of the pay button. |
| **Checkbox** | Background colour of checkboxes inside the iframe. |
| **Checkbox Checkmark** | Colour of the checkmark inside checkboxes. |
| **Header** | Colour of headings / titles inside the iframe. |
| **Link** | Colour of links inside the iframe. |
| **Border Radius** | Degree of rounding of the iframe border. |


> **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:**

| Setting | Description |
|  --- | --- |
| **Payment Method** | Assign this method to a predefined payment type. |
| **External Payment Method** | Toggle to activate this method within the Kustom Checkout iframe. |
| **Image URI** | Per-language URL to a 69×24 pixel image displayed next to the payment method. Use an HTTPS URL. |


#### 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:


```php
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:


```php
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

| Limitation | Details |
|  --- | --- |
| **Pending Flow** | Orders are accepted or rejected immediately. The Kustom "Pending" status is not supported. |
| **Partial Captures** | Not available from the OXID admin. Use the Kustom Merchant Portal. |
| **Refunds / Returns** | Cannot be initiated from OXID admin. Use the Kustom Merchant Portal. |
| **Gift Cards** | Kustom-style money gift cards (purchasable in local stores) are not supported by OXID eShop. |
| **Vouchers** | OXID promotion vouchers are transmitted to Kustom as "Discounts". |
| **Automatic Capture** | Not implemented. Manual capture is required. |
| **Localization (KCO Global)** | If a customer selects a different country in the Global iframe, the iframe language remains the shop's front-end language. |
| **Currency / Company Warnings** | A warning replaces the Kustom payment option if the selected currency doesn't match the country's national currency or if a company name is specified. |


## 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:


```bash
ngrok http 443
```

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


```php
$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

| Contact | Details |
|  --- | --- |
| **Kustom Merchant Support** | [support@kustom.co](mailto:support@kustom.co) |
| **Module Developer (Fatchip GmbH)** | [kontakt@fatchip.de](mailto:kontakt@fatchip.de) |
| **Module Releases** | [GitHub Releases](https://github.com/FATCHIP-GmbH/kustom-checkout-oxid7/releases) |
| **Module Documentation** | [GitHub Wiki](https://github.com/FATCHIP-GmbH/kustom-checkout-oxid7/wiki) |