Scalapay Payments for OpenCart

Overview

Offer Scalapay at checkout on OpenCart 4.1: your customers pay in 3 or 4 instalments, or later, on Scalapay's own checkout page, and you receive the full amount from Scalapay. The extension creates the Scalapay order, sends the customer to Scalapay, reads the order back when the customer returns and captures it at once, or authorizes it with a delayed capture and captures when the order ships. Void, full and partial refunds from the order page. Scalapay's own OpenCart plugin covers OpenCart 1.x to 3.x; this extension is built for OpenCart 4.1.

What it does

• One option per Scalapay product. Tick the products your Scalapay contract includes (Pay in 3, Pay in 4, Pay Later): each becomes its own option at checkout, listed next to your other payment methods and never pre-selected. Tick none for one neutral "Scalapay" option.
• The Scalapay widget, where Scalapay recommends it. Optionally show Scalapay's own price widget below the product price, below the cart total and in the payment step. It uses Scalapay's texts, logo and information window and follows your amount limits.
• Paid means paid. An order moves to your paid status only after the shop read the order back from Scalapay as authorized, its amount equals what the shop sent AND what the order costs now, and Scalapay confirmed the capture. A changed order total, a second payment of a paid order or an authorization for a cancelled order is voided automatically and flagged, never marked paid.
• Capture at once or later. Standard flow: captured as soon as the customer returns. Delayed capture: the order is authorized for 1 to 5 days and captured when it reaches a status you choose (default Shipped) or by hand; voided when you cancel it.
• Never twice. Every create, capture, delay, void and refund is written down before it is sent, with Scalapay's Idempotency-Key. A lost answer is read back and re-sent only with the same key.
• A pending payment is never shown as cancelled. A customer who returns before Scalapay decided sees a waiting page (the basket is emptied so the order cannot be paid twice); the cron and the signed webhook pick up what the browser missed.
• Signed webhooks. Scalapay's webhooks arrive on a parameter-free address and are checked with their HMAC signature before the order is read back.
• Amount limits and countries. Minimum and maximum of your contract; offered only in EUR and for delivery to Austria, Belgium, Finland, France, Germany, the Netherlands, Italy, Portugal and Spain (the countries Scalapay names for its plugins).
• Neutral presentation (CCD2). The new EU Consumer Credit Directive applies from 20 November 2026. The extension helps you show Scalapay neutrally: no pre-selection, no claims about cost, ease or speed, details from Scalapay's own widget and page, an optional information line. This is not legal advice.
• Your key, kept safe. The API key is stored encrypted and never shown again; sandbox mode stays hidden from customers until you confirm it.
• Updates keep your data. Uninstalling keeps payment records, settings and keys, so refunds of older orders keep working after an update.

Requirements

• Tested on OpenCart 4.1.0.4 (built for 4.1.x), PHP 8.1 or newer with cURL and OpenSSL.
• A Scalapay merchant account and its API key (sandbox: the public test key Scalapay publishes works for first tests).
• Euro enabled as a store currency; the telephone field required at checkout (Scalapay needs the phone number).
• HTTPS for the live shop (Scalapay checkout returns the customer to your shop).

Scalapay is a trademark of its owner. This extension is independent software by Kavio Labs that integrates with the Scalapay API; it is not affiliated with or endorsed by Scalapay.

Installation

