API reference

VirtueMart

The Orboni plugin adds crypto to VirtueMart’s checkout, with no code. The buyer chooses Crypto as the payment method, confirms the order 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 VirtueMart 4 payment plugin for Joomla 4, 5 and 6, tested end to end on Joomla 5.4 with VirtueMart 4.6.4. It is free, and its source is open, under the GNU GPL (version 2 or later): orboni/virtuemart-payment on GitHub. Joomla’s own updater offers its new versions.

Set it up

  1. 1Download plg_vmpayment_orboni.zip from the newest release. In Joomla’s administrator, open System → Install → Extensions and upload it. The plugin switches itself on.
  2. 2In VirtueMart → Payment Methods, press New, name the method (for example “Crypto (USDT, USDC, BTC and more)”), choose Orboni for VirtueMart as the payment method, set it published and save.
  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 on the method’s Configuration tab, and save.
  4. 4Under Developers → Webhooks, add an endpoint at the Webhook address the Configuration tab shows, 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.
  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

Confirming the order makes it in VirtueMart as Pending and sends the buyer to Orboni’s payment page for its total. The cart is kept until the payment is seen, so a buyer who comes back without paying can 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 VirtueMart
Paid in fullcomplete, paidConfirmed, a history line naming the coin, the network and the session; VirtueMart emails the buyer
On the chain, not final yetprocessingStill Pending, with a history line; Confirmed once final
Part paidpartially_paidStill Pending, saying how much came; the payment page asks the buyer for the rest
Held for your reviewheldStill Pending, giving the reason; accept it in the dashboard and the order is Confirmed
Left by the page’s back link, nothing sentopen, unpaidStill Pending: the buyer is back in the cart, still full, to pay another way
Ran out with nothing paidexpired, unpaidCancelled, saying why; confirming the cart again makes a new order and a new page
Ran out part paidexpired, partially_paidStill Pending, saying what arrived of what was due; settle the rest with the buyer
Paid for an order changed after its page openedcomplete, paidStill Pending, with what was paid and what the order totals; check it before shipping
Money that paid it left the chainpayment_reversedBack to Pending, 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 on the method’s Configuration tab. Without a webhook a payment is still recorded once the buyer comes back from the payment page, and the cron address reads back open pages whose webhook did not arrive; set up the webhook all the same. An order opened in the administrator is read back too, and its payment section shows its sessions and the one that paid it.

Good to know

  • The currency: the store’s, or the one chosen as Payment currency on the Configuration tab — 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 countries, amounts, shopper groups and fee are set as for any VirtueMart 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 in the cart to choose another way to pay.
  • Each confirm is an order of its own, as with VirtueMart’s other redirect payments: a buyer who comes back and confirms again gets a new order and a new page, and the earlier order is cancelled once its page runs out unpaid.
  • 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 VirtueMart.
  • 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 stored encrypted, as VirtueMart stores its payment methods’ secrets. Debug log writes each request and webhook to administrator/logs/plg_vmpayment_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 payment 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 store’s name: “Order JFTT04 at Example Store”.
client_reference_idstring
VirtueMart’s id of the order: “42”.
metadataobject
virtuemart_order_id, virtuemart_order_number and virtuemart_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 number and a key of its own, which reads the payment back and tells the buyer where it stands; and the cart, still full.

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 payment section.

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