API reference

HikaShop

The Orboni plugin adds crypto to HikaShop’s checkout, with no code. The buyer chooses Crypto as the payment method, presses Finish and pays on Orboni’s payment page, picking a coin and paying 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.

It is a HikaShop 6 payment plugin for Joomla 4, 5 and 6, for HikaShop Starter, Essential and Business alike, tested end to end on Joomla 5.4 with HikaShop Starter 6.8.2. It is free, and its source is open, under the GNU GPL (version 2 or later): orboni/hikashop-payment on GitHub. Joomla’s own updater offers its new versions.

Set it up

  1. 1Download plg_hikashoppayment_orboni.zip from the newest release. In Joomla’s administrator, open System → Install → Extensions and upload it. The plugin switches itself on.
  2. 2In HikaShop → System → Payment methods, press New and choose Orboni. It comes named “Crypto (USDT, USDC, BTC, ETH and more)” and published; change the name if you like.
  3. 3In 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 — into Secret key, and save.
  4. 4Under Developers → Webhooks, add an endpoint at the Webhook address the method’s settings show, with every event, or at least the checkout.session.* ones, and paste its signing secret (whsec_…) into Webhook signing secret. Save.
  5. 5Add the Cron address shown under it in System → Scheduled Tasks as a GET Request task every 15 minutes, or call it from your server’s cron: it reads back payments whose webhook did not arrive, and cancels orders whose page ran out unpaid. HikaShop Essential and Business do the same from their own cron when it runs; Starter has none.
  6. 6Place an order with Crypto, and on its payment page, signed in to the dashboard, press Simulate payment: the order turns Confirmed. Then swap in your live key (sk_live_…) and the live endpoint’s secret. The key decides test or live at Orboni.

How orders move

Finishing the checkout makes the order in HikaShop as Created and sends the buyer to Orboni’s payment page for its total. HikaShop keeps the cart until its thank-you page, so a buyer who leaves the payment page can still choose another way. The plugin reads the payment back from Orboni before it changes anything, and the order follows the payment as it is now — whether the webhook, the buyer’s return or the cron comes first, twice or out of order. What happened is written in the order’s history; only the move to Confirmed is told to the buyer.

PaymentOrboni saysIn HikaShop
Paid in fullcomplete, paidConfirmed, a history line naming the coin, the network and the session; HikaShop emails the buyer
On the chain, not final yetprocessingStill Created, with a history line; Confirmed once final
Part paidpartially_paidStill Created, saying how much came; the payment page asks the buyer for the rest
Held for your reviewheldStill Created, giving the reason; accept it in the dashboard and the order is Confirmed
Left by the page’s back link, nothing sentopen, unpaidCancelled by HikaShop itself, and the buyer is back at checkout with the cart, to pay another way
Ran out with nothing paidexpired, unpaidCancelled, saying why
Ran out part paidexpired, partially_paidStill Created, saying what arrived of what was due; settle the rest with the buyer
Paid for an order changed after its page openedcomplete, paidStill Created, with what was paid and what the order totals; check it before shipping
Money that paid it left the chainpayment_reversedBack to Created, told not to ship until the dashboard shows it paid again
More came after it was paidextra_receivedA history line saying what came in all; send the extra back from your wallet if the buyer asks

The statuses for waiting, paid and ran out can be changed in the method’s settings. Back from the payment page, the buyer lands on HikaShop’s thank-you page, which says where the payment stands while it is not final, with the way back to the payment page while it is open. Without a webhook a payment is still recorded once the buyer comes back, and the cron address reads back open pages whose webhook did not arrive; set up the webhook all the same.

Good to know

  • The currency: the order’s own — 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 the buyer pays its worth in the coin they pick. Crypto is offered only in one of them; the method’s zones, amounts, quantities and fee are set as for any HikaShop payment method.
  • The least is worth $1.00. In dollars Crypto is not offered below it; in another currency the buyer is told the order is below the minimum and is back at checkout to choose another way to pay.
  • A buyer who pays a waiting order again from their account (HikaShop Essential and Business) gets the same payment page while it is open, not a second one.
  • Refunds: the money is in your wallet, so send it back from there, record the refund in the dashboard, and set the order Refunded in HikaShop.
  • Several Joomla sites can share one Orboni project: each adds its own endpoint and acts only on its own orders.
  • The secret key and the signing secret are kept with the method’s other settings and never shown again in its settings page: leave a field empty to keep what is saved. Debug log writes each request and webhook to administrator/logs/plg_hikashoppayment_orboni.php; errors are written either way, keys and secrets never.

What the plugin sends

Each order makes a checkout session through POST /v1/checkout/sessions, with an idempotency key of the site, the order and its amount, and the try, so a retry never makes a second one. Nothing is sent until the plugin has your key and a buyer pays with it.

amountinteger
The order’s total with shipping, taxes and any payment fee, in the currency’s smallest unit: cents, or whole yen.
currencystring
The order’s currency, in lower case: usd, eur, jpy…
descriptionstring
The order’s products, as “Mug × 2, Poster”, cut at 250 characters.
detailsstring
The order number and your site’s name: “Order A1B2C3 at Example Store”.
client_reference_idstring
HikaShop’s id of the order: “42”.
metadataobject
hikashop_order_id, hikashop_order_number and hikashop_site — a key made from your Joomla site’s own secret, so two sites on one project never act on each other’s events.
customer_emailstring
The buyer’s email, where Orboni sends the receipt when your project sends receipts.
localestring
The buyer’s language in your store, as en-GB.
success_url, cancel_urlstring
The plugin’s return address, with the order and a key of its own, which reads the payment back and shows HikaShop’s thank-you page; and HikaShop’s own cancel, back to checkout with the cart.

No address, phone number or other buyer data is sent. A payment in the dashboard, an export or a webhook leads to its order by client_reference_id and the order number in its metadata, and an order to its payment by the session id in its history.

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