HULO Payments

Description

HULO Payments takes payments through your own Stripe account on any WordPress site. Put a payment form on a page or send someone a pay link; the payer pays on a hosted payment page, and every payment lands in one payments list and ledger, with refunds, manual capture and disputes.

Taking payments

  • Payment forms: the “HULO payment form” block or the [hulo_payment_form amount="12.50" currency="GBP" description="Workshop ticket"] shortcode, for a fixed amount or one the payer chooses (allow_custom_amount="1", up to a maximum you set). The payer enters their name and e-mail and continues to the hosted payment page. The form itself needs no JavaScript, and a fixed amount cannot be changed in the browser. If a payment cannot be started (for example an amount above your maximum), the payer is sent back to the form with the reason shown above it.
  • Pay links: create a payment for any amount under HULO Payments Pay links, copy its link and send it to the payer. Pay links stay open for 30 days.
  • Hosted payment page with Stripe’s Payment Element: cards, Apple Pay, Google Pay, Link, Klarna and the other methods you switch on in your Stripe dashboard, with 3-D Secure handled by Stripe. Apple Pay shows only once your site’s domain is added in the Stripe dashboard (Settings Payment method domains), as Stripe requires. The page is never indexed or framed and sends a Content-Security-Policy with a per-request nonce (report-only to start with; switch it to enforce under Settings).

Built to be safe

  • Server-side verification: the browser never decides that a payment is paid. The plugin reads the payment back from Stripe and checks that it belongs to that payment and matches its amount and currency.
  • Signed, idempotent webhooks: Stripe’s signature is checked on the raw body with a 5-minute tolerance, each event is applied once, and an event that fails is released so Stripe sends it again. “Register webhook” creates the endpoint in your Stripe account and saves its signing secret.
  • Card details are typed into Stripe’s own fields and never reach your server.
  • The public endpoints (payment forms, the hosted page, webhooks) are rate-limited per visitor. Behind a proxy or CDN, list its addresses under Settings so the real visitor address is used.

Managing payments

  • Payments: every payment in one list, with status and source filters, search, and a page for each payment.
  • Refunds, full or partial, from the payment’s page. Refunds made in the Stripe dashboard are added to the payment once each. Releasing an authorisation, or the part of one that was not captured, is never counted as a refund.
  • Authorise only (manual capture): reserve the money, then capture or release it from the payment’s page (the PHP API can also capture part of it).
  • Disputes are recorded in the ledger and e-mailed to the ops address you set.
  • Overview: money taken, payments settled, refunds, disputes, success rate and money paid by link for the last 7 and 30 days, with each currency shown on its own. The Transactions tab is the full ledger and the Webhooks tab logs every delivery.
  • Rules: offer a payment method only for an amount band or certain currencies.

For developers

  • A PHP API for other plugins: create, find, capture, release and refund payments, a filter before every charge and actions on every status change. See README.md in the plugin folder.

With WooCommerce (optional)

  • Stripe becomes a payment method for the classic checkout, the Checkout block and the pay-for-order page (HPOS compatible), and order payments join the same payments list.
  • Pay later by invoice for orders, on the payment terms you set.
  • The rules also cover the store’s other payment methods, and at the checkout they can check the customer’s country, user role and whether they are signed in.
  • Each order follows its payment: status, notes and refunds, with capture and release in the order actions and full or partial refunds from the order’s refund button. Refunds made in the Stripe dashboard are added to the order too.
  • The store currency is the default for payment forms and pay links, in place of the Currency setting.

HULO Payments Pro

Everything above is free, with no limits. HULO Payments Pro is a separate add-on from huloglobal.com that adds Adyen, PayPal, Mollie, Square, Braintree, GoCardless, Checkout.com and Coinbase Commerce (for payment forms, pay links and the checkout), provider-hosted payment links, fallback to another method after a decline, payment surcharges, a weekly e-mail report and, with WooCommerce, saved cards.

External services

This plugin connects to Stripe (Stripe, Inc. and its affiliates, for example Stripe Payments Europe, Ltd.) to take payments. It sends nothing to Stripe until you enter your Stripe API keys under HULO Payments Payment methods, and it only ever uses your own Stripe account.

What your server sends to the Stripe API (api.stripe.com), and when:

  • When a payer opens a payment on the hosted payment page: the amount, currency and capture mode, the payment’s description, its number and reference (or, for an order, the order number), your site’s host name, the statement descriptor suffix if you set one, and the payer’s e-mail address (for Stripe’s receipt). This creates a Stripe PaymentIntent.
  • When the payment is completed, or the payer comes back to the page: the PaymentIntent id, to read the payment’s status, amount and card result back from Stripe.
  • When you capture, release or refund a payment: the PaymentIntent id and the amount, and for a refund the reason you typed.
  • When Stripe reports a refund this site did not make (for example one made in your Stripe dashboard) without naming it: the PaymentIntent id, to read that payment’s refunds back.
  • When you click “Test keys”: a request for your Stripe account’s name. When you click “Register webhook”: a request for your webhook endpoints, then this site’s webhook address (/wp-json/hulo-payments/v1/webhook/stripe) and the list of events Stripe should send to it. An endpoint this plugin registered before, whose signing secret is saved, keeps that secret and gets the events it is missing (and is switched back on if Stripe disabled it). Any other endpoint for the same address (one you added by hand, or one whose secret was not saved) is deleted and replaced with a new one, because Stripe shows an endpoint’s signing secret only when it is created.
  • Other HULO plugins you install (for example HULO Checkout Guard or HULO Fraud Prevention) can make their own Stripe API calls through HULO Payments with your keys; their readmes describe those calls.

