OXID eShop

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, kontakt@fatchip.de
Releases and wiki	GitHub

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.
• 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 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:

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:

$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.
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:

ngrok http 443

and point the shop at the tunnel:

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

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:

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 — what “Capture complete order” does at Kustom
• Refunds — the operation OXID admin can’t perform
• Open source platform responsibility — what you own running Kustom on OXID
• Activate Kustom Checkout on your platform — getting the merchant account first
• Authentication and environments — what Playground and Live mode switch between
• Order management — the model behind the Kustom tab
• Test data — identities and cards that pass in Playground
• Platform catalogue — the other platforms with plugins