# Blesta

Part of the Orboni API reference: https://orboni.com/docs. This page: https://orboni.com/docs/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: https://github.com/orboni/blesta-gateway on GitHub.

## Set it up

1. Download `orboni-blesta-…zip` from the newest release (https://github.com/orboni/blesta-gateway/releases/latest) and upload the `orboni` folder in it to `components/gateways/nonmerchant/` of your Blesta.
2. In Blesta’s admin, open Settings → Company → Payment Gateways → Available, and install **Orboni (crypto)**. Its settings open.
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 the gateway’s Secret key.
4. Under 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. Pay 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.

| Payment | Orboni says | In Blesta |
| --- | --- | --- |
| Paid in full | `complete, paid` | An approved transaction, naming the coin and the network; the invoices are paid |
| On the chain, not final yet | `processing` | A pending transaction, approved once the payment is final |
| Part paid | `partially_paid` | A pending transaction saying how much came; the payment page asks the client for the rest |
| Held for your review | `held` | A pending transaction giving the reason; accept it in the dashboard and it is approved |
| Ran out with nothing paid | `expired, unpaid` | Nothing is recorded |
| Ran out part paid | `expired, partially_paid` | What arrived is approved and applied to the invoices in order; the rest stays due |
| Money that paid it left the chain | `payment_reversed` | The transaction is declined and the invoices are due again; approved again if the payment completes again |
| More came after it was paid | `extra_received` | The 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: https://orboni.com/docs#currencies). 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.

| Parameter | Type | What |
| --- | --- | --- |
| `amount` | integer | What the client is paying, in the currency’s smallest unit: cents, or whole yen. |
| `currency` | string | The invoices’ currency, in lower case: usd, eur, jpy… |
| `description` | string | The invoices’ lines, as “Web hosting Starter, Domain example.com × 2”, cut at 250 characters. |
| `details` | string | Blesta’s own words for the payment and your company’s name: “Invoice #1042 at Example Hosting”. |
| `client_reference_id` | string | The invoices’ numbers: “1042”, or “1042, 1043” for two. |
| `metadata` | object | 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_email` | string | The client’s email, where Orboni sends the receipt when your project sends receipts. |
| `locale` | string | The client’s language in Blesta. |
| `success_url, cancel_url` | string | 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.