In the payer’s browser, the hosted payment page loads Stripe.js from js.stripe.com. It shows Stripe’s payment fields, in frames from Stripe’s own domains (js.stripe.com and its subdomains, hooks.stripe.com for 3-D Secure, and link.com when the payer uses Link), and sends the card or wallet details straight to Stripe.

Stripe sends signed webhook events (payments, refunds, disputes) to this site’s /wp-json/hulo-payments/v1/webhook/stripe address.

Stripe Services Agreement: https://stripe.com/legal/ssa — Stripe Privacy Policy: https://stripe.com/privacy

Payment forms, pay links, the rules, the ledger and pay later by invoice use no external service. The plugin makes no other external requests: no tracking, no licence checks and no remote updates.

Screenshots

Blocks

This plugin provides 1 block.

  • HULO payment form A payment form: the payer enters their name and e-mail address, and an amount if you let them choose it, then pays on the hosted payment page.

Installation

  1. Install HULO Payments from Plugins Add New (or upload the zip) and activate it.
  2. Go to HULO Payments Payment methods and click “Set up” next to Stripe. Paste your publishable and secret keys (start with your test keys, pk_test_… and sk_test_…), tick “Enable” and save.
  3. Click “Test keys”, then “Register webhook”. Stripe can only send webhooks to a site it can reach on the internet.
  4. For Apple Pay, add your site’s domain in the Stripe dashboard under Settings Payment method domains (Stripe requires it for Apple Pay and recommends it for Google Pay, Link and Klarna).
  5. Add the “HULO payment form” block to a page, or create a pay link, and pay with Stripe’s test card 4242 4242 4242 4242.
  6. Under Settings, set an ops e-mail address for disputes and, if there is a Currency setting, your default currency. When everything works, swap in your live keys.

FAQ

Do I need WooCommerce?

No. Payment forms, pay links, the hosted payment page, refunds, webhooks and the ledger all work on a plain WordPress site. If your site runs it, HULO Payments can also take the payments at its checkout.

Which Stripe account is used? Does HULO take a fee?

Your own: payments go straight to your Stripe account and only Stripe’s own fees apply. The plugin adds no fee.

Do card details touch my server?

No. The Stripe Payment Element runs in Stripe’s own frames on the hosted payment page. Your server only receives what Stripe reports about the payment (for example the card brand and last four digits), never the card number.

Can I try it without taking real money?

Yes. Use your Stripe test keys: the Payment methods tab shows “Test mode”, and Stripe’s test cards work on the hosted payment page.

Which currency does a payment form use?

The one in the shortcode or block, otherwise your default currency: the Currency setting under Settings or, where Settings has none, the store currency. The Overview shows the money taken in each currency separately.

Why doesn’t Apple Pay show on the payment page?

Stripe shows Apple Pay only on domains registered with your Stripe account. In the Stripe dashboard, open Settings Payment method domains and add your site’s domain. Apple Pay also needs a device and browser that support it, with a card in Apple Wallet. Google Pay, Link and Klarna appear when they are switched on in your Stripe dashboard and the payer’s browser supports them.

What happens if a webhook arrives twice?

The event id is claimed in the webhook log before anything is applied, so the second delivery is acknowledged and skipped.

What does the plugin store about payers?

With each payment, on your own site: the payer’s name and e-mail address, what they paid for, the amount, the Stripe references, what Stripe reports about the card (brand, last four digits, country, checks and risk level, never the card number) and, for payment forms and orders, the payer’s IP address. Nothing is sent anywhere except to Stripe, as described under “External services”.

What does “Delete data on uninstall” remove?

Payments, the ledger, the webhook log, hosted payment sessions and the plugin’s settings. Store orders, with their transaction ids and refunds, are never removed. The box is unticked by default, so deleting the plugin keeps your payment records.

Reviews

There are no reviews for this plugin.

Contributors & Developers

“HULO Payments” is open source software. The following people have contributed to this plugin.

Contributors

Translate “HULO Payments” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

0.1.3

  • The Stripe provider class is now StripeGateway (the plugin bundles no third-party library; the old class name stays available to add-ons).

0.1.2

  • The Overview no longer shows a box about the Pro add-on, and the Payment methods tab no longer labels providers; Settings has one plain line about the add-on instead, shown only while it is not installed.
  • New for developers: the hulo_payments_provider_note filter adds a line under a provider on the Payment methods tab.

