Payments for Stripe (OpenCart 4)

Overview

Take card, wallet and local payments through your own Stripe account on OpenCart 4.1 with the Stripe Payment Element on the Payment Intents API. Stripe shows each customer the payment methods that fit their country, currency and amount (cards, Apple Pay, Google Pay, Link and the local methods you switch on in your Stripe Dashboard, such as iDEAL, Bancontact, BLIK, EPS, Przelewy24, SEPA Direct Debit or Klarna), and runs 3D Secure / Strong Customer Authentication when the bank asks for it. Charge at once or authorize and capture later; cancel authorizations, full and partial refunds from the order page.

What it does

• One modern form. The Payment Element is loaded from js.stripe.com (version endive, the same release train as the pinned API version 2026-10-28.endive). Card and bank details are typed into Stripe's own iframes and never reach your server. Accordion or tabs layout, Stripe / Flat / Night style and your accent colour.
• Restricted keys, as Stripe requires. Stripe asks third-party integrations to use restricted API keys (rk_) instead of secret keys. The extension accepts only restricted keys and tells you exactly which permissions to give it. The key and the webhook signing secret are stored encrypted.
• Paid means paid. An order moves to your paid status only when the shop read the PaymentIntent back from Stripe, its amount, currency and reference are the ones the shop sent, and the order still costs that amount. If the cart changed while the customer paid (or the order was edited while a bank payment was processing), the money is kept and the payment is flagged on the order, never marked paid: you accept it, refund it or cancel the authorization with one click. Only a second payment of an order that is already paid is refunded automatically. A total that changed before the customer pressed Pay updates the PaymentIntent first; the customer sees the new amount.
• Bank payments that take days. Methods such as SEPA Direct Debit stay "processing" at Stripe for days. The order waits in your "Processing at Stripe" status (default Pending) with a "Do not ship yet" note, the customer sees a waiting page, and the order is marked paid when Stripe confirms. It is never shown as cancelled while Stripe is still processing it.
• Redirect methods on OpenCart 4.1. OpenCart 4.1 sends its session cookie with SameSite=Strict, so a customer who returns from a bank page would lose the session. Stripe returns the customer to a small bounce page (extension/kv_stripe/return.php) that continues inside the shop, so the success page, the emptied cart and a signed-in account all keep working.
• Never twice. Every create, update, capture, cancel and refund carries an idempotency key that is stored before the request. A lost answer is sent again with the same key, or reconciled by reading the payment back (Stripe caches a 5xx answer for its key); nothing is sent twice.
• Signed webhooks. Events arrive on a parameter-free endpoint and are checked with their Stripe-Signature on the raw body with a 5-minute tolerance; each event is applied once and only triggers a read-back from Stripe.
• Updates keep your data. OpenCart 4 updates are uninstall + install: payment records, settings and keys survive.

Requirements

• OpenCart 4.1.0.x, PHP 7.4 to 8.3 with cURL and OpenSSL, HTTPS on the live shop.
• Your own Stripe account. Stripe's fees apply.

Not in 1.0

Saved cards and subscriptions, Express Checkout buttons on the product or cart page, Stripe Tax, multicapture. Voucher and cash methods that customers pay days later (Multibanco, OXXO, Boleto, Konbini) are not offered. OpenCart 3 is not supported (no OpenCart 3 package is shipped).

Stripe is a trademark of Stripe, Inc. This extension is independent software by Kavio Labs that integrates with the Stripe API; it is not affiliated with or endorsed by Stripe.

Installation

1. Install the extension. Extensions > Installer > Upload kv_stripe.ocmod.zip, then Install.
2. Install the payment method. Extensions > Extensions > Payments > Payments for Stripe > Install, then Edit.
3. Keys (test mode first). In the Stripe Dashboard switch to test mode (sandbox) and open Developers > API keys.
   • Copy the publishable key (pk_test_...).
   • Click Create restricted key and give it Payment Intents: Write, Charges and Refunds: Write and, if you want the domain button, Payment Method Domains: Write. Everything else stays None. Copy the key (rk_test_...).
   • Secret keys (sk_...) are refused: Stripe requires third-party integrations to use restricted keys.
   • Enter both in the "Test mode keys" block on the Connection tab and press Save and test connection.
