Description

Blokko Payments connects Blokko’s alternative payment methods to your store without changing how
you operate today. Blokko sums it up in its own tagline: “More Ways to Pay”.

According to Blokko, its service lets you accept stablecoins, real-time international payments and
crypto through the systems you already use, settling in local fiat currency over existing banking
rails, with connectivity to payment networks and regulated exchanges handled by Blokko. This plugin
is the WordPress side of that service.

Two ways to take a payment

At your WooCommerce checkout: Blokko appears as one more payment method, in the classic checkout
and in the Cart & Checkout Blocks, next to the ones your store already offers.
On any page of your site: a payment button you drop into a page with the WordPress block editor,
or with the [blokko_pago] shortcode, for a fixed amount or for an amount your customer types.

How the buyer pays

The buyer needs no account and no wallet on your site: they pick a payment method and pay on a
payment page hosted by Blokko, and several methods are paid by scanning a QR code. How they get
there depends on where the payment started:

At the WooCommerce checkout, Blokko’s payment page opens in a window over your own checkout, so
the buyer pays without leaving it. If their browser cannot open that window, they are taken to
Blokko’s payment page instead.
From a payment button on one of your pages, Blokko’s payment page opens in the same kind of
window over your page. If their browser cannot open it, they go to the page hosted by Blokko
instead.

Either way, Blokko returns the buyer to your site when they are done.

How a payment is confirmed

This is the part worth reading closely, because it defines what the plugin guarantees:

The notification Blokko sends decides nothing. It arrives signed, and its only effect is to bring
a check forward. The state carried in it is never used to mark an order as paid.
Confirmation is re-read from Blokko over a signed request. Marking an order as paid is decided by
the signed response of Blokko’s status endpoint — not by what a third party claims, and not by
what the browser returns.
The browser return page is informational. It exists to tell the buyer what happened; it is not a
payment authority.
Every request the plugin sends is signed, and every request it receives is verified against the
same signature before it is processed.
The amount and currency of the invoice Blokko returns are compared against the order. If they do
not match, Blokko’s payment page is not opened and the order is left for manual review.

Compatibility

HPOS (High-Performance Order Storage): the WooCommerce side of the plugin supports it, so the
store keeps working whichever order storage WooCommerce uses.

Payment methods

The available methods are not hardcoded in the plugin: they are read from your Blokko account and
grouped into real-time payments, stablecoins and exchanges. Two criteria are applied on top of that
list:

A method that Blokko reports as subject to AML (anti-money-laundering) controls is not offered.
A method whose order total exceeds the high-value transaction threshold Blokko defines for it is
shown with a warning.

Coverage, as stated by Blokko

Blokko states more than 700 wallets (among them Binance, Crypto.com and Strike), more than 200
alternative payment methods (including USDC, USDT, Bitcoin and international real-time payments)
and operation in Brazil, Mexico, Colombia, Chile, Bolivia and Peru, with Venezuela, Canada and the
European Union announced as upcoming. Coverage is defined by Blokko and depends on your account:
the plugin imposes no geographic restrictions of its own.

Current limits

Environments: sandbox and production are both selectable, and each keeps its own credentials. A
store with production selected and production credentials saved charges for real — update
deliberately. Blokko has confirmed production’s API base URL and its payment page; what has not
happened yet is the first real production invoice that exercises that host end to end.
Confirmation has no setting to turn it on or off: whatever Blokko confirms for the exact amount
and currency of the order or charge is marked as paid. The only way to refuse it for one site is a
code-level filter, described in the FAQ.
No currency conversion: the plugin sends the total in your store’s currency and converts nothing.
If your store charges in a currency your Blokko account does not settle, that payment will not
complete.

Requirements

WordPress 6.4 or newer.
PHP 8.1 or newer, with the OpenSSL extension.
A Blokko account with a Merchant ID, an API Key and an API Secret.
HTTPS on your site: the callback URL registered with Blokko is HTTPS.
WooCommerce is optional.

External services

Blokko Payments is a client of Blokko, a payment gateway, and it does not work without it: every
payment the plugin starts is created, hosted and settled by Blokko’s service. This plugin is the
WordPress side of a service you already have an account with. The service is described at
https://www.blokko.io/, and it is governed by its own terms of use and its own privacy policy:

The plugin talks to these Blokko hosts, and to no others. Which pair is used depends on the
environment you select in the plugin’s settings:

Sandbox: https://sandbox.blokko.dev (signed API) and https://payment-link-sandbox.blokko.dev (hosted payment page).
Production: https://api.blokko.app (signed API) and https://payment-link.blokko.app (hosted payment page).

When the plugin contacts Blokko, and what it sends

What follows is what the shipped code does. There is no telemetry, no usage reporting, no license
check and no update check against any server: every call below exists to start a payment or to
confirm one.

