# VirtueMart

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

## Set it up

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

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.

| Payment | Orboni says | In VirtueMart |
| --- | --- | --- |
| Paid in full | `complete, paid` | Confirmed, a history line naming the coin, the network and the session; VirtueMart emails the buyer |
| On the chain, not final yet | `processing` | Still Pending, with a history line; Confirmed once final |
| Part paid | `partially_paid` | Still Pending, saying how much came; the payment page asks the buyer for the rest |
| Held for your review | `held` | Still Pending, giving the reason; accept it in the dashboard and the order is Confirmed |
| Left by the page’s back link, nothing sent | `open, unpaid` | Still Pending: the buyer is back in the cart, still full, to pay another way |
| Ran out with nothing paid | `expired, unpaid` | Cancelled, saying why; confirming the cart again makes a new order and a new page |
| Ran out part paid | `expired, partially_paid` | Still Pending, 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 Pending, with what was paid and what the order totals; check it before shipping |
| Money that paid it left the chain | `payment_reversed` | Back to Pending, 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 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: 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 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.

| 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 payment 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 store’s name: “Order JFTT04 at Example Store”. |
| `client_reference_id` | string | VirtueMart’s id of the order: “42”. |
| `metadata` | object | 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_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 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.
