API reference

FOSSBilling

The Orboni gateway lets your clients pay FOSSBilling invoices in crypto, with no code. The client chooses Orboni on an invoice, picks a coin on Orboni’s payment page and pays from any wallet or exchange. The money goes to the wallets you set in the dashboard, and the invoice is marked paid by itself once the payment is final on the chain. FOSSBilling then activates or renews what the invoice was for, as after any payment.

It needs FOSSBilling 0.8.9 or a later 0.8 release, with FOSSBilling’s cron running. Its source is open, under the MIT license: orboni/fossbilling-gateway on GitHub.

Set it up

  1. 1In FOSSBilling’s admin, open System → Payment Gateways, then the tab Install from the Extension Directory, and install Orboni. Or download it from its page in the directory and put its files in library/Payment/Adapter/Orboni.
  2. 2Press New Payment Gateway, install Orboni under Available Adapters, then open it from the list of gateways.
  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 the gateway’s Secret key.
  4. 4Under Developers → Webhooks, add an endpoint at the gateway’s IPN Callback URL, shown on its settings page (https://your-site.com/ipn.php?gateway_id=3), with every event, or at least the checkout.session.* ones. Paste its signing secret (whsec_…) into Webhook signing secret, tick Enabled and save.
  5. 5Pay an invoice with Orboni, and on its payment page, signed in to the dashboard, press Simulate payment: the invoice turns Paid. Then swap in your live key and the live endpoint’s secret. The key decides test or live; FOSSBilling’s Test Mode switch is not used.

How invoices move

The gateway reads the payment back from Orboni before it changes anything, and FOSSBilling follows the payment as it is now — whether the webhook or the client’s return comes first, twice or out of order. A paid payment goes on the client’s balance and pays the invoice from it, as FOSSBilling’s own gateways do, and each payment is one transaction under Invoices → Transactions.

PaymentOrboni saysIn FOSSBilling
Paid in fullcomplete, paidThe invoice is Paid, and what it was for is activated or renewed
On the chain, not final yetprocessingUnpaid, with a Received transaction the cron reads again until the payment is final
Part paidpartially_paidUnpaid, with a Received transaction saying how much came; the payment page asks the client for the rest
Held for your reviewheldUnpaid, with a Received transaction giving the reason; accept it in the dashboard and the invoice is paid
Ran out with nothing paidexpired, unpaidUnpaid; nothing is recorded
Ran out part paidexpired, partially_paidUnpaid, with a transaction in Error saying what arrived: settle it with the client
Money that paid it left the chainpayment_reversedA transaction in Error and a line in the log. FOSSBilling keeps the invoice paid, so check what it was for
More came after it was paidextra_receivedNothing changes; the payment in the dashboard shows what came in all

A paid invoice is never taken back by anything else. Without a webhook the invoice still moves once the client comes back from the payment page, and a payment still on its way then is read again on every run of FOSSBilling’s cron. Each change goes to FOSSBilling’s log, every line starting with “Orboni:”.

Good to know

  • The invoice’s currency: US dollars, euros, pounds, yen or any other currency a checkout session takes (Currencies in the API reference). The payment page shows the invoice’s total in it, and the client pays its worth in the coin they pick. In a currency Orboni does not take, the invoice says crypto is not taken in it; the gateway’s Accepted Currencies can keep it to the ones it takes.
  • The least is worth $1.00. A smaller invoice says it is below the minimum for a crypto payment.
  • A client who goes back and pays again gets the same payment page while it has more than five minutes left, never a second session for the same invoice and amount.
  • An invoice paid twice, or changed to ask for more after its payment page opened, is not paid again: the money stays on the client’s balance as credit, with a note on the transaction.
  • Add-funds invoices work too: the payment goes on the client’s balance.
  • One-time payments only. Each renewal invoice is paid on its own; FOSSBilling’s subscriptions are not offered.
  • Refunds: the money is in your wallet, so send it back from there and record the refund in the dashboard.
  • Several FOSSBilling sites can share one Orboni project: each adds its own endpoint and acts only on its own invoices.
  • The gateway never logs the key or the signing secret.

What the gateway sends

Each invoice makes a checkout session through POST /v1/checkout/sessions, with an idempotency key of the site, the invoice, the amount and its currency, and the try, so a retry never makes a second one.

amountinteger
The invoice’s total, in the currency’s smallest unit: cents, or whole yen.
currencystring
The invoice’s currency, in lower case: usd, eur, jpy…
descriptionstring
The invoice’s lines, as “VPS Small — 1 month, Extra IPv4 × 2”, cut at 250 characters.
detailsstring
The invoice’s number and your company’s name: “Invoice FOSS00042 at Example Hosting”.
client_reference_idstring
The FOSSBilling invoice’s id.
metadataobject
fossbilling_invoice_id, fossbilling_invoice_number, and fossbilling_site — a short hash of the site’s address, so two sites on one project never act on each other’s events.
customer_emailstring
The client’s email, where Orboni sends the receipt when your project sends receipts.
localestring
The client’s language in FOSSBilling.
success_url, cancel_urlstring
FOSSBilling’s ipn.php, which reads the payment back and opens the invoice; and the invoice itself.

The transaction keeps the session’s id as its transaction id, so a payment in the dashboard, an export or a webhook leads to its invoice by client_reference_id, and the invoice to its payment by the transaction id.

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