Creating the invoice for a payment. When a buyer places an order with Blokko selected as the
payment method, or submits a charge made with the “Blokko — Direct charge” block or the
[blokko_pago] shortcode, the plugin asks Blokko to create the hosted invoice for that payment. It
sends your Merchant ID, the amount of that order or charge in your store’s currency, and — when it
can build it — the address on your site Blokko should return the buyer to. Blokko answers with the
URL of the hosted invoice and with the amount and currency it recorded; the plugin compares those
against the order before the buyer is sent anywhere.
Re-reading the status of a transaction. When Blokko delivers an event to the callback URL your
site registered, the plugin asks Blokko for the status of the transaction that event names. The
event never marks an order as paid — it only brings the confirmation forward — and what the plugin
acts on is the signed answer of the status endpoint.
Registering your site’s callback URL. When you register the webhook from the plugin’s settings
screen, the plugin sends Blokko your Merchant ID and this site’s own callback URL. Registering an
earlier URL again, from that same screen, is the same call carrying that earlier URL instead.
Initializing the payment terminal. When you use “Verify connection”, the plugin sends Blokko the
terminal serial and type you configured, and stores the terminal identifier Blokko answers with.
The scheduled reconciliation. Confirming a payment is not the webhook’s job: the plugin re-reads
the status of the invoices a buyer worked on in the last 15 minutes, on a scheduled task that runs
every five minutes, and once more right away when a buyer comes back from Blokko’s payment page
(at most once every 30 seconds for the whole site). That read is a GET to the payment page host of
your environment, at /api/invoices/{reference}/payment-state, asking for the state of one invoice,
identified by the reference Blokko issued for it, and it carries no
credentials at all. It is a read-only query: it changes nothing on your site and nothing on
Blokko’s.

What does not leave your site

No buyer data. The buyer pays on the page hosted by Blokko without an account on your site, and the
plugin never receives or stores their name, email address, postal address, card details or wallet
keys — it does not read any of them, so there is nothing of theirs for it to send. The buyer’s own
browser does visit Blokko’s payment page, or loads it in the frame of the embedded checkout; that
request is the buyer’s browser contacting Blokko, the way any visit to a website is.

Your credentials: the signed calls to Blokko’s API carry your Merchant ID and your API Key to
identify your account, and each one carries a signature computed on your site with your API Secret.
The API Secret is never sent. What stays on your site is what Blokko has no need for: your orders
and charges, and the credentials you saved.

The embedded checkout’s frame

On a store that can pay with Blokko, the plugin can open the hosted payment page in a window on your
own checkout page, or on the page that carries a payment button, instead of navigating to it. That window loads the invoice URL Blokko returned for
that payment attempt in an iframe, and that URL is served by the payment page host of the
environment your store is bound to: payment-link-sandbox.blokko.dev in sandbox, payment-link.blokko.app
in production. The plugin accepts that frame’s address only when its host is exactly the one
configured for the environment in use — never a subdomain of it, never a suffix, never a wildcard —
and it sets no sandbox and no allow attribute on the frame. Nothing about the payment is decided in
that frame: the store’s own status endpoint decides it, as the Description of this plugin explains.

Screenshots

The Blokko Payments settings screen: credentials, environment and the active-environment badge.

The webhook section, with the callback URL visible and copyable and registration against Blokko. — The Blokko Payments settings screen: credentials, environment and the active-environment badge.

Blocks

This plugin provides 1 block.

Blokko — Direct charge Direct-charge form via Blokko (fixed or variable amount), without a shopping cart.

Installation

Upload the plugin folder to /wp-content/plugins/, or install the ZIP from Plugins Add New Upload Plugin.
Activate the plugin.
Go to “Blokko Payments” in the admin menu and enter the Merchant ID, API Key and API Secret from your Blokko account. The API Secret is stored and never shown again.
Pick the environment and save: sandbox and production are both selectable, and each keeps its own credentials, terminal and callback state.
Register the address Blokko calls back: the screen shows the exact URL and registers it with Blokko without leaving WordPress.

If you are going to take payments at your WooCommerce checkout:

Under WooCommerce Settings Payments, enable “Blokko Payments” and set the name and the text the buyer sees at checkout. If you do not have Blokko credentials yet, ask for them from “Blokko Payments” in the admin menu: that screen is where they are entered, and where the plugin offers to request them.

If you are going to put payment buttons on your own pages:

Insert the “Blokko — Direct charge” block on a page, or the [blokko_pago] shortcode, with a fixed or a buyer-entered amount.

FAQ

