Blokko Payments

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.

Links

• Blokko website: https://www.blokko.io/
• API documentation: https://docs.blokko.us/
• Supported payment methods: https://blokko.us/supported-payment-methods/
• Contact: https://blokko.us/contact/

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:

• Terms of use: https://www.blokko.us/docs/TermsandConditionswebsite.pdf
• Privacy policy (USA): https://www.blokko.us/docs/PrivacyPolicyforUSA.pdf
• Privacy policy (Brazil): https://www.blokko.us/docs/PrivacyPolicyforBrazil.pdf
• Privacy policy (Mexico): https://www.blokko.us/docs/PrivacyPolicyforMexico.pdf

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.