4. Webhook. Webhooks, log and cron tab: copy the webhook endpoint URL (https://your-shop/extension/kv_stripe/notify.php). In the Dashboard open Developers > Webhooks > Add endpoint, paste the URL and select the events listed on the tab (payment_intent.succeeded, payment_intent.processing, payment_intent.payment_failed, payment_intent.amount_capturable_updated, payment_intent.canceled, charge.refunded, charge.refund.updated, charge.dispute.created, charge.dispute.updated, charge.dispute.closed). Copy the endpoint's signing secret (whsec_...) into the test block.
5. Payment methods. In the Dashboard open Settings > Payment methods and switch on the methods you want. The Payment Element shows each customer the ones that fit.
6. Payment tab: switch the method on; choose the layout, the style and your accent colour.
7. Capture and statuses tab: charge at once (recommended) or authorize only; when to capture; the order statuses.
8. Place a test order with a Stripe test card (4242 4242 4242 4242, any future date, any CVC). Test mode is hidden from your customers until you tick "I confirm: show the payment method to real customers in test mode" on the Connection tab; tick it only on a test shop. Test orders get the note "TEST MODE (Stripe sandbox): no money moved" and no e-mail.
9. Go live. Create a live restricted key with the same permissions and a live webhook endpoint, enter the live keys, switch the mode to Live and test the connection again. On the live shop press Register your-domain with Stripe (or add the domain under Settings > Payment method domains) so Apple Pay, Google Pay and Link appear.
10. Cron. Make sure the OpenCart cron runs (*/10 * * * * php /path/to/cron.php). The extension adds an hourly job.

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

Settings > Webhooks, log and cron > Remove all data (type DELETE) deletes the payment records, the log, the keys and the kept settings. It is refused while a payment is processing or unclear or an authorization is not captured or cancelled. The licence stays.

Configuration

Usage

At checkout

The customer chooses "Card, wallet or bank payment". The confirm step loads the Stripe Payment Element with the methods that fit the order, and a Pay amount currency button. On Pay the shop first checks that the order still costs what the form shows (if not, the amount is updated and the customer is asked to press Pay again), then Stripe confirms the payment, with 3D Secure when the bank asks for it.

• Cards and wallets: the customer lands on the success page after the shop has read the payment back from Stripe.
• Redirect methods (iDEAL, Bancontact, BLIK, Klarna ...): the customer approves at the bank and comes back through the bounce page to the success page.
• Bank debits (SEPA Direct Debit ...): Stripe processes them for days. The basket is emptied, the customer sees a waiting page, the order waits in "Processing at Stripe" and becomes paid when Stripe confirms. It is never shown as cancelled meanwhile.
• Declines: Stripe's message ("Your card was declined.") appears; nothing is charged and the customer can try again on the same form.

On the order page

Sales > Orders > the order > Stripe tab:

• Amount, status, PaymentIntent id with a link to the Stripe Dashboard, payment method (card brand and last four digits, wallet), 3D Secure result, dispute status, every operation.
• Capture (authorizations): once, up to the authorized amount; a lower amount releases the rest.
• Cancel authorization: the customer is not charged.
• Refund: full or partial, several times, with an optional Stripe reason (requested by customer, duplicate, fraudulent).
• Accept as paid (amount mismatch only): books the payment although it does not match the order total.
• Read back: reads the payment from Stripe (also picks up refunds made in the Dashboard) and reconciles operations without a clear answer.

Automatic actions

• Authorize only + capture at status: changing the order to Shipped (or a complete status) captures; Canceled cancels the authorization.
• A payment that no longer matches the order total is kept and flagged ("Amount mismatch (money kept, not marked paid)"); the settings page shows a red notice and the Stripe tab offers Accept as paid, Refund and Cancel authorization. An authorization that does not match is never captured by an order status.
• A second payment of an order that is already paid (or cancelled) is refunded or cancelled automatically and noted.
• If a capture by order status cannot be done (Stripe busy, an earlier operation unclear), the order history says so with the date Stripe would cancel the authorization, and the cron tries again while the order stays in the capture status.
• A refund that fails at the bank later is written to the order history ("the customer has NOT got this money back").
• An authorization Stripe cancels after 7 days without capture gets a history note; after 5 days the order history gets a warning and the settings page counts it.
• Unpaid attempts older than 48 hours are cancelled at Stripe (reason "abandoned"); the order is not touched.
• Dispute events add a history note (and, if you chose one, the dispute status).

Developer notes

Decisions

• Payment Element with PaymentIntents, intent-first. "Create a PaymentIntent before collecting payment details" (accept-a-payment, payment-ui=elements&api-integration=paymentintents): the server creates the PaymentIntent, the browser initialises Elements with its client secret and confirms with stripe.confirmPayment. Stripe recommends Checkout Sessions for most new integrations; the brief asked for PaymentIntents, which keeps the OpenCart order total in charge of the amount.
• No stripe-php. The official library is MIT licensed and supports our PHP range, but it is several MB, autoloads through Composer, and we use eight endpoints. Direct REST calls keep the package small; the one algorithm we reproduce (webhook signature) is documented step by step by Stripe.
• Restricted keys only. "Migrate a plugin to Stripe Apps or Stripe Connect" (stripe-apps/plugins/decide-migration): "Starting September 30, 2024, all plugin developers must use secure authentication methods (OAuth 2.0, restricted API keys, Stripe Connect)"; for self-hosted back ends set up by hand: "Validate API Keys: Make sure businesses give you restricted API keys that start with the prefix with rk_, not sk_." Config::keyProblem() refuses sk_. Permissions (stripe-apps/reference/permissions): Payment Intents payment_intent_write, Charges and Refunds charge_write (refund create and list, latest charge read), optional Payment Method Domains payment_method_domain_write. A Stripe App (RAK install flow) is a possible later step and needs a Stripe account of ours.
• Pinned version, same train in the browser. "Set Stripe's API version in your plugin" (building-plugins); "The current version is 2026-10-28.endive" (api/versioning); "keep the Stripe.js version and server-side API version on the same release train" (sdks/stripejs-versioning). Webhook payloads use the account's default version; the handler reads only id, type, livemode, data.object.object/id/payment_intent (and dispute status, reason, amount, currency) and reads the PaymentIntent back with the pinned version, so the account version does not matter.
• Identification. building-plugins: without an official library "set the value of the User-Agent header on requests made to the Stripe API as name/version (url)" with the platform in the name: OpenCart KavioPaymentsForStripe/1.0.0 (https://kaviolabs.com); in the browser stripe.registerAppInfo({name, version, url}).

Every call, header and field, with its source

Sources, all read 2026-11-08 from docs.stripe.com (Markdown copies in the build workspace scratchpad/oc-stripe/apidocs/): api/authentication, api/versioning, api/idempotent_requests, api/errors, error-low-level, error-codes, api/payment_intents/{create, update, retrieve, search, capture, cancel, object}, api/refunds/{create, list, object}, api/charges/object, api/payment_method_domains/create, payments/payment-methods/pmd-registration (API), payments/accept-a-payment (Elements + Payment Intents), payments/place-a-hold-on-a-payment-method, payments/paymentintents/lifecycle, js/initializing, js/elements_object/create, js/elements_object/create_payment_element, js/payment_intents/confirm_payment, sdks/stripejs-versioning, webhooks, currencies, keys/restricted-api-keys, stripe-apps/plugins/decide-migration, stripe-apps/reference/permissions, building-plugins.

Every request (Api::call)

Calls

Payment states (Payments::derive)

succeeded -> captured / partial_refund / refunded; requires_capture -> authorized; processing -> pending (order in "Processing at Stripe", waiting page, never cancelled); canceled -> canceled; requires_payment_method, requires_confirmation, requires_action -> open (not paid; after processing an explicit failure), except requires_action with next_action.type *_display_details or display_bank_transfer_instructions -> pending (an offline payment the customer still makes; never cancelled; such methods are excluded at create anyway). An amount that differs from the order -> error / MISMATCH, money kept, admin "Accept as paid"; only a duplicate (second payment of a paid order) is reversed automatically. Source: api/payment_intents/object status, payments/paymentintents/lifecycle.

Browser (Stripe.js)

Webhooks (Webhook::verify, Payments::webhook)

Money (Money)

ISO 4217 exponents from tooling/release-templates/cscart/iso4217/gen.py (checked with --check); Stripe "amount" is the minor unit as Stripe defines it (currencies: "Currencies are two-decimal currencies unless otherwise specified"; zero-decimal list BIF CLP DJF GNF JPY KMF KRW MGA PYG RWF UGX VND VUV XAF XOF XPF; special case ISK "represent it as a two-decimal value, where the decimal amount is always 00"). Factor 1 where ISO and Stripe agree, 100 for ISK, refused where they disagree without a rule (MGA) or the page contradicts itself (UGX is on the zero-decimal list and in the special cases as two-decimal). Presentment currencies: union of the per-country lists on the currencies page (BHD, JOD, KWD, OMR, TND are not listed). Minimum amounts are left to Stripe (amount_too_small -> the customer is told).

OpenCart specifics

• OpenCart 4.1 sends the session cookie with SameSite=Strict (system/config/default.php session_samesite), so the bank return goes through return.php (no OpenCart boot, no cookie, parameter whitelist) and SameSite::bounce() as a second line.
• Order history through model_checkout_order->addHistory (catalog) or the store instance in the admin (createStoreInstance), so mails and stock behave like core payments.
• Uninstall keeps data (Install::drop($purge = false), Keep snapshot restored by install()), as OpenCart 4 updates are uninstall + install.

Tests

• tests/unit.php (PHP 8.1 and 8.3, 97 checks) against tests/mock-server/server.js (follows the sources above; never talks to Stripe) and a throw-away MariaDB database.
• tests/e2e.js (53 checks) on an OpenCart 4.1.0.4 dev store; refuses to run unless the provider base is a loopback mock.
• tooling/release-templates/oc-upgrade/upgrade-test.js oc_stripe <store>: data, settings and licence survive the OpenCart 4 update path.

Conformance with the Stripe documentation (OpenCart)

Checked against the Stripe API reference and guides listed in developer.md, 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: money rules, webhook signatures with tolerance and rolled secrets, create / reuse / update / pay, declines, capture later, partial capture, refunds, cancel, processing payments, mismatches, duplicates, idempotent retries after a lost answer, a dropped connection, 409 and 429, Dashboard refunds, abandoned attempts), browser tests on OpenCart 4.1.0.4 against the same stand-in (settings and restricted keys, the Payment Element form, card, decline, changed total, redirect method through the SameSite bounce, processing payment with the waiting page and a signed webhook, forged webhooks, order tab refund / capture / cancel, cron) and the OpenCart 4 update path. It has not been run against a real Stripe account: no Stripe key of ours was used. Confirm the points below once with your own test-mode keys.

Points to confirm with a real test-mode account

1. A restricted key with exactly Payment Intents Write + Charges and Refunds Write can create, update, read (with expand[]=latest_charge), search, capture, cancel and refund (a missing permission is shown as "The restricted key lacks a permission").
2. The Payment Element shows the Dashboard methods in accordion and tabs layout; wallets on a registered HTTPS domain.
3. A 3D Secure test card (4000 0027 6000 3184) and an iDEAL / Bancontact test redirect return through return.php to the success page.
4. SEPA Direct Debit test payment: processing, then succeeded by webhook.
5. The webhook endpoint receives the listed events and "Send test event" from the Dashboard is answered 200 ("Ignored" for an unknown payment).

FAQ

Why a restricted key and not my secret key?

Stripe's "Migrate a plugin to Stripe Apps or Stripe Connect" guide: since 30 September 2024 third-party plugins must use secure authentication; for self-hosted integrations set up by hand: "Make sure businesses give you restricted API keys that start with the prefix rk_, not sk_". A restricted key can do only what you allow (here: payments and refunds), which limits the damage if it ever leaked.

Which payment methods?

Those you switch on in the Stripe Dashboard and that fit the order (country, currency, amount). With "Authorize only" Stripe offers only methods that support capturing later.

Multibanco, OXXO, Boleto, Konbini?

Not in 1.0. These voucher and cash methods wait days for the customer to pay offline; they are excluded from the Payment Element (excluded_payment_method_types) even if you switch them on in Stripe.

What happens if the order total changes while the customer pays?

Before Pay the payment is updated and the customer sees the new amount. If it still differs afterwards, the money is kept and flagged on the order; you accept, refund or cancel it on the Stripe tab. It is never marked paid by itself.

Do card numbers touch my server?

No. They are typed into Stripe's iframes; the shop only handles the PaymentIntent.

Which currencies?

The order's currency, as long as Stripe can present it (135 currencies; your account country decides the exact list). Amounts follow Stripe's rules: zero-decimal currencies such as JPY are sent as whole units, ISK as two decimals ending in 00. MGA and UGX are not offered because Stripe's and ISO 4217's decimals disagree for them; BHD, JOD, KWD, OMR and TND are not Stripe presentment currencies.

Do I need webhooks?

Strongly recommended: they confirm bank payments that take days and record disputes and Dashboard refunds. Card payments work without them (the shop reads every payment back), and the hourly cron reads processing payments back too.

Apple Pay and Google Pay do not appear. Register your live shop domain (Connection tab button, or Dashboard > Settings > Payment method domains) and use HTTPS. Wallets also need a supported browser and device.

Saved cards, subscriptions, Express Checkout buttons?

Not in 1.0.

Does it work on OpenCart 3?

No, OpenCart 4.1 only.

Does it change core files?

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

Is it affiliated with Stripe?

No. It is independent software that integrates with the Stripe API.