Do I need a Blokko account?: Yes. The plugin uses your Blokko account credentials (Merchant ID, API Key and API Secret). The one
who needs no account is the buyer: they pay on the page hosted by Blokko, without registering on
your site or opening a wallet there.
Does it work without WooCommerce?: Yes. Payment buttons work on any WordPress site: you insert the “Blokko — Direct charge” block, or
the [blokko_pago] shortcode, on one of your pages, with a fixed amount or one your customer types.
Neither WooCommerce nor any other commerce plugin is required.
Which countries does it operate in?: According to Blokko: Brazil, Mexico, Colombia, Chile, Bolivia and Peru, with Venezuela, Canada and
the European Union announced as upcoming. The plugin adds no geographic restrictions of its own —
actual availability is determined by your Blokko account.
Which currency do I receive the money in?: Blokko states that it settles in local fiat currency over existing banking rails. The plugin does
not convert currency: it sends the total in your store’s currency and requires the invoice Blokko
returns to match in amount and currency before opening Blokko’s payment page. If your store charges
in a currency your Blokko account does not settle, that payment does not complete.
The buyer closed the browser after paying. Is the payment lost?: No. Payment does not depend on the buyer seeing the return page: the plugin asks Blokko for the
status over a signed request, on a scheduled reconciliation, and also reacts to the events Blokko
sends. The confirmation arrives either way.
Does the notification Blokko sends mark the order as paid?: No, and that is deliberate. The notification arrives signed and only brings a check forward; the
state it carries never decides a payment. What marks an order as paid is the signed response of
Blokko’s status endpoint, queried by the plugin.
Can settlement be turned off for one site?: Only by code, and deliberately. There is no setting for it: when Blokko confirms a payment for the
exact amount and currency the order asked for, that order is marked as paid. To refuse settlement
for one site, whoever maintains it adds a filter that returns false — blokko_payments_settle_orders
for WooCommerce orders, blokko_direct_charge_settle_charges for direct charges. A store that still
has the older “settlement off” choice saved keeps that row where it is, and it decides nothing.
Why don’t I see every payment method?: Because the list is defined by your Blokko account, and two filters are applied on top: methods
subject to AML (anti-money-laundering) controls are not offered, and those above Blokko’s
high-value transaction threshold are shown with a warning.
Can the same payment be confirmed twice?: No. For a payment made from one of your pages, the move to “paid” is a single atomic transition on
the payment’s own record: only the process that actually performs it fires the extension event, and
a second attempt on the same payment does nothing and duplicates no events.
Does the plugin store card data or wallet keys?: No. The buyer picks the method and pays on the page hosted by Blokko; the plugin never receives or
stores that data. What stays on your site is your Blokko account credentials and the payment
records.
Can I use it in production today?: Yes. Production is selectable on the settings screen and each environment keeps its own
credentials, so a store with production selected and production credentials saved charges for
real. Do it deliberately: switching the selector does not move anything else, and the environment
you save is the one this store transacts against from then on.
What happens to my data if I uninstall the plugin?: Everything the plugin created is removed: its options, the payment records and its scheduled tasks.
On a multisite installation, the cleanup applies to the site being uninstalled or to the whole
network, depending on how it is uninstalled.

Reviews

There are no reviews for this plugin.

Contributors & Developers

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

blokko

Translate “Blokko Payments” into your language.

Interested in development?

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

Changelog

1.0.0

First stable release. No functional changes since 0.5.0.

0.5.0

The “Pay for order” page (the link in the order email, or My account Orders) now opens
Blokko’s payment page in the same window over your store as the checkout does, instead of
sending the buyer away. It only steps in when the buyer chose Blokko, so other payment methods
on that page work exactly as before.
When a payment takes longer than usual to confirm, the payment window says so and keeps
checking, instead of stopping; a buyer who closes it after returning sees that the payment is
still being confirmed.
The payment window’s waiting screens were redesigned: they stay readable on any theme, show
a moving progress indicator and the three steps of the payment, and announce each step to
screen readers.
When the buyer comes back from Blokko’s page, the store checks that payment with Blokko right
away instead of waiting for its next automatic pass, so a payment is confirmed in seconds even
when Blokko’s notification does not reach this site. Those checks are limited to one every 30
seconds for the whole store.
Automatic payment confirmation now checks only the payments a buyer worked on in the last
15 minutes, taking turns between them, so a store with a large number of abandoned carts
confirms real payments just as quickly and no longer asks Blokko about old abandoned ones.
When a paid order is not marked as paid because a support-level filter holds settlement back,
the order note says so.
The notification connection details describe a failure only by what this site can actually
know: whether it could not reach Blokko, or Blokko refused the request.
The Blokko section in WooCommerce’s payment settings now explains what Blokko does for your
store, shows your connection status, and offers a link to connect or request credentials —
without leaving the section. The Blokko Payments settings screen links back to it too, so you
can move between the two without guessing where either one lives.
After activating the plugin, a dismissible notice tells you when your store still needs
credentials and where to add them — on the plugin’s settings screen, WooCommerce’s Payments
screen, and the plugins list. It goes away on its own once your credentials are complete.
If your store stops receiving payment confirmations, the connection details now offer
“Reconnect Blokko’s notifications”: it tells Blokko to notify this site’s address again, and
says so before it does. If a reconnect fails, the settings screen keeps saying so until one
succeeds.