1. Install the extension. Extensions > Installer > Upload kv_scalapay.ocmod.zip, then Install.
2. Install the payment method. Extensions > Extensions > Payments > Scalapay Payments > Install, then Edit.
3. Before you start: enable Euro (System > Localisation > Currencies) and make the telephone field required (System > Settings > Option > Telephone required). The settings page warns you if either is missing.
4. Connection tab, sandbox first. Choose Sandbox. You can test at once with the public sandbox key Scalapay publishes (used automatically while the field is empty) or enter the sandbox key you received. Press Save and test connection; the answer "API key was accepted" proves the key works.
5. Payment tab: switch the method on; tick the Scalapay products of your contract (Pay in 3, Pay in 4, Pay Later) or none; enter the minimum and maximum order amount of your contract.
6. Widget tab (optional): switch the official widget on for the product page, the cart page and the checkout. In the sandbox the test merchant token is used; for live, enter the Live merchant token from the Developer section of the Merchant Portal (it is not the API key).
7. Capture and statuses tab: capture at once (standard flow, recommended) or use a delayed capture (by order status or by hand, 1 to 5 days); choose the order statuses.
8. Webhook (recommended). Copy the Webhook URL from the Connection tab and enter it in the Scalapay Merchant Portal (Developers section, Webhook Url).
9. Place a test order. Sandbox is hidden from your customers until you tick "I confirm: show Scalapay to real customers in sandbox mode" on the Connection tab; tick it only on a test shop. Use Scalapay's test card 5200828282828210 (any CVV, any expiry date) for a successful payment and 4000000000000341 for a failed one. Sandbox orders get the note "TEST MODE (Scalapay sandbox): no money was taken" and no e-mail.
10. Go live. Enter the live API key (Merchant Portal > Developer, starts with sp_), switch the mode to Live, test the connection again, enter the live merchant token for the widget and the Webhook URL in the live Merchant Portal.
11. Cron. Make sure the OpenCart cron runs (*/10 * * * * php /path/to/cron.php). The extension adds an hourly job that reads open payments back and re-sends unanswered operations.

Updating

Uninstall the payment method (Extensions > Payments > Uninstall), uninstall and delete the old files in the Installer, upload the new zip, install, install the payment method. Payment records, operations, the log, your settings and keys are kept. Open the settings page once afterwards.

Removing all data

Uninstalling keeps your data on purpose (payment records are needed for refunds of older orders). Settings > Log and cron > Remove all data (type DELETE) deletes the payment records, the log, the API keys and the kept settings. It is refused while a payment is open or an authorization is not captured or voided. The licence stays.

Configuration

Usage

At checkout

The customer chooses one of the Scalapay options (for example "Scalapay - Pay in 3 instalments") next to your other payment methods. The payment step explains, without promises, that Scalapay shows the plan and the terms before the customer confirms; with the widget on, Scalapay's own checkout widget shows the instalments. "Continue to Scalapay" opens the Scalapay checkout page. After confirming there, the customer comes back to your shop, the shop reads the order back, captures it (or requests the delayed capture) and shows the success page.

• Cancelled on the Scalapay page: the customer is back in the cart with a message and can choose another method. Nothing is charged.
• Back before Scalapay decided: the basket is emptied (so the order cannot be paid twice) and a waiting page updates by itself. It is never shown as cancelled while Scalapay may still approve it.
• Expired or declined: a clear message; nothing is charged.

Widget

With the widget switched on, Scalapay's own widget appears below the product price, below the cart total and in the payment step, for customers who shop in EUR and amounts within your limits. Its texts, logo and information window come from Scalapay.

On the order page

Sales > Orders > the order > Scalapay tab:

