Payments for Vendure
One payments plugin for Vendure: eleven payment systems — Stripe, Adyen, PayPal, Mollie, Square, Braintree, GoCardless, Checkout.com, crypto, bank transfer and pay-later — behind a single contract, with a hosted checkout page, wallets, 3-D Secure, captures, refunds, disputes, saved cards, subscriptions, pay-by-link, routing and one ledger.
Install on Vendure: add the package with npm, yarn or pnpm, then register HuloPaymentsPlugin in vendure-config.ts. All steps
npm
npm install @huloglobal/vendure-plugin-payments yarn
yarn add @huloglobal/vendure-plugin-payments pnpm
pnpm add @huloglobal/vendure-plugin-payments Register it in vendure-config.ts
// vendure-config.ts
import { HuloPaymentsPlugin } from '@huloglobal/vendure-plugin-payments' ;
export const config: VendureConfig = {
plugins: [
HuloPaymentsPlugin.init({
publicBaseUrl: 'https://shop.example.com' ,
licenceKey: process.env.HULO_LICENCE_KEY_PAYMENTS,
}),
// ... your other plugins
],
};What it does
Built for production from day one.
Vendure ships a Stripe plugin, a Mollie plugin and a Braintree plugin, each with its own shape, its own gaps and no view across them. Payments gives you eleven payment systems behind one contract: the storefront asks which to offer and gets a session; the provider's client renders cards, Apple Pay, Google Pay, iDEAL, Klarna and the rest; the plugin verifies the result with the provider before Vendure records the payment. Manual capture, partial captures and refunds work the same way on every provider. Webhooks are signature-checked and idempotent, disputes land in the ledger and alert ops, signed-in customers can save a card (licensed), any product variant can become a subscription (billed natively by Stripe, PayPal or Mollie, or by the plugin's scheduler from an Adyen token; licensed), and any unpaid order can be settled by a payment link (free for the hosted page and Stripe). Provider order, fallback on decline, eligibility rules and surcharges are per channel. Stripe, bank transfer, pay later, the hosted checkout page, pay links, the ledger and the dashboard are free; the other eight providers need a licence. Everything lands in one ledger with a dashboard under Sales → Payments.
Hosted checkout page, free
One mutation and a redirect. The plugin serves a branded payment page that lists every enabled method, drives each provider's own client (Stripe Payment Element, Adyen Drop-in, PayPal buttons, Square, Braintree, hosted redirects, bank-transfer instructions) and sends the customer back to your storefront paid. No provider code in your storefront at all.
Eleven payment systems, one contract
Stripe, Adyen, PayPal, Mollie, Square, Braintree, GoCardless, Checkout.com, Coinbase Commerce (crypto), bank transfer and pay-later / invoice — all as Vendure payment method handlers with the same capture, refund, webhook, ledger and admin behaviour. Connect any of them from the Payments page: paste the keys, the plugin checks them, sets up the webhook and creates the method. Stripe, bank transfer and pay later are free; the other eight need a licence.
Wallets and local methods included
Apple Pay, Google Pay, Link, iDEAL, Bancontact, Klarna, SEPA, PayPal, Venmo and Pay Later — whatever each provider enables shows up in its hosted element with 3-D Secure handled by the provider.
Verified server-side
The storefront never decides a payment state. The plugin re-reads the intent, session or order from the provider and checks amount, currency and order code before addPaymentToOrder.
Capture control
Automatic or manual capture per method, partial captures, cancels, full and partial refunds — all from the normal Vendure order and refund screens.
Signed, idempotent webhooks
Stripe signatures, Adyen HMAC, PayPal verification, Square and Checkout.com HMAC, GoCardless and Coinbase signatures, Mollie fetch-back. Each payment method has its own endpoint, <publicBaseUrl>/hulo-payments/webhook/<handler code> (for example /hulo-payments/webhook/hulo-stripe); the Providers tab shows the exact URL. Duplicate deliveries are ignored; payments, refunds and subscriptions are updated; a webhook log shows every delivery.
Disputes
Chargebacks reported by Stripe, Adyen, PayPal, Mollie, Square, Checkout.com and GoCardless land in the ledger with their reason and alert ops by webhook or email (Braintree, Coinbase Commerce, bank transfer and pay later report none).
Dashboard refunds reconciled
Switch it on per channel and a refund made in the provider's own dashboard becomes a settled Vendure refund on the order's payment, once, with an order-history note — never more than is left to refund. Free.
Saved cards
With a licence: Stripe Customers and Adyen stored payment methods for signed-in customers, listed and removed through the shop API.
Subscriptions
With a licence, set a billing interval on any product variant. The order charges the first period; Stripe, PayPal and Mollie bill natively, Adyen renewals are charged by the plugin from the stored card. Dunning, MRR, customer self-service cancel, admin pause / resume / cancel.
Pay by link, free
One click creates a payment link for any unpaid order — draft orders, accepted quotes, phone orders: this shop's own hosted payment page, or a provider-hosted page (Stripe on the free tier, the other providers with a licence), deposits and balances included. The payment or the provider's webhook settles it.
Routing, rules and surcharges
Provider order per channel and an eligibility checker (amount band, currencies, countries, customer groups, signed-in only) for any payment method, free; with a licence, fallback to the next provider after a decline and optional per-provider surcharges.
Rate limits
Per-IP limits on the public routes: the hosted page, its actions, webhooks and CSP reports.
One ledger, one dashboard
Authorisations, captures, refunds, disputes, failures, renewals and pay-links by provider and day, success rate, subscriptions and settings under Sales → Payments. Light and dark themes.
No SDKs, PostgreSQL ready
Each provider is a handful of REST calls on the platform fetch; tables are created on boot on MySQL, MariaDB and PostgreSQL.
MySQL, MariaDB & PostgreSQL
The plugin follows whatever database your Vendure dbConnectionOptions use — no configuration. Verified against PostgreSQL 17; MySQL/MariaDB installs are unchanged.
Buy & activate from the admin
The 14-day evaluation starts by itself, with no card. Subscribe or buy lifetime from the plugin's admin page — checkout opens in a new tab and the key installs itself within a minute, renewals included. The same card shows your plan, first-charge date and a Manage billing link to the Stripe portal (update card, cancel, switch plan). Already have a key? Paste it into the same banner. No .env edit, no redeploy; environment keys still take precedence for infrastructure-as-code setups.
Weekly report, set-up checklist & dashboard widget
With a licence (or during the first 14 days), every Monday the plugin emails whoever runs the store a short report of what it did that week — real numbers from your own database, week-over-week, with the next set-up step to take — and the plugin page opens with a set-up checklist that hides itself once everything is done. Change the recipient, send a test or switch the report off from the plugin's Settings tab (needs the host's SMTP_* settings). If the licence lapses, the report stops and the checklist is hidden; their settings are kept. The dashboard widget (Dashboard → Add widget) is free and shows the plugin's recent numbers.
One-click in-app updates
When a new version ships, an update banner shows current → latest with a What's-new link to the changelog. "Update now" installs the registry-verified release via your project's own package manager (yarn/npm/pnpm auto-detected) and gracefully restarts under pm2/systemd. Disable with HULO_SELF_UPDATE=off.
Install
Four steps, five minutes.
Add the package
Or run the one-line installer that does steps 1–3 for you:
Prefer to do it by hand?
npm
yarn
pnpm
Register it
In your vendure-config.ts:
Compile the admin UI
Add the extension to your compileUiExtensions call so the plugin's page appears in the admin:
Run the migration
Tables are created on boot; the only migration is Vendure's own, for the three subscription custom fields the plugin adds to ProductVariant. Generate and run it like any other:
That's it. Restart Vendure and the plugin's page is in the admin with every feature on for 14 days — no card, no key. To keep it all on afterwards, open the page and click Subscribe (first charge when the 14 days end) — the key installs itself, no .env edit, no redeploy.
Free tier vs licensed
Try the whole thing, keep the core for free.
Every new install has every feature on for its first 14 days, with no card and no key. After that the free tier keeps working indefinitely, and a licence keeps the licensed features on. If a licence lapses, the licensed features stop and nothing is deleted.
Free tier (after the 14 days)
- Stripe: sessions, wallets, 3-D Secure, automatic or manual capture, refunds, disputes, signed webhooks
- Bank transfer and pay-later / invoice methods
- The hosted checkout page, provider order per channel and the hulo-payment-rules eligibility checker
- Pay links: the hosted page or Stripe, deposits and balances included
- Refunds made in a provider dashboard reconciled into Vendure (opt-in)
- Per-IP rate limits on the hosted page and webhooks
- The payments ledger, disputes, dashboard and webhook log
First 14 days + licensed
- Adyen, PayPal, Mollie, Square, Braintree, GoCardless, Checkout.com and Coinbase Commerce, and their pay links
- Subscriptions and the renewal scheduler
- Saved cards
- Surcharges
- Fallback to the next provider after a decline
- The weekly report and set-up checklist
HTTP endpoints
Every route exposed.
/hulo-payments/pay/:tokenPublic: the hosted checkout page for one order/hulo-payments/webhook/:handlerCodeProvider webhooks, one URL per payment method handler, e.g. /hulo-payments/webhook/hulo-stripe/hulo-payments/dashboardAdmin: KPIs by provider and day, subscriptions/hulo-payments/transactionsAdmin: the ledger, filterable/hulo-payments/providersAdmin: configured methods, capabilities, webhook URLs/hulo-payments/subscriptionsAdmin: subscriptions (cancel / pause / resume actions)/hulo-payments/pay-linkAdmin: payment link for an unpaid order (hosted page or Stripe free; other providers licensed)/hulo-payments/settingsAdmin: routing, surcharges, ops per channelhuloHostedCheckoutShop: URL of the hosted checkout page for the active orderhuloPaymentProvidersShop: providers to offer for the active orderhuloCreatePaymentSessionShop: client secret / session / checkout URLhuloMySubscriptionsShop: the customer's subscriptions (+ cancel)/hulo-payments/metaAdmin: licence + evaluation + update status/hulo-payments/licence/activateAdmin: activate a licence key from the admin UI/hulo-payments/update/runAdmin: one-click in-app update + graceful restart/hulo-payments/digest/settingsAdmin: weekly report recipient, last/next send/hulo-payments/digest/send-testAdmin: email this week's report to you now/hulo-payments/setupAdmin: set-up checklist (what is still to do)/hulo-payments/widgetAdmin: headline figures for the dashboard widgetFAQ
Common questions.
How do I get a licence key?
Buy one on the web with Stripe Checkout: monthly licence for Payments, annual licence for Payments (two months free) or lifetime licence for Payments. You'll receive the JWT key by email. Paste it into the plugin's admin settings (Activate) — no redeploy — or set it as HULO_LICENCE_KEY_PAYMENTS in your .env if you prefer config-as-code; the env key wins when both are present.
Does it work without a key?
Yes. Every install runs with all premium features on for its first 14 days — no card, no licence key, nothing to configure — so you can judge it on your real traffic. After that it keeps working in the free tier. To keep them, click Subscribe on the plugin's admin page: the first charge is taken when the 14 days end (or 49 hours after checkout, if that is later), you can cancel any time before then, and the licence installs itself.
Which databases are supported?
MySQL, MariaDB and PostgreSQL (verified against PostgreSQL 17). The plugin follows your Vendure dbConnectionOptions automatically — there is nothing to configure.
How do updates work?
The plugin checks the npm registry daily. When a newer version exists, the admin dashboard shows an update banner with a What's-new link to the changelog and an "Update now" button that installs the registry-verified release via your own package manager and gracefully restarts under your process supervisor. Prefer manual control? Copy the install command instead, or set HULO_SELF_UPDATE=off.
Where is data stored?
In your Vendure database: the plugin keeps its data in its own tables there, created on boot. Hulo Global never receives your customer data: the plugin sends our licence server only the licence check-ins and usage counts described under “Do the plugins call home?”. Payments are sent from your server to the providers you connect (Stripe, Adyen, PayPal and the others), as with any payment plugin.
Will it survive a Vendure upgrade?
It supports Vendure >=3.5.0 <4.0.0 (its peer dependency), and current releases are built and tested against Vendure 3.8.2 before they are published. A boot-time compatibility check emits a non-fatal warning if @vendure/core is outside that range, so upgrades to a future 3.x are safe to try. The 4.0 line will be tested and re-declared once its changelog lands.
Changelog
What's new.
Latest release: v0.5.0, 16 November 2026. Full changelog for Payments for Vendure
v0.5.0NewLatest
Improvement round. Payment behaviour is unchanged; ops alerts look different and operators outside the default channel see less.
Changed
- Ops alert e-mails (disputes opened and closed, a provider confirming a different amount, a renewal that failed or ended the subscription, a subscription that could not be created) now use the shared e-mail design: a compact 600px card with the channel's logo or brand name over an accent bar, an info box with the order, provider, amount and references (references in a monospace font), a warning box where something needs doing, an Open Payments in Admin button and a sign-off. Every alert has an HTML and a plain-text part (before, text only). Amounts are formatted in the order's currency instead of raw minor units.
- Branding comes from the channel's hosted-page settings (brand name, accent colour when changed, logo). New optional
emailplugin option as the fallback for every channel:accentColor(default#155dfc),logoUrl,storeName,supportEmail,footerText. renderEmail()is exported for hosts that want their own payment e-mails in the same design.- Dev dependencies:
@nestjs/schedule^12.0.4,mysql2^3.24.6.
Fixed
- Channel scoping of subscriptions. An administrator working in a non-default channel could list every channel's subscriptions (with customer e-mail addresses) and cancel, pause or resume them. The list is now limited to the operator's channel, and the actions answer 403 for another channel's subscription (404 for an unknown id). The dashboard's subscription figures and configured providers follow the dashboard's channel.
- The webhook event log (
GET /hulo-payments/events) has no channel, so it is now shown only in the default channel; other channels get an empty list. - The Providers tab listed every channel's payment methods and channels to operators of a single channel; it now lists their channel's only.
- A provider pay link asked for a disabled payment method by code was issued anyway; it is now refused (
no-provider, "payment method … is disabled"). - An unknown or mistyped hosted-page link (404) now carries the same no-store, no-framing security headers as every other hosted-page response.
v0.4.0New
Parity with HULO Payments for WordPress. Existing payment behaviour is unchanged by default: Stripe sessions, captures, refunds made from Vendure and webhooks work exactly as in 0.3.8.
Changed (tiers)
- Pay links are free. The admin's Pay by link tab and
POST /hulo-payments/pay-linkno longer need a licence. Provider links for the licensed providers (Adyen, PayPal, Mollie, Square, Checkout.com, Coinbase Commerce) still do, as those providers do everywhere; Stripe links and hosted-page links are free. - The weekly report and the set-up checklist are licensed (licence or evaluation). On the free tier the scheduler sends nothing, Send me a test answers 402 and
GET /hulo-payments/setupreturns no items (premium: false). The report's settings and history are kept; it resumes when a licence is activated. PREMIUM_FEATURES(admin banners, weekly report) now lists what a licence really adds: the eight other providers, subscriptions, saved cards, surcharges, fallback after a decline, and the weekly report and checklist. The hosted checkout page and provider routing were listed as licensed but have always been free.
Added
- Fallback after a decline (licensed; fixes B9). The per-channel Fall back to the next provider on decline setting was saved and shown but never read. Now, with a licence and the switch on, a failed payment or session on the hosted page answers with
fallback(the other methods, next in the routing order first) and the page moves the failed method to the end and highlights the next one. Storefronts with their own checkout get the same order fromhuloPaymentProviders(failedMethodCode: "…")(new optional argument). Nothing is charged automatically. Unlicensed, or with the switch off, nothing changes. - Hosted-page pay links (free). A pay link can now be this shop's own hosted payment page for the order (
mode: 'hosted', the default when nomethodCodeis given), offering every method enabled on the order's channel, bank transfer and pay later included, for 1 hour to 30 days. Paying it records the payment exactly like a checkout and turns the link's ledger row took.GET /hulo-payments/pay-links?orderCode=lists an order's links. PayLinkService(aliasHuloPayLinkService) — a stable, exported service API for pay links (createPayLink(ctx, { orderCode, amount?, currency, description, customerEmail?, returnUrl?, expiresInHours?, reference?, metadata? }) → { url, ref }, pluscreate(ctx, input),listForOrder(orderCode)andPayLinkErrorcodes) so other plugins (HULO Quotations) can issue "Pay now", deposit and balance links. Documented in the README.- Part payments by link (free). A pay link with an
amountbelow what is left to pay is a Stripe link for that amount; paying it adds a partial payment, and the order reaches PaymentSettled only once its settled payments cover the total (deposit, then balance). Stripe accepts an intent below the order total only when the plugin stamped ithuloPartialserver-side; every other payment still has to match the total exactly. A link can never be for more than is left to pay. - Dashboard-refund reconciliation (free, per channel, off by default). With Settings → Routing → Record refunds made in the provider's dashboard on, a refund made in Stripe's (or another provider's) own dashboard becomes a Settled Vendure refund on the order's payment, keyed by the provider's refund id, with an order-history note and one ledger row. A second event for the same refund (Stripe sends
charge.refundedandrefund.updated) changes nothing; Stripe events that name no refund (API versions from 2022-11-15) read the payment's refunds back; Mollie's running total is reconciled against the refunds Vendure already has. Never more than is left to refund. Refunds made from the order page are recognised (their ledger row, or a refund still in flight, in which case the event is answered 500 and redelivered) and are never counted twice. Payments made by another integration on the same provider account are not touched. - Per-IP rate limits on the public routes: hosted page
GET120/min, its/sessionand/completecalls 40/min, provider webhooks 1200/min, CSP reports 60/min;429withRetry-Afterover the limit. Configurable with the newrateLimitsoption (falseturns them off). Behind a reverse proxy on a private address the client IP is taken fromCF-Connecting-IP/X-Forwarded-For/X-Real-IP. - Stripe:
listRefundson the provider contract (GET /v1/refunds?payment_intent=);refundedTotalon normalised refund events (Stripecharge.refunded, Mollie).
Fixed
- Saving settings through
POST /hulo-payments/settingskeeps the stored value of any field the request leaves out (it used to reset it).
Docs
- README: pay links and the service API, fallback, refund reconciliation, rate limits, tiers table (no card is needed for the evaluation), the full webhook path (
<publicBaseUrl>/hulo-payments/webhook/hulo-stripe) and which providers report disputes (Stripe, Adyen, PayPal, Mollie, Square, Checkout.com, GoCardless).
Upgrade notes
- New columns are added on boot:
hulo_payment_settings.reconcileRefunds(default 0) andhulo_hosted_session.payLink(default 0). No data changes. POST /hulo-payments/pay-linkwithoutmodeand withoutmethodCodenow makes a hosted-page link (it used to pick the first provider that supports links). Passmode: 'provider'for the old behaviour.
v0.3.8NewSecurity
Fixed
- Hosted payment page charges the recalculated total on Vendure 3.8+. Vendure 3.8 recalculates prices, promotions and shipping when an order moves to
ArrangingPayment. The hosted page moved the order there and then created the provider session (Stripe PaymentIntent etc.) from the order it had loaded before the transition, so a price or promotion change since the cart was built could open a session for the old total. The order is now reloaded after the transition. No change on Vendure 3.5 to 3.7.
- Security Admin REST routes refuse a Shop-API session on Vendure 3.8+. Vendure 3.8 binds every session to the API it was created on and refuses Shop-API sessions on the Admin API (GHSA-5fpx-9m35-w745), but it does not check REST routes added by plugins: an administrator's storefront session still carried their admin permissions into the HULO Payments admin REST routes (providers, payment methods, ledger, licence). Those routes now also require a session created on the Admin API (
isAdminApiSessionfrom the licence SDK 0.15.6, the same rule as Vendure's own AuthGuard). The admin UI is unaffected; administrators logged in before the 3.8 upgrade log in again once, as Vendure already requires. No change on Vendure 3.5 to 3.7.
Compatibility
- Tested with Vendure 3.8.2 (NestJS 12,
@nestjs/graphql14, Apollo Server 5), as well as 3.5 to 3.7. The peer range stays@vendure/core >=3.5.0 <4.0.0; nothing here needs 3.8. - Requires
@huloglobal/vendure-licence-sdk^0.15.6.
v0.3.7New
Fixed
- Ops e-mails and the weekly report failed when the mail server was slow to greet. The plugin's SMTP transport allowed 5 seconds to connect and 5 seconds for the server's greeting. A mail server may hold its greeting while it checks the sending host's reverse DNS (Gmail has taken just over 5 seconds), so the weekly report and ops e-mails (disputes, failed renewals) failed with "Greeting never received". Connecting and the greeting now get 30 seconds each, and a whole send may take 60 seconds instead of 12. The socket idle timeout is 45 seconds instead of 10. It also runs while the server has not greeted yet, so it is longer than the greeting timeout, and a server that never greets is still reported as "Greeting never received" rather than a bare "Timeout". The ops webhook was not affected.
- A failed-renewal webhook no longer waits for the ops e-mail. When Stripe, PayPal or Mollie reported a failed renewal (
subscription.payment_failed), the plugin answered the provider only after the ops alert (webhook and e-mail) had gone out, so a slow or unreachable mail server could hold the reply past the provider's timeout. The provider then showed a failed delivery and sent the event again (it was not applied twice). The alert is now sent in the background, as dispute and amount-mismatch alerts already were. The subscription is still marked past due and the failure recorded before the reply.
v0.3.6New
Package metadata
- The
licensefield is nowAGPL-3.0-only, matchingLICENSE, which grants the GNU Affero General Public License version 3 (it saidAGPL-3.0-or-later). Published npm builds remain under the separate commercial licence described inLICENSE. No code changes.
v0.3.5New
Fixed
- PostgreSQL: a renewal is charged once. With licence SDK 0.15.3 or older, the claims that stop double processing always looked successful on Postgres. The hourly renewal job and an admin "run now" could both charge the same subscription renewal, and two overlapping completions of one hosted checkout link could both run. The plugin now requires licence SDK
^0.15.4, and each goes through once. The first weekly report is no longer skipped either (it used to start a week late). MySQL and MariaDB were not affected. - PostgreSQL: a licence key activated in the admin is now stored. The plugin's licence store left out the conflict column that the Postgres upsert needs, so saving a key failed. Pasting a key into the admin applied it, answered with a server error and did not store it, so the plugin was unlicensed again after a restart. A key bought from the admin, which installs itself, was not stored either. MySQL and MariaDB were not affected.
Package metadata
- A shorter
descriptionthat npm shows in full (npm cuts descriptions at 255 characters).
v0.3.4New
Documentation
- The README now shows the plugin logo, hosted on huloglobal.com so it displays on npm and GitHub alike, linking to the product page. No code changes.
v0.3.3NewSecurity
- Security Provider confirmations are bound to the exact order, amount and currency. A client-supplied provider reference could mark a different (or larger) order paid:
- Adyen: a completed Drop-in session of any order was accepted for any other order. The session's
referencemust now be the order code, and when Adyen reports the session's payments the authorised amount and currency must match the order. - GoCardless: the billing request's order reference was optional and its amount/currency unchecked (a pending request for a smaller basket authorised the new total). Both are now required to match.
- Coinbase Commerce: the charge's price was never compared with the order and its order reference was optional; a completed charge for a smaller basket settled the order at its full total. Both now must match.
- Square: a payment looked up by
paymentIdwas accepted for any order. Itsreference_idand currency must now match. - PayPal, Mollie, Braintree, Checkout.com, Stripe: the order reference check was skipped when the provider object had none (PayPal orders can be created in the browser with the public client id; Mollie payment-link payments carry no metadata). The reference is now mandatory (Mollie: metadata or the
Order <code>description), PayPal orders must have exactly one purchase unit, Braintree and Checkout.com currencies are checked.
- Adyen: a completed Drop-in session of any order was accepted for any other order. The session's
- Security Webhook confirmations must cover the payment. A
payment.authorized/payment.settledevent whose amount or currency differs from the Authorized Vendure payment no longer settles it; afailureledger row and an ops notification (payments.amount_mismatch) are written instead. An Adyen session payment, recorded at the order total before its AUTHORISATION arrives, is only settled by an AUTHORISATION for that amount. - Security Surcharges follow the method actually charged. The payment handler refuses a payment whose
hulo-surcharge:line is not exactly the fee configured for the payment method being charged (no fee, another method's fee, or a fee computed on an older basket).huloCreatePaymentSessionand the hosted checkout page now apply the chosen method's fee before creating the provider session, so the session amount includes it; storefronts that add a payment without a session must callhuloApplyPaymentSurchargewith the method they pay with. Webhook-recorded pay-by-link payments are not re-checked.
v0.3.2New
Changed
- Every install now gets a 14-day evaluation with all features on and no card (granted by the HULO licence server). The licence banner's buttons read Subscribe: during the evaluation the first charge falls on the day it ends, so there is no second free trial.
v0.3.1
Fixed
- Admin UI build error (TS2352) in the payment-method detail panel's handler-args reader under the Angular production compiler.
v0.3.0
Added
- Weekly report. Monday 08:00 server-local, from the ledger: payments settled and value, refunds, disputes opened, active subscriptions and MRR, pay-by-link takings and failed renewals recovered, each against the previous week, with next steps from the set-up checklist. Settings → Weekly report card (on/off, recipient with the default shown, last / next send, Send me a test, Preview). Endpoints
GET/POST /hulo-payments/digest/settings,POST …/digest/send-test,GET …/digest/preview. Uses the ops SMTP transport; nothing is sent withoutSMTP_*. Worker-only, once per install across replicas, off withdisableScheduler. - Set-up checklist at the top of the Payments overview (
GET /hulo-payments/setup): provider connected, method enabled on a channel,hostedReturnHostsset, ops email, webhook secret for every connected provider, first payment taken. Replaces the "Three steps" card. "Hide" is remembered in the browser and the card returns if a done item comes undone. - Dashboard widget (Dashboard → Add widget → Payments): 7-day takings, settled payments and disputes, the licence notice, and a link to the page (
GET /hulo-payments/widget). - Usage stats (last 30 days, numbers only) sent with the evaluation ping and, after purchase, the daily heartbeat:
paymentsSettled,volumePence,refundedPence,disputesOpened,subscriptionsActive,mrrPence,payLinkPaidPence,renewalsRecovered. - Renewals recovered tile on the overview (renewals that succeeded after a failed attempt, from the ledger), also in
GET /dashboardasrenewalsRecovered. - Licence banners: lifecycle notice (trial ending, key expiring, evaluation ended) in an amber strip, the premium feature list and "So far: …" figures on the trial and free banners, and the trial banner's Email me before it ends reminder (the existing
eval/remind-meroute, which now also remembers the address as the weekly report's last-resort recipient).GET /metagainsnotice,premiumFeaturesandrecentStats.
Changed
@huloglobal/vendure-licence-sdk^0.15.1; the heartbeat reports the jti of the key currently in force (env key, admin activation or buy-from-admin claim), not only the boot-time one.- 402 responses carry
buyUrl: https://elite.charity/licence/buy/vendure-plugin-payments; the admin UI turns any 402 (orlicence-requiredbody) into "<action> needs a licence — start the free trial or activate a key at the top of this page." - Ops e-mail accepts
SMTP_HOSTas an alias ofSMTP_SERVERand works withoutSMTP_USER(unauthenticated relays).
Fixed
- Ops alerts (disputes, failed renewals) now honour the per-channel Settings → Operations → Ops email, falling back to the
ops.emailplugin option; the channel setting was saved but never used.
v0.2.10
Fixed
- Settings → Payment methods: the description line under a HULO method decodes HTML entities (
&,', …) that Vendure's rich-text editor stores, so "Card & Apple Pay" no longer shows asCard & Apple Pay.
v0.2.9
Follow-up to the 0.2.8 audit — no new features. One column type change on hulo_hosted_session is applied on boot; nothing else to migrate.
Added
- Content-Security-Policy on the hosted page. A per-request nonce on the page's inline script and a policy listing every provider client host (Stripe, Adyen via jsDelivr, PayPal, Square, Braintree) for
script-src,frame-srcandconnect-src, withimg-src * data:,style-src 'self' 'unsafe-inline',frame-ancestors 'none',base-uri 'none',form-action 'self'. New plugin optionhostedCsp: 'enforce' | 'report-only' | 'off'(default'report-only': the policy is sent asContent-Security-Policy-Report-Onlyand violations posted to the newPOST /hulo-payments/csp-reportroute are logged, rate-limited, tokens masked). The Stripe hosted flow was verified under'enforce'in a real browser (Payment Element mounted, session created, zero violations). - Postgres corpus test (
src/pg-corpus.test.ts, runs whenHULO_PG_URLis set): every SQL statement insrc/**is translated by the licence-sdk adapter and prepared against a scratch PostgreSQL 17 with quoted-camelCase stand-ins for the Vendure tables the plugin reads. 66 statements pass.
Changed
- Unit test files are no longer compiled into
dist(they were published with the package before).
Fixed
- Adyen pay-by-link never recorded a payment.
confirmPaymentinsisted on a Drop-insessionId+sessionResult, which a payment link does not have. The AUTHORISATION / CAPTURE notification now confirms the payment (Authorized or Settled per the event,transactionId= pspReference, amount and currency checked against the order). The facts are registered by the webhook path and consumed once by the handler, so a storefront cannot forge apspReferencethroughaddPaymentToOrder. - Adyen manual capture from the order page could not re-check the session:
sessionResultis now kept in the payment metadata. - Webhook settle mark (
markSettledByWebhook) is a map with a 60 s TTL and is cleared in afinallyaroundsettlePayment, so a failed settle can no longer leave a stale "trust me" entry for that payment. - Renewals counted twice in the ledger. Stripe renewal intents are stamped
huloRenewaland theirpayment_intent.*events ignored; Adyen notifications whose merchant reference is a scheduler reference (<order>-R<yyyymmdd>-<variant>-a<n>) are ignored. The scheduler'srenewalrow is the only one. - Refund webhooks settled the wrong refund.
refund.settlednow targets the Vendure refund by the provider's refund id (Stripere_…fromcharge.refunded's refund list or the newrefund.updated/charge.refund.updatedhandling, Adyen's REFUND pspReference), then by exact amount, then the only pending one — never "the first pending refund" when several are open. A refund already settled from the handler is not written to the ledger a second time. - Adyen sessions now include a "Shipping & fees" line for
amount − Σ lines(Klarna / Afterpay reject sessions whose lines do not sum to the amount). - Hosted page GET froze carts. Opening the link moved the order to
ArrangingPayment, so link previews and crawlers locked baskets. The GET is read-only (anAddingItemsorder still lists its providers); the transition happens inPOST …/session, before the provider session is created. - Mollie
cancelSubscriptionuses the stored customer reference instead of listing up to 250 subscriptions to find it; the provider contract gained an optionalproviderCustomerRefargument. - UUID id strategy.
hulo_hosted_session.orderIdwasINT; it is nowVARCHAR(36)(widened on boot with a guardedALTER, MariaDB/MySQL and Postgres) and compared as text.
v0.2.8Security
Reliability and security pass — no new features. Two columns on hulo_hosted_session, a unique key on hulo_subscription, one index on hulo_payment_txn and a best-effort index on Vendure's payment table are added on boot; nothing to migrate.
- Security Hosted checkout page. Values embedded in the page script are serialised so they can never close the script block;
returnUrlandcancelUrlmust be absolute http(s) URLs (optionally restricted with the newhostedReturnHostsoption);methodCodeandlocaleare validated; client metadata is allow-listed and server-side session ids win; provider and Vendure error text no longer reaches the customer; clickjacking and referrer headers are set; each link allows at most 30 provider sessions; expiry is stored as a date (no UTC/local drift); expired rows are purged. - Security Permissions and scoping. Self-update and licence activate/deactivate need SuperAdmin; admins in a non-default channel only see and act on that channel's ledger, settings, methods and connections; settings, pay-link return URLs, days and e-mails are validated; short secrets are fully redacted; the licence lead request times out after 8 s.
Fixed
- Webhook-created payments. Payments recorded from a webhook (pay-by-link completion, a redirect-flow
payment.settledarriving before the customer returns) calledaddPaymentToOrderoutside a transaction, which Vendure 3.7 rejects; the event was then marked processed and lost. Every webhook is now applied inside one transaction with the order row locked, in the order's own channel with that channel's method code. - Duplicate payments. A webhook racing the customer's own completion (or Stripe's
checkout.session.completed+payment_intent.succeededpair) can no longer record two payments: both paths lock the order and skip a reference that is already on a live payment. The hosted/completeroute also holds a one-minute lease on the session row so a double submit is answered from the order's state. - Payment matching ignores Declined/Cancelled/Error payments, so an Adyen decline-then-retry settles the retry instead of the failure.
- Webhook redelivery. A processing error now releases the idempotency claim and answers 5xx, so the provider redelivers instead of the paid event being lost.
- Subscription double charge. Due renewals are claimed with a conditional
UPDATEbefore the provider is called (the hourly cron and the admin "run now" run in different processes); the charge reference includes the attempt number so a retry never replays a cached refusal. Subscription rows are claimed with a pending row + unique key before the provider subscription is created (the bus fires for PaymentAuthorized and PaymentSettled seconds apart). Monthly and yearly periods are calendar arithmetic instead of 30/365 days. The plugin registersScheduleModuleitself, so renewals run on hosts that never wired it;disableScheduleris honoured. - Postgres. Raw queries on Vendure tables quote their camelCase columns (
channelId,paymentMethodId,transactionId,orderId); the subscription updater no longer quotes the plugin's own columns; the channel lookup goes through the dialect adapter. Payment methods were silently absent on Postgres before. - Handler args. Numeric strings with leading zeros (UK account numbers, sort codes) stay strings instead of being converted to numbers.
- Stripe pay-by-link uses one line for the order total so the intent equals
order.totalWithTaxand the webhook accepts it; GoCardless refunds send the requiredtotal_amount_confirmation; refund idempotency keys are per minute, not per second. - Ops alerts never hold a webhook response (dispute alerts are fire-and-forget), use one pooled SMTP transport with timeouts and log non-2xx replies.
ALTER TABLE … IF NOT EXISTSis replaced by an information-schema check (MySQL 8 boots again).
Changed
- Admin UI: OnPush change detection,
trackByon every table, daily bars computed once per load, tab switches keep loaded data (Refresh reloads), every provider named in Transactions/Subscriptions/Routing and available in the Surcharges table, the providers cache expires after 60 s and is cleared after Connect, the pay-by-link capability chip reads the right key, the method panel shows the method being edited, and the action-bar button needs only ReadOrder. hulo_payment_eventrows older than 180 days and expired hosted sessions older than 7 days are purged.
v0.2.7
Fixed
- Payments → Payment methods tab: every channel cell stacks its status chip and buttons left-aligned with the same widths, columns are fixed-width and rows vertically centred, so nothing drifts out of line on multi-channel installs.
v0.2.6
Fixed
- Settings → Payment methods: the status chips sit in their own fixed column (mark · status · name), so they line up down the page whatever the method name length; the Payment methods tab's status chips and buttons share fixed widths for the same reason.
v0.2.5
Fixed
- Sharing a Stripe account with Vendure's own Stripe plugin no longer produces webhook errors. Events for PaymentIntents the plugin did not create (they lack its
vendureOrderIdstamp) are acknowledged and ignored instead of being applied to the order; the plugin never adds a payment to an order that already carries another method's payment. - A configured but disabled method still answers its webhook endpoint with 200 after verifying the signature, so the provider does not mark the endpoint as failing while the method is switched off.
- Enabling, disabling or editing a payment method in Settings takes effect immediately (the plugin's method cache is cleared on the Vendure event) instead of after up to 30 seconds.
v0.2.4
Added
- Payment methods tab on the Payments page: every provider for every channel in one table, one status word per cell (Not added / Not set up / Ready, disabled / Test mode / Live). Add creates the payment method on that channel — disabled, no keys, with a descriptive name such as "Adyen · cards, wallets & 100+ local methods" — so it is visible under Settings → Payment methods straight away; Connect opens the Connect panel for that channel. "Add every missing method" fills the whole table in one click. The button on Settings → Payment methods now opens this tab.
POST /hulo-payments/methods { provider, channelId }behind it (admin, CreatePaymentMethod), idempotent per provider and channel.
v0.2.3
Added
huloHostedCheckout(methodCode): the storefront can preselect one of the enabled methods, so a "Pay with PayPal" button opens the hosted page straight on PayPal. Without it the page opens on the first method in the channel's order, as before.
v0.2.2
Changed
- Settings → Payment methods reads at a glance. The Name column of the list now shows, for every HULO method, a brand mark, the name, one status word (Live / Test mode / Ready, disabled / Not set up) and the first line of the description — so twenty methods scan in seconds without opening each one. Other plugins' methods are untouched.
- Providers tab regrouped. Providers are listed under four plain headings — Cards & wallets; PayPal, bank & local methods; Crypto; Offline & on account — as compact rows (mark, name, what customers can pay with, one status word). A row expands to the details, dashboard links, its payment methods and the Connect panel; nothing else is on screen until you ask for it.
v0.2.1
Added
- Settings → Payment methods explains itself. Any payment method that uses a HULO handler now shows a panel under the form: what the provider is, what customers can pay with, what the method supports (holds, refunds, subscriptions, saved cards, pay-by-link), where the keys come from with links to the provider dashboard, a Test these keys button that checks the unsaved form values, the webhook URL with a copy button and a saved/not-saved status, and the go-live checklist. Offline methods (bank transfer, pay later) get a plain-language "how it works" instead of keys and webhooks.
- Connect a payment provider button on the payment-methods list, opening the Payments page on the Providers tab. The Payments page accepts
?tab=and?connect=<provider>deep links.
v0.2.0
Added
- Hosted checkout page.
huloHostedCheckout(returnUrl)returns a URL the storefront redirects to; the page shows every enabled method in the channel's preferred order, drives each provider's own client (Stripe Payment Element, Adyen Drop-in, PayPal buttons, Square Web Payments, Braintree Drop-in, hosted redirects, bank-transfer instructions), records the payment and sends the customer back with?order=&result=. No provider code in the storefront. Branding (name, colour, logo) per channel in Settings. - Seven more payment systems, all behind the same contract: Square (cards, Apple Pay, Google Pay, Cash App Pay, Afterpay; holds, refunds, payment links, signed webhooks), Braintree (cards, PayPal, Venmo, wallets; holds, refunds), GoCardless (Bacs, SEPA, ACH direct debit, Instant Bank Pay; native subscriptions), Checkout.com (hosted payments page; holds, refunds, disputes, payment links, workflow webhooks), Coinbase Commerce (crypto), bank transfer and pay-later / invoice (offline methods settled from the order page, free tier).
- Get-started wizard on the Payments page until the first provider is connected; Connect works for every provider, including automatic webhook setup for Square and Checkout.com.
v0.1.0
Added
- Four providers, one contract. Stripe (Payment Intents + Payment Element), Adyen (Sessions + Drop-in), PayPal (Orders v2) and Mollie (Payments API) as Vendure payment method handlers with server-side verification of amount, currency and order code.
- Capture control and refunds. Automatic or manual capture per method, partial capture, cancel, full and partial refunds through Vendure's refund flow.
- Signed, idempotent webhooks per provider at
/hulo-payments/webhook/<provider>, updating payments, refunds and subscriptions; disputes recorded and alerted. - Saved cards (Stripe Customers, Adyen stored methods) with shop-API listing and removal.
- Subscriptions from product-variant custom fields: native billing on Stripe, PayPal and Mollie, scheduler-billed renewals for Adyen, dunning, MRR, customer self-service.
- Pay by link for any unpaid order from the admin (Stripe Checkout, Adyen Pay by Link, PayPal approve links, Mollie Payment Links).
- Routing and rules. Provider order per channel with fallback, the
hulo-payment-ruleseligibility checker, optional surcharges. - One-step Connect on every provider card: verifies the keys with the provider, creates the webhook through the provider's API (Stripe, PayPal, Adyen Management API) and stores its secret, then creates the Vendure payment method — with links straight into each provider's dashboard, API keys and webhook pages.
- Ledger and dashboard under Sales → Payments: volume by provider and day, success rate, refunds, disputes, subscriptions, webhook log, settings, licence card.
Ready to ship?
Install in five minutes, run the trial on real traffic, keep it if it earns its place.