0.4.0

Direct charges pay in the same window as WooCommerce checkouts. The charge form (block or
shortcode) opens Blokko’s payment page in a window over your page instead of sending the
buyer away, and brings them back to your page when the payment settles. Without JavaScript
the form still works the classic way.
A buyer who closes that window and presses Pay again gets the same payment page back — never
a second one — and pressing Pay twice in a row opens one window, not two.

0.3.0

Payments Blokko confirms are always marked as paid, with no switch to forget. An order or a
direct charge is settled only when Blokko confirms the exact amount and currency it asked for.
To refuse settlement on one site, whoever maintains it can use the blokko_payments_settle_orders
or blokko_direct_charge_settle_charges filter (see the FAQ).
Blokko Payments is what your store calls it. The payment method, the settings screen and the
submenu all use the same name and speak in plain terms, and WooCommerce’s “Complete setup”
now takes you to the Blokko Payments screen instead of somewhere you cannot finish from.
Don’t have credentials yet? The settings screen now offers to request them, right beside the
place they go, and tells you what it will send.
The connection details and repair tools moved into a block you open only when you need them.
Nothing your store needs to take payments is hidden behind it.
Your terminal type is worked out from the serial you enter, so there is one less field to get
wrong.
The webhook repairs itself. If your callback address moves because you changed permalinks,
the plugin re-registers it without asking. If your site address itself changed, it says so
and waits for you: it will never send a registration you did not ask for.
A direct charge that got stuck now finishes on its own once its payment window closes, and
you can ask Blokko about any charge from the Transactions screen instead of waiting.
One order, one payment page. If a buyer closes the Blokko window without paying and comes
back to buy the same thing again, WooCommerce now reuses the order and the payment page they
already have instead of creating a second order with a second page that can also be paid.
Before this, both pages stayed payable and nothing stopped a buyer paying twice.
The new-order email to you now arrives when the payment is settled, instead of as soon as the
buyer is sent to the payment page. Your customer’s email changes with it: the order waits in
“pending payment” rather than “on hold”, so they no longer receive the “is on hold” email at
all, and WooCommerce sends them its order-received one when the payment settles. While the
payment page is unpaid the order waits for payment and nobody is emailed.
Fixed: switching the environment (sandbox/production) on the settings screen without reloading
left the Merchant ID and API Key showing the previous environment’s values; saving in that state
silently overwrote the new environment’s credentials with the old ones. The selector now reloads
the page with the chosen environment before saving is allowed.
Production is available. Both environments are selectable, each keeps its own credentials,
terminal and callback state, and a store with production selected and production credentials
saved charges for real. The first real production invoice is still the last step to be exercised
end to end.
Fixed: the “Cancel” button on the API Secret field now uses WordPress’ native styling for the
show/hide password pattern.
The collapsed API Secret field shows generic dots instead of looking empty.
The webhook section now really registers the URL with Blokko, reverting to the previous URL on
failure, and keeps the callback URL visible and copyable.
Active-environment badge (sandbox/production) next to the screen title.
Visual separation between the critical sections (credentials) and the optional ones
(notifications).
The payment method’s default description no longer says the buyer is redirected to Blokko:
the Blokko checkout now opens in a window on your own checkout page, and the description
works on both paths. A store that saved a description of its own keeps it — check yours if
it mentions a redirect.
Settlement is applied automatically, with no switch to turn on: when Blokko confirms a payment for
the exact amount and currency an order asked for, that order is marked as paid. The Settlement
section is gone from the settings screen, and refusing settlement for one site is a code-level
decision, documented in this readme.

Earlier releases are listed in changelog.txt.

Description

Two ways to take a payment

How the buyer pays

How a payment is confirmed

Compatibility

Payment methods

Coverage, as stated by Blokko

Current limits

Requirements

Links

External services

When the plugin contacts Blokko, and what it sends

What does not leave your site

The embedded checkout’s frame

Screenshots

Blocks

Installation

FAQ

Do I need a Blokko account?

Does it work without WooCommerce?

Which countries does it operate in?

Which currency do I receive the money in?

The buyer closed the browser after paying. Is the payment lost?

Does the notification Blokko sends mark the order as paid?

Can settlement be turned off for one site?

Why don’t I see every payment method?

Can the same payment be confirmed twice?

Does the plugin store card data or wallet keys?

Can I use it in production today?

What happens to my data if I uninstall the plugin?

Reviews

Contributors & Developers

Interested in development?

Changelog

1.0.0

0.5.0

0.4.0

0.3.0

Meta

Ratings

Contributors

Support