0.1.1

  • Fixed: a refund made in the Stripe dashboard was not recorded on Stripe accounts whose API version is 2022-11-15 or later, because Stripe’s charge.refunded event no longer names the refund. The plugin now reads the payment’s refunds back from Stripe and adds each one once, so the payment, its refund form, the Overview and the refunds on its order, if it has one, match Stripe. “Register webhook” also subscribes to refund.created and brings an endpoint registered by 0.1.0 up to date, keeping its secret.
  • Fixed: on Stripe accounts whose API version is older than 2022-11-15, releasing an authorisation, letting one expire or capturing only part of one was counted as a refund (and its order, if it had one, was refunded too), because Stripe reports the released amount as a refund. Refunds are now recorded only on money that was taken: a release is never counted as a refund, written to the ledger as one or added to the order.
  • Fixed: a release from the payment’s page was written to the ledger twice (once more when Stripe’s event for it arrived).
  • Fixed: the Overview added amounts in different currencies together (for example yen and euros taken by forms in two currencies). Each currency now has its own line.
  • Fixed: sending the refund form with its amount field emptied refunded everything left on the payment. The amount is now required.
  • Pay links: the currency is chosen from a list, so a mistyped code can no longer make a link that fails when the payer opens it.
  • Amounts follow their currency: a payment form that lets the payer choose takes no less than Stripe’s minimum charge in its currency (for example ¥50 or HK$4), amount fields step in the currency’s own units (whole yen, for example), and an amount with more decimals than its currency has is refused instead of rounded. The hosted payment page says so when an amount is below the minimum Stripe accepts.
  • “Register webhook” now says when it replaced an endpoint for this site’s address that it had not created itself.
  • The readme and the Stripe settings say that Stripe shows Apple Pay only once your domain is added under Settings Payment method domains in the Stripe dashboard.
  • For developers: hulo_payments_webhook_event passes the normalised event fields only (the provider’s payload is no longer included), and a refund call made again after a time-out stays one refund even when Stripe’s webhook for it arrives first.
  • Fixed: two refunds of the same amount made within a minute (from the payment’s page, the PHP API or an order’s refund button) reached Stripe with the same idempotency key, so Stripe made one refund while the plugin counted two. Each refund request now has its own key, a refund form sent twice refunds once, a refund Stripe has already reported is never counted again, and refunds, captures and releases of one payment run one after the other.
  • Fixed: a payment form refused in the browser (an amount above the maximum, an e-mail address that is not accepted, too many attempts, or a form from a page cached before this update) showed a raw JSON message. The payer now goes back to the form’s page with the reason shown above the form, and the amount field has its maximum.
  • Fixed: a “Signed-in only”, user-role or country rule made payment forms and pay links unpayable, because those payments have no checkout customer. These three rules now apply where the customer is known, at the checkout and on order payments, and the Rules tab shows them only when there is a checkout. Payment forms, pay links and API payments use the amount and currency rules.
  • The payment form block is registered from block.json with block API version 3 (WordPress 6.9 deprecates version 2), and its editor strings can be translated.
  • The hosted page’s Content-Security-Policy also allows the hosts Stripe’s security guide lists for Stripe.js and Link (*.js.stripe.com, link.com).
  • Admin: the capture, release and refund buttons, and the Pro box’s “Hide” button, stay on one line (their forms are no longer inside paragraphs).
  • Security: the hosted payment page confirms only the Stripe payment it created for that payment link, at the payment’s amount and currency; a payment reference sent by the browser is ignored.
  • Security: rate limits use the connecting IP address. Forwarding headers (X-Forwarded-For, CF-Connecting-IP, X-Real-IP) are used only for requests from a proxy you list under Settings Trusted proxies (or in the HULO_TRUSTED_PROXIES constant), taking the right-most address that is not one of your proxies.
  • Fixed: “Paid by link” on the Overview now counts pay links paid on the hosted payment page (it only counted Pro’s provider payment links).
  • The payment form has its own small stylesheet and takes the theme’s button style; its spam trap is hidden without inline styles. Payment, source and provider names in the admin are shown as readable, translatable labels.
  • The hosted payment page, its message pages and the admin screens load their styles and scripts through WordPress (the page’s CSP nonce is added through core’s script filters), every admin form and REST field is sanitised as it is read, and add-on payment actions pass an allow-list.
  • Checkout block requests are recognised whatever the case of the URL, and add-ons can correct an order just before its payment is created.

0.1.0

  • First release: payment forms (block and shortcode), pay links and a hosted payment page; Stripe with wallets, 3-D Secure, automatic or manual capture, refunds, disputes and signed idempotent webhooks; payments list, ledger and dashboard; rules; standalone payments API for other plugins. With WooCommerce: checkout gateway (classic, block, pay-for-order), pay later by invoice, order sync and an integration API for orders.