• Order amount, captured and refunded amounts, local and Scalapay status (and Scalapay's eligibility feedback when an order was declined), Scalapay order token, product, the "capture by" date of a delayed order.
• Capture (delayed orders): once, up to the authorized amount.
• Void: a delayed authorization that is not captured. The customer is not charged.
• Refund: full or partial, several times, up to the captured amount, with an optional reason.
• Read back: reads the order from Scalapay (also picks up captures made in the Merchant Portal) and re-sends operations without a clear answer.

Automatic actions

• Delayed capture by status: changing the order to Shipped (or a complete status) captures it; changing it to Canceled voids it.
• An order whose total changed while the customer was at Scalapay, a second payment of a paid order, or an authorization for an order you already cancelled is voided automatically and the order gets a history note; it is never marked paid. If the void fails, the settings page shows a red notice.
• A delayed capture that ends within 24 hours is listed on the settings page and in the log.

Developer notes

Sources

All read 2026-11-08 from the official developer site (copies in the build workspace scratchpad/oc-scalapay/apidocs/; the site publishes an index at https://developers.scalapay.com/llms.txt and every page as Markdown with its OpenAPI definition):

• API Architecture https://developers.scalapay.com/reference/api-architecture ("Arch")
• Payment flows https://developers.scalapay.com/reference/payment-flows-1, Standard order flow https://developers.scalapay.com/docs/standard-capture-flow, Delayed capture order flow https://developers.scalapay.com/docs/delayed-capture-flow ("Flows")
• API calls https://developers.scalapay.com/docs/custom-integration-api-calls
• Create order https://developers.scalapay.com/reference/post_v2-orders ("Create")
• Get order details https://developers.scalapay.com/reference/get_v2-payments-token ("Get")
• Get orders by reference https://developers.scalapay.com/reference/get_v2-payments-references ("Refs")
• Capture order https://developers.scalapay.com/reference/post_v2-payments-capture ("Capture")
• Delay order https://developers.scalapay.com/reference/post_v2-payments-token-delay ("Delay")
• Void order https://developers.scalapay.com/reference/post_v2-payments-token-void ("Void")
• Refund order https://developers.scalapay.com/reference/post_v2-payments-token-refund ("Refund")
• Webhooks https://developers.scalapay.com/reference/webhooks, Listener authentication setup https://developers.scalapay.com/reference/listener-authentication-setup, Webhook data model https://developers.scalapay.com/reference/wehook-data-model, Messages validation https://developers.scalapay.com/reference/messages-validation, Examples of webhook requests https://developers.scalapay.com/reference/examples-of-webhook-requests, Connection issues and retry system https://developers.scalapay.com/reference/connection-issues-and-retry-system ("Hooks")
• API Simulator https://developers.scalapay.com/reference/api-simulator; Test the order flow https://developers.scalapay.com/docs/test-the-order-flow ("Test")
• Widget installation https://developers.scalapay.com/docs/custom-integration-widget-installation, Widget configuration https://developers.scalapay.com/docs/custom-integration-widget-configuration ("Widget")
• Guidelines & best practices https://developers.scalapay.com/docs/best-practice-guideline ("Guide")
• OpenCart v2 and v3 plugin https://developers.scalapay.com/docs/opencart-v2-v3-plugin ("OC plugin": Scalapay's own extension for OpenCart 1.x to 3.x)
• Go Live https://developers.scalapay.com/docs/go-live

Every call, header and field, with its source

Unverifiable or flagged

• No merchant configuration API is documented. Older Scalapay integrations read limits from a configuration endpoint; the current reference index (llms.txt, 2026-11-08) lists none, and /reference/get_v3-configurations answers 404. The minimum and maximum are therefore merchant settings (default minimum 5.00 EUR from the OC plugin page).
• Amount format. The queue brief said "EUR minor units"; the official schema uses decimal strings ("Example: 187.95"). The extension follows the schema.
• Webhook version string. The documentation shows the version only in its examples ('V1', header x-scalapay-hmac-v1). V1 is tried first, v1 second. A signature is still required, and the body is never trusted.
• Signed bytes. The documented raw string is {version}:{timestamp}:{JSON.stringify(payload)}. The raw request body is verified first; the body re-encoded compactly (json_encode without escaped slashes) second, in case the bytes on the wire differ from Scalapay's stringify output. A body that matches neither is refused (401) and the order is still picked up by the return, the waiting page and the cron.
• Public test key and webhooks. In sandbox mode without an own key the HMAC key is the public test key, so anyone can sign a sandbox hook. Harmless: a hook only triggers a read-back.
• Comma decimals. Some documented examples write amounts with a comma ("40,70" in the Delay answer, "190,00" in a Capture example) while the schema says "187.95". Money::parse() accepts one comma when there is no dot.
• Status after a partial refund. Webhooks: refunded is "Triggered when a refund request is successfully processed", so it may come after a partial refund. It is acted on only when this shop made no refund itself (a refund in the Merchant Portal); the shop's own refunds are counted from their answers.
• Item prices. Items are sent with their net unit price and the tax in taxAmount, as the documented example adds up (items + shipping + tax - discounts = total). Rounding of OpenCart's per-line tax can leave a cent between the parts and totalAmount; the total is what Scalapay charges.
• 404 on Get. Only 422 invalid_token means "unknown order"; a 404 (not documented for this call) is treated as no clear answer and read again later.
• Webhook timestamp age. No maximum age is documented, so none is enforced; a replayed hook only causes a read-back.
• Statuses after void, delay and partial refund. The Get example shows charged and expired; the status of a voided order, of a delayed order and of a partly refunded order is not documented. The extension sets its own state from the 200 answer of each call and never moves a final state backwards on an unknown status.
• Refund amounts in Get. Get documents no refunded total. Refunds are tracked locally from the answers; an unclear refund is re-sent with the same Idempotency-Key within 24 hours, then flagged for a check in the Merchant Portal.
• Several captures. "Up to the total" is documented, several partial captures are not; 1.0 allows one capture per order (full or lower amount).
• Idempotency-Key lifetime is not documented; resends stop after 24 hours.
• Return query parameters. What Scalapay appends to the redirect URLs is not documented; the extension ignores them and reads the order back.
• Not run against the real sandbox. The rules forbid tests against the real sandbox; everything was proven against tests/mock-server/server.js, which follows the sources above. Run one real sandbox order with your own setup before going live (public key + test card 5200828282828210).

EU Consumer Credit Directive (CCD2)

Directive (EU) 2023/2225 (https://eur-lex.europa.eu/eli/dir/2023/2225/oj) brings "buy now, pay later" credit into the consumer credit rules (recital 69). Member States apply their national measures from 20 November 2026 (Art. 48(1)). Relevant for how a shop presents the method: advertising must be "fair, clear and not misleading" (Art. 7); advertising must carry a warning such as "Caution! Borrowing money costs money" (Art. 8(1)); Member States may ban advertising that "highlights the ease or speed with which credit can be obtained" (Art. 8(8)(a)); consent may not be inferred from default options such as pre-ticked boxes (Art. 15).

What the extension does to help: the options are listed next to the other payment methods and none is pre-selected; its own texts name the method and make no claims about cost, ease or speed; the instalment amounts, dates and terms come from Scalapay's own widget and checkout page; an optional "Information line" lets the merchant show a text their adviser asks for. Scalapay is the creditor; the merchant decides how the shop advertises. This is not legal advice.

Internals worth knowing

• Return through return.php (OpenCart 4.1 session cookie is SameSite=Strict). system/config/default.php sets session_samesite = 'Strict' and the store setting config_session_samesite defaults to Strict. A browser coming back from scalapay.com does not send a Strict cookie, so OpenCart would start a new empty session on that request and overwrite the customer's cookie (cart, sign-in lost; the e2e test reproduced it with a cross-site form post). return.php does not boot OpenCart, sets no cookie, checks the four parameters (txn digits, k 32 hex, c, language) and continues with a same-site navigation (meta refresh + location.replace) to .back, where the cookie is sent again.
• Statuses. The waiting statuses (pending_status_id, authorized_status_id) never count as "further along" (OpenCart 4.1 lists Pending as a processing status), so a confirmed payment always moves the order on. A delayed authorization that expires uncaptured moves the order to "Scalapay authorization expired"; a capture by status that finds the newest attempt expired, voided or declined writes a history note instead of skipping silently. A delay refused by Scalapay falls back to an immediate capture; a refused automatic capture voids the authorization.
• Never the default option. OpenCart 4.1's payment dialog pre-checks the first option when none is chosen (checkout/payment_method.twig: !method && first). The getMethods/after model event moves Scalapay behind the first other method; when Scalapay is the only method OpenCart still pre-checks it, and the customer confirms on Scalapay's page.
• Payments::start() (under the order lock): earlier attempts first (paid or reserved = success; created without an answer or approved with a running capture = "busy"; pending = the customer left Scalapay: Scalapay has no call to withdraw an order that is not authorized, so a new attempt is allowed and a late authorization of the old one is voided as a duplicate). Amount from the order in its own currency (EUR only), limits checked, payload built, row with the Idempotency-Key BEFORE the call; a retryable failure re-sends once with the same key, then keeps the attempt created for the cron, which finds the token by merchant reference.
• Payments::applyRemote(): under the order lock and GET_LOCK('kvscalapay_<shop>_t<id>'); only open attempts can become paid; an authorization whose amount or currency differs from the created order, or whose OpenCart order total changed meanwhile (Orders::sameTotal() with the order's own stored rate), becomes error / MISMATCH, gets a visible "Payment amount mismatch" status (unless the order is already further along) and is voided after the locks are released; a second authorization of a paid order, or one that arrives after the order was cancelled, is a duplicate and is voided. A good authorization becomes approved and is captured (standard flow) or delayed (delayed flows) after the locks are released; the order status moves only when Scalapay confirmed the capture or the delay.
• States: created -> pending -> approved -> captured / authorized (delayed) -> partial_refund / refunded; voided, expired, declined (capture refused), failed (never created), error (mismatch, duplicate). open() = created, pending, approved: the waiting page keeps waiting, the cron keeps reading.
• Operations (kv_scalapay_op): creating -> done / failed / unknown; before a resend the order is read back (capture: charged = done; void: expired = done); the rest is re-sent with the same key within 24 hours.
• Customer return while still open: the basket is cleared like checkout/success does (cart->clear() deletes a signed-in customer's saved rows) and the waiting page polls; a return through the cancel URL with nothing authorized goes back to the cart with a message.
• Tests: php81 tests/unit.php and php83 tests/unit.php (needs node tests/mock-server/server.js 11983 and MariaDB 3307), node tests/e2e.js on a dev store (STORE=oc41). The hidden setting payment_kv_scalapay_base_url (loopback hosts only) points the extension to the mock; tests/e2e.js refuses to run unless the store's endpoint is a loopback address, and answers the widget script with a local stand-in so cdn.scalapay.com is never contacted.

Conformance with the Scalapay documentation (OpenCart)

Checked against the Scalapay developer documentation (developers.scalapay.com, the OpenAPI definitions of the Orders and Refund API, the webhook and widget pages; see developer.md for every source), read 2026-11-08.

How it was proven: unit tests against a local stand-in that follows those sources (PHP 8.1 and 8.3, including the documented webhook signature example), browser tests on OpenCart 4.1.0.4 against the same stand-in (settings, sealed key, products as checkout options, widget on product / cart / checkout, redirect, confirm and return, capture, cancel on the Scalapay page, waiting page, signed webhooks on the shop's endpoint, forged webhooks refused, amount mismatch, refunds, delayed capture and void on admin status changes, cron), and the OpenCart 4 update path. It has not been run against the real Scalapay sandbox: tests never call a real provider. Confirm the points below once with your own set-up.

To confirm with your own set-up

• One sandbox order with test card 5200828282828210 and one declined with 4000000000000341.
• One delayed capture (if enabled for your account) and one void.
• One partial refund.
• The webhook URL entered in the Merchant Portal reaches /extension/kv_scalapay/notify.php (firewall or bot filter).

Not covered in 1.0.0

Several captures per order, Pay by link, in-store orders, travel extensions, subscriptions, OpenCart 3 (Scalapay's own plugin covers OpenCart 1.x to 3.x).

FAQ

Do I need a Scalapay account?

Yes, a Scalapay merchant account and its API key. For first tests the extension uses the public sandbox key Scalapay publishes in its documentation.

Who pays the customer's instalments, and who carries the risk?

Scalapay. The customer agrees to the plan with Scalapay on Scalapay's page; you receive the order amount from Scalapay under your contract, minus Scalapay's fees.

Which currencies and countries?

Euro only, and delivery to Austria, Belgium, Finland, France, Germany, the Netherlands, Italy, Portugal and Spain, as Scalapay states for its plugins. Use the geo zone to narrow it further.

Where do the minimum and maximum come from?

From your Scalapay contract; you enter them on the Payment tab. Scalapay publishes no API to read them. Its plugin documentation names 5.00 EUR as the default minimum.

Should I capture at once or later?

At once is Scalapay's standard flow. Delayed capture (if enabled for your account) keeps the authorization for up to 5 days until you ship; capture or void it in time.

Can I capture in several parts?

1.0 captures once (the full or a lower amount). Refunds can be partial and repeated.

Is the widget required?

No, it is optional. Scalapay recommends it below the product price and the cart total. It is loaded from Scalapay's CDN only on the pages you switch on.

What about the EU Consumer Credit Directive (CCD2)?

Directive (EU) 2023/2225 applies through national laws from 20 November 2026 and covers buy now, pay later credit. The extension helps you present Scalapay neutrally (no pre-selection, no claims about cost, ease or speed, details from Scalapay's own widget and page, an optional information line). Check your shop's wording with your adviser; this is not legal advice.

Does it work on OpenCart 3?

No, OpenCart 4.1 only. Scalapay offers its own plugin for OpenCart 1.x to 3.x.

Does it change core files?

No. Events and a cron job only, no OCMOD.