# HikaShop

Part of the Orboni API reference: https://orboni.com/docs. This page: https://orboni.com/docs/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): https://github.com/orboni/hikashop-payment on GitHub. Joomla’s own updater offers its new versions.

## Set it up

1. Download plg_hikashoppayment_orboni.zip from the newest release (https://github.com/orboni/hikashop-payment/releases/latest/download/plg_hikashoppayment_orboni.zip). In Joomla’s administrator, open System → Install → **Extensions** and upload it. The plugin switches itself on.
2. In 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. In 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. Under 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. Add 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. Place 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.

| Payment | Orboni says | In HikaShop |
| --- | --- | --- |
| Paid in full | `complete, paid` | Confirmed, a history line naming the coin, the network and the session; HikaShop emails the buyer |
| On the chain, not final yet | `processing` | Still Created, with a history line; Confirmed once final |
| Part paid | `partially_paid` | Still Created, saying how much came; the payment page asks the buyer for the rest |
| Held for your review | `held` | Still Created, giving the reason; accept it in the dashboard and the order is Confirmed |
| Left by the page’s back link, nothing sent | `open, unpaid` | Cancelled by HikaShop itself, and the buyer is back at checkout with the cart, to pay another way |
| Ran out with nothing paid | `expired, unpaid` | Cancelled, saying why |
| Ran out part paid | `expired, partially_paid` | Still Created, saying what arrived of what was due; settle the rest with the buyer |
| Paid for an order changed after its page opened | `complete, paid` | Still Created, with what was paid and what the order totals; check it before shipping |
| Money that paid it left the chain | `payment_reversed` | Back to Created, told not to ship until the dashboard shows it paid again |
| More came after it was paid | `extra_received` | A 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: https://orboni.com/docs#currencies). 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.

| Parameter | Type | What |
| --- | --- | --- |
| `amount` | integer | The order’s total with shipping, taxes and any payment fee, in the currency’s smallest unit: cents, or whole yen. |
| `currency` | string | The order’s currency, in lower case: usd, eur, jpy… |
| `description` | string | The order’s products, as “Mug × 2, Poster”, cut at 250 characters. |
| `details` | string | The order number and your site’s name: “Order A1B2C3 at Example Store”. |
| `client_reference_id` | string | HikaShop’s id of the order: “42”. |
| `metadata` | object | 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_email` | string | The buyer’s email, where Orboni sends the receipt when your project sends receipts. |
| `locale` | string | The buyer’s language in your store, as en-GB. |
| `success_url, cancel_url` | string | 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.
