API reference

Blesta

The Orboni gateway lets your clients pay Blesta invoices in crypto, with no code. The client chooses Orboni (crypto) when paying one or more invoices, 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 invoices are paid by themselves once the payment is final on the chain. Blesta then goes on as after any other payment.

It needs Blesta 6 and is tested on 6.0.4. It has no cron of its own: Orboni’s webhook and the client’s return record each payment. Its source is open, under the MIT license: orboni/blesta-gateway on GitHub.

Set it up

  1. 1Download orboni-blesta-…zip from the newest release and upload the orboni folder in it to components/gateways/nonmerchant/ of your Blesta.
  2. 2In Blesta’s admin, open Settings → Company → Payment Gateways → Available, and install Orboni (crypto). Its settings open.
  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 Webhook address shown on the gateway’s settings page (https://your-site.com/callback/gw/1/orboni/), with every event, or at least the checkout.session.* ones. Paste its signing secret (whsec_…) into Webhook signing secret, tick the currencies to offer it in and save.
  5. 5Pay an invoice with Orboni (crypto), and on its payment page, signed in to the dashboard, press Simulate payment: the invoice is paid. Then swap in your live key and the live endpoint’s secret. The key decides test or live.

How payments move

The gateway reads the payment back from Orboni before it changes anything, and Blesta follows the payment as it is now — whether the webhook or the client’s return comes first, twice or out of order. Each payment is one transaction under Billing → Transactions, whose note says what happened, and Blesta applies it to the invoices once it is approved.

PaymentOrboni saysIn Blesta
Paid in fullcomplete, paidAn approved transaction, naming the coin and the network; the invoices are paid
On the chain, not final yetprocessingA pending transaction, approved once the payment is final
Part paidpartially_paidA pending transaction saying how much came; the payment page asks the client for the rest
Held for your reviewheldA pending transaction giving the reason; accept it in the dashboard and it is approved
Ran out with nothing paidexpired, unpaidNothing is recorded
Ran out part paidexpired, partially_paidWhat arrived is approved and applied to the invoices in order; the rest stays due
Money that paid it left the chainpayment_reversedThe transaction is declined and the invoices are due again; approved again if the payment completes again
More came after it was paidextra_receivedThe transaction’s note says what came in all; send the extra back from your wallet if the client asks

Without a webhook a payment is still recorded once the client comes back from the payment page, as it is at that moment; one confirmed later is recorded only by the webhook, so set it up. Each step goes to Blesta’s gateway log (Tools → Logs → Gateway).

Good to know

  • The invoices’ currency: US dollars, euros, pounds, yen or any other currency a checkout session takes (Currencies in the API reference). The payment page shows the total in it, and the client pays its worth in the coin they pick. The gateway is offered only for invoices in one of those currencies, and only in the ones you tick.
  • The least is worth $1.00. A smaller payment says it is below the minimum for a crypto payment.
  • Several invoices paid at once make one payment page for their total, and the payment is applied to each.
  • 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 invoices and amount. While money for that payment is on its way, the client is told so instead of getting a second page.
  • An invoice paid twice: the second payment stays the client’s credit. An invoice changed to ask for more after its payment page opened gets what was paid, and the rest stays due.
  • One-time payments only. Each renewal invoice is paid like any other.
  • Refunds: the money is in your wallet, so send it back from there and record the refund in the dashboard and in Blesta.
  • Several Blesta sites, or companies of one Blesta, can share one Orboni project: each adds its own endpoint and acts only on its own payments.
  • The gateway never logs the key or the signing secret.

What the gateway sends

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

amountinteger
What the client is paying, in the currency’s smallest unit: cents, or whole yen.
currencystring
The invoices’ currency, in lower case: usd, eur, jpy…
descriptionstring
The invoices’ lines, as “Web hosting Starter, Domain example.com × 2”, cut at 250 characters.
detailsstring
Blesta’s own words for the payment and your company’s name: “Invoice #1042 at Example Hosting”.
client_reference_idstring
The invoices’ numbers: “1042”, or “1042, 1043” for two.
metadataobject
blesta_client_id, blesta_invoices (each invoice’s id and the amount for it), blesta_return (the Blesta page the client goes back to), and blesta_site — a short hash of the Blesta company, 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 Blesta.
success_url, cancel_urlstring
The gateway’s callback address, which reads the payment back, records it and sends the client on to Blesta’s page; and the page where the client chooses how to pay.

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 invoices by client_reference_id, and an invoice to its payment by the transaction id.

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