# XenForo

Part of the Orboni API reference: https://orboni.com/docs. This page: https://orboni.com/docs/xenforo.

The Orboni add-on makes Orboni one of XenForo’s payment providers, with no code. A member buying an account upgrade — or anything another add-on sells through XenForo’s payment profiles — 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 once the payment is final XenForo applies the upgrade, adds the member to its user groups and emails the receipt, as with any other provider.

It is an add-on for XenForo 2.3 and later, tested end to end on 2.3.13. It is free, and its source is open, under the MIT license: https://github.com/orboni/xenforo-payment on GitHub.

## Set it up

1. Download orboni-xenforo.zip from the newest release (https://github.com/orboni/xenforo-payment/releases/latest/download/orboni-xenforo.zip). In the admin control panel, open Add-ons → **Install/upgrade from archive** and choose it. XenForo offers that only with `$config['enableAddOnArchiveInstaller'] = true;` in `src/config.php`; without it, copy the contents of the zip’s `upload/` folder into your forum’s root and install Orboni crypto payments from the Add-ons page.
2. Setup → Payment profiles → **Add payment profile**, provider Orboni. Its display title is what members see, for example “Crypto (USDT, USDC, BTC and more)”.
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.
4. Under Developers → Webhooks, add an endpoint at the Webhook address shown on the profile (`…/payment_callback.php?_xfProvider=orboni`), with every event, or at least the `checkout.session.*` ones, and paste its signing secret (`whsec_…`) into Webhook signing secret. Save.
5. Users → User upgrades: tick the Orboni profile under Payment profiles on an upgrade that is not recurring.
6. Buy the upgrade as a member, and on its payment page, signed in to the dashboard, press **Simulate payment**: the upgrade is applied. Then swap in your live key (`sk_live_…`) and the live endpoint’s secret. The key decides test or live at Orboni; XenForo’s `enableLivePayments` setting does not apply.

## What happens to an upgrade

Pressing Purchase with the Orboni profile sends the member to Orboni’s payment page for the upgrade’s cost, and grants nothing yet: the upgrade is applied once the payment is final. The add-on reads the payment back from Orboni before it changes anything, and the upgrade follows the payment as it is now — whether the webhook, the member’s return or the cron comes first, twice or out of order. What happened is written to Logs → Payment provider log.

| Payment | Orboni says | In XenForo |
| --- | --- | --- |
| Paid in full | `complete, paid` | The upgrade applied and the member added to its user groups; XenForo’s receipt emailed; the payment logged under the session’s id, naming the coin and the network |
| On the chain, not final yet | `processing` | Nothing yet, a line in the log; applied by itself once final |
| Part paid | `partially_paid` | Not applied, a line in the log saying how much came; the payment page asks the member for the rest |
| Held for your review | `held` | Not applied, an error in the log giving the reason; accept it in the dashboard and the upgrade is applied |
| Left by the page’s back link, nothing sent | `open, unpaid` | Nothing: the member is back on the upgrades page |
| Ran out with nothing paid | `expired, unpaid` | Nothing, a line in the log; buying again opens a new page |
| Ran out part paid | `expired, partially_paid` | Not applied, an error in the log saying what arrived of what was due; settle it with the member |
| Money that paid it left the chain | `payment_reversed` | The upgrade taken back, as XenForo does for a reversed payment, until the dashboard shows it paid again: then applied again |
| More came after it was paid | `extra_received` | A line in the log saying what came in all; send the extra back from your wallet if the member asks |

Without a webhook a payment is still applied once the member comes back from the payment page, and the cron entry “Orboni: read back open payments” reads back, every 15 minutes, pages whose webhook did not arrive; set up the webhook all the same. XenForo runs its cron entries as the forum is visited, or from a server cron.

## Good to know

- Recurring: Orboni takes one payment per payment page, so XenForo refuses the Orboni profile on an upgrade marked recurring. Offer a non-recurring upgrade, which the member buys again when it ends.
- The currency: 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 upgrade’s cost in it, and the member pays its worth in the coin they pick. XenForo refuses the Orboni profile on an upgrade in another currency.
- The least is worth $1.00. A member buying something cheaper is told it is below the minimum.
- Each press of Purchase opens a new payment page: XenForo makes a new purchase request every time.
- Refunds: the money is in your wallet, so send it back from there, record the refund in the dashboard, and end the upgrade in XenForo (Users → User upgrades → Active upgrades).
- Several forums can share one Orboni project: each adds its own endpoint and acts only on its own purchases.
- The settings show the key and the secret as hidden fields. The log keeps each webhook and what it did, with the session read back; keys, secrets and the member’s email never.
- Switched off, the add-on still applies payments made before; members cannot choose its profiles until it is on again.

## What the add-on sends

Each purchase makes a checkout session through `POST /v1/checkout/sessions`, with XenForo’s purchase request key as its idempotency key, so a retry never makes a second one. Nothing is sent until a member pays with it.

| Parameter | Type | What |
| --- | --- | --- |
| `amount` | integer | The upgrade’s cost, in the currency’s smallest unit: cents, or whole yen. |
| `currency` | string | The upgrade’s currency, in lower case: usd, eur, jpy… |
| `description` | string | XenForo’s title for the purchase: “Account upgrade: Gold (alice)”. |
| `details` | string | The upgrade and your forum’s title: “Gold at Example Forum”. |
| `client_reference_id` | string | XenForo’s purchase request key, which the payment provider log is searched by. |
| `metadata` | object | xenforo_request_key (the same key), xenforo_purchasable (user_upgrade for an upgrade) and xenforo_user_id (the member’s user id). |
| `customer_email` | string | The member’s email, where Orboni sends the receipt when your project sends receipts. |
| `locale` | string | The member’s language on your forum, as en-US. |
| `success_url, cancel_url` | string | The add-on’s return address (index.php?orboni/return), which reads the payment back and shows XenForo’s page for the purchase; and the upgrades page. |

No other member data is sent. The payment provider log keeps the session’s id as the payment’s transaction, so a payment in the dashboard, an export or a webhook leads to its purchase by `client_reference_id`, and a purchase to its payment by the session id.
