Magento 2 integration guide

After you install and activate the iwocaPay plugin, it appears as a payment option in your Magento checkout. Payments made through iwocaPay automatically reconcile with your store data.

You can offer Buy Now, Pay Later to your customers, and optionally Pay Now via instant bank-to-bank transfers at no extra cost.

---

Before You Begin

Installing the iwocaPay extension for Magento takes 1–2 hours. You’ll likely need a developer or someone with command-line access.

Supported versions

You must have Magento 2 — the iwocaPay extension is not compatible with Magento 1.

Prerequisites

• Understand the user journey and our concepts
• Set the terms and pricing you want to offer, via the universal pay link page in your iwocaPay dashboard
• Access to your server’s command line
• Get your API token by clicking Install Plugin on the Magento tab of the Integrations page in your iwocaPay dashboard. This sends a request to your Account Manager. You can also contact your Account Manager directly.
• Back up your database before making any changes
• Run installation commands in maintenance mode

Choose your pricing structure

With iwocaPay, you decide who covers the cost of Pay Later transactions.

You can manage your pricing preferences from your universal pay link in the iwocaPay dashboard.

Read more about our pricing structure

---

Installing iwocaPay in Magento 2

Caution

If you need to refresh your API keys, please note this is only required for Production and your staging keys will remain unchanged.

1. Access your Magento server via SSH and navigate to your Magento 2 installation directory:

   cd /path/to/magento

2. Download the plugin files:

   composer require iwoca/iwocapay-magento

3. Enable and install the plugin:

   magento module:enable Iwoca_Iwocapay
   magento setup:upgrade
   magento cache:clean && magento setup:di:compile

4. Configure the plugin:

   Caution

   Make sure you are editing the Default Config scope when configuring iwocaPay. In the Magento admin, go to the Store View dropdown at the top-left of the Configuration page and check it says “Default Config”, not a specific website or store view.

   iwocaPay supports one seller account per Magento installation. Configuration must be saved at the default (global) level to work correctly across all your websites and store views.

   If you have more than one website or store view, don’t re-save the iwocaPay configuration while it’s scoped to a specific website. If you do it’ll create a website-level override that can cause payment failures and order reconciliation issues.

   • Log in to your admin panel at /admin.
   • Navigate to Stores > Configuration (make sure default config is selected) > Sales > Payment Methods.
   • Select iwocaPay and configure the following:
     • Enabled: Yes
     • Seller Access Token: <Your key>
     • Seller ID: <Your ID>
   • Set Mode to Production mode.
   • Click Save Config

5. Clear your cache:

   magento cache:flush

Testing your setup

Before you go live, test your integration in our sandbox environment. See API and plugin testing for the full guide.

As a quick check, add items to your basket, proceed to checkout, and confirm that iwocaPay is available as a payment option.

Updating the iwocaPay plugin

Update the plugin regularly to get the latest features and fixes.

1. SSH into your server and navigate to the Magento 2 directory:

   cd /path/to/magento

2. Run the following command to update to the latest release:

   composer require iwoca/iwocapay-magento

   Tip

   If you encounter issues with the latest release, you can install a specific version instead. Replace VERSION_NUMBER with the version you want to install (for example, 1.2.3):

   composer require iwoca/iwocapay-magento:VERSION_NUMBER

3. Apply the update:

   composer update iwoca/iwocapay-magento --with-dependencies

4. Clear cache and update dependencies:

   magento setup:upgrade
   magento cache:clean && magento setup:di:compile

Configuring iwocaPay payment options

You configure the payment terms and the pricing structure through the universal pay link in your iwocaPay dashboard.

In Magento, you can also choose whether to show only Pay Later at checkout, or both Pay Later and Pay Now. Pay Now is always free for both you and your customers.

To choose which payment options appear:

• Log in to your admin panel at /admin
• Go to Stores > Configuration > Sales > Payment Methods
• Select iwocaPay.
• Use the Allowed payment terms drop-down menu to choose your preferred options.
• Changes update automatically.

Removing iwocaPay

If you need to remove iwocaPay from your checkout, follow these steps:

• Enable maintenance mode on your server.
• Disable the extension, update dependencies, and clear your cache.
• Verify the removal.
• Remove the module files from the app directory.
• Disable maintenance mode.

To reinstall iwocaPay in the future, you’ll need to follow the installation steps again.

How orders work in Magento

Order lifecycle

When a buyer selects iwocaPay at checkout, the extension creates an order via the iwocaPay ecommerce API. The order progresses through these statuses:

iwocaPay status	Magento status	What happened
CREATED	Pending payment	Order placed, buyer redirected to iwocaPay checkout
PENDING	Pending payment	Buyer has started their application or login
APPROVED	Pending payment	Buyer approved for credit (Pay Later only)
SUCCESSFUL	Processing	Payment confirmed — buyer completed checkout
UNSUCCESSFUL	Cancelled	Buyer declined, abandoned, or payment failed

The extension doesn’t use webhooks. An hourly reconciliation job checks the iwocaPay API for orders still in Pending payment, and updates the Magento order to match. When it finds SUCCESSFUL, it moves the order to Processing, triggering standard Magento fulfilment workflows (invoicing, stock commitment, shipment creation). While an order is still PENDING, the job keeps it alive so the Magento timeout (see below) doesn’t cancel it prematurely — for up to 72 hours.

Checkout timing

New buyers without an existing Spending Limit go through the iwocaPay credit assessment and security checks before they can check out with Pay Later. For some new customers, we run additional manual checks that can take around an hour. For returning buyers with an active Spending Limit, checkout takes a few minutes.

During this time, the Magento order sits in Pending payment with stock reserved per the Magento inventory rules. The Magento default behaviour is to cancel Pending payment orders after a configurable timeout, so set this long enough to allow for the checkout duration above.

Abandoned and cancelled orders

Scenario	What happens
Buyer is declined	The reconciliation job detects UNSUCCESSFUL and doesn’t prolong the order’s life. The Magento Pending Payment Lifetime timeout then cancels it and releases stock.
Buyer abandons mid-checkout	No automatic cancellation signal. The order stays in Pending payment — kept alive for up to 72 hours while iwocaPay reports it as PENDING — until the configurable Magento timeout cancels it.
Buyer clicks back to store	Magento cancels the order locally and queues it for cancellation on iwocaPay’s side, synced within 15 minutes. This is on by default and can be turned off in the admin settings.
Seller cancels	Call DELETE /ecommerce/order/{orderId}/ to cancel on iwocaPay’s side. Cancelling in the Magento admin only cancels the order locally — it doesn’t notify iwocaPay.

Fulfilment

Once the order reaches SUCCESSFUL, Magento moves to Processing. You create a shipment and invoice as normal, through the Magento admin or your order management system.

Reconciliation

The extension passes the Magento increment ID as the order reference at creation, so it’s available if you need to match orders against your own payment records. The reconciliation job (hourly) keeps Magento order statuses up to date — not in real time.

Known considerations

• Custom order workflows: The Magento order state machine is highly customisable. If you use custom statuses or transitions, map these against the iwocaPay order statuses during integration.
• Abandoned order cleanup: Silent abandonment (no decline, no completion) doesn’t trigger cancellation. The native Magento Pending Payment Lifetime cron setting can help, but set it long enough not to conflict with legitimate checkout times.
• Multi-website / multi-store: iwocaPay supports one seller account per Magento installation. Website-level credential overrides aren’t fully supported — the reconciliation and cancellation cron jobs always use the default-scope credentials, regardless of the order’s website.
• Third-party system dependencies: Identify the third-party systems that interact with iwocaPay and account for any dependencies.