API reference

WooCommerce

The Orboni for WooCommerce plugin adds “Crypto” to your checkout, with no code. The buyer places the order, picks a coin on Orboni’s payment page and pays from any wallet or exchange; the money goes to the wallets you set in the dashboard, and the order is marked paid by itself once the payment is final on the chain.

It works with the block checkout and the classic one, and with WooCommerce’s order tables (HPOS). It needs WordPress 6.5, WooCommerce 8.0 and PHP 7.4 or later.

Set it up

  1. 1In WordPress, go to Plugins → Add New Plugin, search for “Orboni” and install Orboni for WooCommerce, then activate it. WooCommerce must be active.
  2. 2In the Orboni dashboard, set the wallets you want to be paid to under Wallets, then copy a secret key under Developers → API keys — a test key (sk_test_…) first.
  3. 3In WordPress, open WooCommerce → Settings → Payments → Orboni, paste the key and tick Enable.
  4. 4Under Developers → Webhooks, add an endpoint at https://your-store.com/wp-json/orboni/v1/webhook (the plugin’s settings show your store’s own address) with every event, or at least the checkout.session.* ones, and paste its signing secret (whsec_…) into the plugin’s settings.
  5. 5Place an order, and on its payment page, signed in to the dashboard, press Simulate payment: the order turns Processing. Then swap in your live key and the live endpoint’s secret.

How orders move

The plugin reads the payment back from Orboni before it changes an order, and the order follows the payment as it is now — whether the webhook, the buyer’s return or a scheduled check comes first, twice or out of order.

PaymentOrboni saysThe order
Paid in fullcomplete, paidProcessing — or Completed, for an order WooCommerce completes by itself
On the chain, not final yetprocessingOn hold, until it is final
Part paidpartially_paidOn hold, with how much came; the payment page asks the buyer for the rest
Held for your reviewheldOn hold, with the reason; accept it in the dashboard and the order is paid
Ran out with nothing paidexpired, unpaidCancelled, if it still waits for payment
Money that paid it left the chainpayment_reversedBack to On hold
More came after it was paidextra_receivedA note with the total; the order stays paid

A paid order is never taken back by anything else. Each change is written on the order as a note: the coin, the network, the amount and the session. Without a webhook the order still moves: the plugin reads the payment when the buyer comes back to “Order received”, ten minutes after the payment page opens, and again after it runs out. WooCommerce’s own sweep of unpaid orders (“Hold stock”) waits for a crypto order until an hour after its page ran out, because what was sent in time may still confirm.

Good to know

  • Your store’s currency: US dollars, euros, pounds, yen or any other currency a checkout session takes (Currencies in the API reference). The payment page shows the order’s total in it, and Orboni turns it into dollars at the rate of the day (the European Central Bank’s, or the market’s for a currency the ECB does not publish); the buyer pays that in the coin they pick. In a store whose currency is not on the list Crypto is not offered at checkout, and the settings page says so and names the ones it takes.
  • The least is worth $1.00. In a US-dollar store the plugin does not offer Crypto for a smaller order; in another currency Orboni checks the total’s worth when the buyer places the order, and a buyer whose order is worth less is told it is below the minimum for a crypto payment.
  • A buyer who goes back and presses Pay again gets the same payment page while it is open, never a second session for the same order and amount.
  • An order whose total grew after the buyer was sent to pay is put on hold when the payment completes, not marked paid.
  • Refunds: the money is in your wallet, so send it back from there and record the refund in the dashboard. The plugin does not refund through WooCommerce.
  • Several stores can share one Orboni project: each adds its own endpoint and acts only on its own orders.
  • Turn on “Debug log” in the settings to see every request under WooCommerce → Status → Logs (source “orboni”). Errors are logged either way; keys and signing secrets never are.

What the plugin sends

Each order makes a checkout session through POST /v1/checkout/sessions, with an idempotency key of the store, the order, the amount and its currency, and the try, so a retry never makes a second one.

amountinteger
The order’s total, in the currency’s smallest unit: cents, or whole yen.
currencystring
The store’s currency, in lower case: usd, eur, jpy…
descriptionstring
The items, as “Blue mug × 2, Green tea”, cut at 250 characters.
detailsstring
The order’s number and your store’s name: “Order 1042 at Mug & Tea Shop”.
client_reference_idstring
The WooCommerce order’s id.
metadataobject
woocommerce_order_id, woocommerce_order_number, and woocommerce_site — a short hash of the store’s address, so two stores on one project never act on each other’s events.
customer_emailstring
The billing email, where Orboni sends the buyer’s receipt when your project sends receipts.
localestring
The language WordPress is showing the buyer.
success_url, cancel_urlstring
“Order received”; and the checkout, or the order’s own pay page for an order made in the admin.

The order keeps the session’s id as its transaction id, so a payment in the dashboard, an export or a webhook leads to its order by client_reference_id, and the order to its payment by the transaction id.

This page as Markdown, for a program or an AI assistant: /docs/woocommerce.md. Something missing or unclear? Write to us from the dashboard’s Help & Support.