# OXID eShop

Install and configure the Kustom Checkout module for OXID eShop 7 — Composer install, SSL and callback prerequisites, the full settings map, order management from the admin and the limitations you have to design around.

Kustom Checkout for OXID eShop 7 replaces the standard OXID checkout with an embedded iframe
that collects address, shipping and payment in one step — a customer who is already known to
Kustom needs only an email address and a postal code. The module is built and maintained by
Fatchip GmbH. This page covers installing it, the shop prerequisites that silently break the
checkout when they are wrong, the settings that matter and the operations OXID admin can't do.

| | |
| --- | --- |
| Module | Kustom Checkout for OXID eShop 7, version 1.1.0 |
| Composer package | `fatchip-gmbh/kustom-checkout-oxid7` |
| OXID versions | 7.0 and higher |
| PHP versions | 8.0 – 8.4 |
| Developer | [Fatchip GmbH](https://www.fatchip.de), `kontakt@fatchip.de` |
| Releases and wiki | [GitHub](https://github.com/FATCHIP-GmbH/kustom-checkout-oxid7/releases) |

## Before you start

- OXID eShop 7.0 or higher, meeting OXID's own server requirements, and PHP 8.0 to 8.4.
- An active Kustom merchant account. Your Merchant ID and password arrive in the Kustom welcome
  email — see [Activate Kustom Checkout on your platform](/partners/activate-kustom-checkout/).
- **A valid SSL certificate, with the HTTPS address stored in `config.inc.php` as
  `$this->sSSLShopURL`.** Kustom Checkout can't be activated without it.
- **The shop reachable from the internet on port 443.** Kustom posts callbacks to it for
  transaction validation and payment status. No password protection, IP blocking or firewall
  rule may stand in the way.
- **Unique article numbers.** `OXARTICLES.OXARTNUM` must be unique across the shop. Kustom
  validates them at order creation, and duplicates across order lines stop the order being
  created at all.

On OXID eShop 6, Kustom is only available through the old *Klarna Checkout and Klarna Payments
Module* (`fatchip-gmbh/oxid-klarna-6`), which is no longer developed. This page doesn't cover
it. See the [Fatchip Wiki](https://wiki.fatchip.de/public/klarna-en) if you're still on v6, and
plan the upgrade to v7.

### What the module can't do

Design around these rather than discovering them in production.

| Limitation | Detail |
| --- | --- |
| Pending flow | Orders are accepted or rejected immediately. Kustom's "Pending" status isn't supported |
| Partial captures | Not available from OXID admin. Use the Kustom Merchant Portal |
| Refunds and returns | Can't be started from OXID admin. Use the Kustom Merchant Portal |
| Automatic capture | Not implemented. Capture is always manual |
| Address updates | Blocked in OXID admin for Kustom orders — the payment method's risk assessment was made on the checkout address |
| Gift cards | Kustom money gift cards bought in physical stores are not supported by OXID eShop |
| Vouchers | OXID promotion vouchers are sent to Kustom as discounts |
| Localization | In the global iframe, choosing a different country doesn't change the iframe language, which stays the shop's front-end language |

Order modifications made in the OXID admin — adding or removing items, adding discounts — are
transmitted to Kustom where the module can express them. Anything more complex belongs in the
Kustom Merchant Portal, and each order's Kustom tab links straight to it.

## Step by step

### 1. Install the module with Composer

From the shop root:

```bash
composer require fatchip-gmbh/kustom-checkout-oxid7
```

### 2. Activate the module

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

### 3. Set the SSL URLs

Edit `config.inc.php` in the shop's `/source` directory:

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

### 4. Activate the payment method and assign countries

Under **Shop Settings → Payment Methods**, activate **Kustom Checkout** and assign it, on the
**Countries** tab, to every country your Kustom contract covers — and only those.

### 5. Assign shipping methods

Under **Shop Settings → Shipping Methods →** each method **→ Payment**, make sure **Kustom
Checkout** is assigned. A shipping method with no Kustom assignment makes the payment method
invisible for those carts.

### 6. Enter your credentials and configure the checkout

A **Kustom** section appears in the admin sidebar after activation. Each field has a `[?]`
tooltip. The settings that decide behavior are:

**General.** **Mode** switches between Playground and Live — only go Live after successful tests
and a conversation with your Kustom Integration Manager. **Merchant ID / API Username** and
**Password / API Password** come from your welcome email, and apply globally unless you add
country-specific credentials below them. **Enable logging** records all API traffic in the
`tcKustom_logs` table. Leave it off in production, because of both volume and sensitivity.
**Product URLs** and **Image URLs** send links and images so Kustom can show your articles in the
Portal, while **Enable anonymization** hides product names entirely — intended for pharmacies,
and only after agreeing it with Kustom. **Allowed customer types** is B2C, B2B or both. B2B needs
enabling on your Kustom account first. **Terms and Conditions URI**, **Cancellation Rights URI**
and **Shipping Details URI** are all mandatory.

**Checkout.** **Default Shop Country** is what loads before the customer says otherwise. **Allow
separate shipping address**, **Phone number mandatory** and **Date of birth mandatory** should
mirror what your OXID registration requires — date of birth is necessary for invoice and
instalment purchases. **Custom checkbox** puts an account-creation or newsletter opt-in inside
the iframe, with text that adapts if the customer already has one. **Order validation** should be
set to **Require successful validation**. The alternatives skip or ignore the cart availability
check at submission. **Enable pre-filling** fills the iframe from a logged-in OXID customer, and
**Pre-filling notice** shows the data protection notice some countries require alongside it.

**Design.** Leave every color field empty to use Kustom's defaults. Otherwise set the pay
button background and text, checkbox background and checkmark, header, link and border radius.
**Footer** controls whether the Kustom logo shows in your shop footer.

**Shipping methods.** Map OXID shipping methods to Kustom shipping types — "Pick-up" to
`PickUpStore`, for instance. This is optional and improves the payment method's risk
assessment, except for DHL
Packstation, where you must choose **Postal + DHLPackstation**. Otherwise choose **Postal**.

### 7. Test, then go live

Run test transactions in Playground for every payment method you plan to offer, verify callbacks
move order status in both directions and test capture and cancellation against the Kustom
Merchant Portal. Coordinate an approval cycle with the Kustom integrations team, then switch
**Mode** to Live.

## Check that it works

1. Add a product to the cart and open the checkout. The Kustom iframe should load.
2. Complete a Playground purchase with [test data](/basics/test-data/).
3. Confirm the order appears in **Administer Orders**, with a **Kustom** tab on it.
4. On that tab, click **Capture complete order** and confirm the capture registers in the Kustom
   Merchant Portal.
5. Confirm the order status shows green — green means OXID and the Portal agree. If it doesn't,
   the Portal is authoritative. OXID is the copy.
6. If you run custom or heavily modified templates rather than a stock OXID theme, check the
   footer, product detail page, checkout page, order overview page and order confirmation email
   for the module's template blocks. Compare against the module wiki: some of those blocks carry
   legally required text.

## Variations

### Developing locally

Kustom's servers can't reach a local shop, so callbacks never arrive. Tunnel port 443:

```bash
ngrok http 443
```

and point the shop at the tunnel:

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

Free tunnel URLs change on every restart, so the base URL has to be updated each time.

### Offering external payment methods inside the iframe

The module can present **Cash on Delivery** and **Prepayment** inside the Kustom iframe
alongside Kustom's own methods, with address data auto-filled even for guests when the customer is
recognized. Amazon Pay & Login 4 OXID (best it GmbH) and the OXID eSales PayPal module are
compatible. Per method you assign a **Payment Method**, toggle **External Payment Method** and
give an **Image URI** — a 69×24 pixel image on an HTTPS URL, per language.

To add your own, extend `Controllers/KustomOrderController.php` with an action in
`KustomExternalPayment()` and register the name in `getKustomExternalPaymentNames()` in
`Core/KustomConsts.php`. Only names Kustom has approved will work — ask your Integration Manager.

### Sending Extra Merchant Data

Only enable these if your Kustom Integration Manager tells you to. **Customer Account Info**
transmits account creation and update dates. **Payment History Full** transmits purchase counts,
sums, first and last purchase dates and payment method types. Both feed the payment
method's risk assessment.

For a free-form value per order, override `getPassThroughField()` to populate `merchant_data`:

```php
class your_module_pass_through extends your_module_pass_through_parent
{
    public function getPassThroughField()
    {
        return "any custom string";
    }
}
```

For structured attachments — travel, event, voucher or subscription data — extend the EMD class:

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

Register either through `Metadata.php`.

### Updating the module

Change the version in the shop root's `composer.json`, run `composer update`, then deactivate and
reactivate the module under **Extensions → Modules**. Releases are on the module's GitHub
releases page.

## Troubleshooting

**The checkout iframe doesn't load.** Check `$this->sSSLShopURL` is set correctly, that the shop
answers on port 443 from outside, that Merchant ID and password are right for the selected mode
and that the payment method is active and assigned to both countries and shipping methods.

**Orders fail with a duplicate article error.** Two order lines carry the same
`OXARTICLES.OXARTNUM`. Make article numbers unique.

**Callbacks aren't received.** Check for firewalls, IP blocking or HTTP auth, and confirm the
shop URL Kustom holds matches the URL that is actually reachable.

**The payment method isn't displayed.** Confirm it's assigned to the customer's country and to a
shipping method, that your contract covers that country and that the cart currency matches the
country's national currency — a mismatch replaces the Kustom option with a warning, as does a
company name on a B2C-only configuration.

Note that the module's own guidance is contradictory about user groups. The configuration rules
say **not** to assign user groups to Kustom Checkout, so that it stays available to guests, while
the troubleshooting advice says to confirm the method *is* assigned to user groups. Follow the
configuration rule: leave user groups unassigned, and make sure at least one shipping method and
one shipping cost rule are also unrestricted by group. Don't use the "price increase / discount"
field on the Kustom Checkout payment method.

To dig further, enable **Kustom → General → Enable logging** and read `tcKustom_logs`. Disable it
again in production.

## Related

- [Capture an order](/order-management/capture/) — what "Capture complete order" does at Kustom
- [Refunds](/order-management/refunds/) — the operation OXID admin can't perform
- [Open source platform responsibility](/partners/open-source-responsibility/) — what you own running Kustom on OXID
- [Activate Kustom Checkout on your platform](/partners/activate-kustom-checkout/) — getting the merchant account first
- [Authentication and environments](/api/authentication/) — what Playground and Live mode switch between
- [Order management](/order-management/) — the model behind the Kustom tab
- [Test data](/basics/test-data/) — identities and cards that pass in Playground
- [Platform catalogue](/partners/) — the other platforms with plugins