API reference

Odoo

The Orboni payment provider adds crypto to Odoo, with no code: on the eCommerce checkout, on orders and invoices paid from the customer portal, and on payment links. The customer chooses Crypto, 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 once the payment is final on the chain Odoo confirms the order or reconciles the invoice, as with any other payment provider.

It is a module, payment_orboni, for Odoo 18, 19 and 20, with the same features in each, and each is tested end to end. It is free on Odoo Apps. Its source is open, under the LGPL-3 license like Odoo’s own payment providers: orboni/odoo-payment-orboni on GitHub, with a branch for each Odoo version.

Set it up

  1. 1Download the module for your Odoo version from Odoo Apps (pick 20.0, 19.0 or 18.0 there), or payment_orboni-20.0-…zip from the newest release on GitHub. Put the payment_orboni folder in it into your Odoo’s addons path and restart Odoo.
  2. 2With developer mode on, open Apps → Update Apps List, then find Orboni in Apps and activate Payment Provider: Orboni. It appears under Invoicing (or Website, or Sales) → Configuration → Payment Providers; open it.
  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 provider’s Secret Key.
  4. 4Under Developers → Webhooks, add an endpoint at the Webhook Address shown on the provider (https://your-odoo.com/payment/orboni/webhook), with every event, or at least the checkout.session.* ones, and paste its signing secret (whsec_…) into Webhook Signing Secret.
  5. 5Keep the provider in test mode — State Test Mode on Odoo 18 and 19, Live off on Odoo 20 — and publish it. Pay an order with Crypto, and on its payment page, signed in to the dashboard, press Simulate payment: the order is confirmed.
  6. 6Then swap in your live key (sk_live_…) and the live endpoint’s secret, and go live: State Enabled, or Live on. The key decides test or live at Orboni, so Odoo takes only a test key in test mode and only a live key live.

How payments move

Each press of Pay is a transaction in Odoo with its own payment page. The module reads the payment back from Orboni before it changes anything, and the transaction follows the payment as it is now — whether the webhook or the customer’s return comes first, twice or out of order. Odoo writes each change on the order or invoice, and the transaction’s message says why (Configuration → Payment Transactions, in developer mode).

PaymentOrboni saysIn Odoo
Paid in fullcomplete, paidConfirmed, naming the coin and the network; Odoo confirms the order or reconciles the invoice
On the chain, not final yetprocessingPending, and the customer is told the payment is being confirmed; confirmed once final
Part paidpartially_paidPending, saying how much came; the payment page asks the customer for the rest
Held for your reviewheldPending, giving the reason; accept it in the dashboard and it is confirmed
Left by the page’s back link, nothing sentopen, unpaidCanceled; confirmed after all if the customer pays on that page later
Ran out with nothing paidexpired, unpaidCanceled
Ran out part paidexpired, partially_paidError, saying what arrived of what was due; settle the rest with the customer
Money that paid it left the chainpayment_reversedPending until it completes again; once confirmed, Odoo keeps it confirmed and the order or invoice gets a message to check
More came after it was paidextra_receivedA message on the order or invoice saying what came in all; send the extra back from your wallet if the customer asks

Without a webhook a payment is still recorded once the customer 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. A payment made after its page ran out still confirms its transaction. On Odoo 20, Odoo applies the payment in its own processing job, a moment after the webhook.

Good to know

  • The 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 customer pays its worth in the coin they pick. Odoo offers the provider only for a payment in one of them.
  • The least is worth $1.00. A smaller payment says it is below the minimum for a crypto payment.
  • A customer who presses Pay again makes a new transaction, with its own page. A retry of the same transaction gets the same page while it has more than five minutes left, never a second session.
  • Payment links: Odoo’s Generate a Payment Link on an order or invoice offers Crypto like the checkout does.
  • One-time payments only: no saved payment methods, so nothing is charged by itself. A renewal invoice is paid from the portal 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 Odoo, with a credit note.
  • Several Odoo databases can share one Orboni project: each adds its own endpoint and acts only on its own payments.
  • Only Odoo’s administrators see the keys, and the module never logs them.

What the module sends

Each transaction makes a checkout session through POST /v1/checkout/sessions, with an idempotency key of the database and the transaction’s reference, and the try, so a retry never makes a second one. Nothing is sent until the provider has your keys and a customer pays with it.

amountinteger
The transaction’s amount, in the currency’s smallest unit: cents, or whole yen.
currencystring
The transaction’s currency, in lower case: usd, eur, jpy…
descriptionstring
The order’s or invoice’s lines, as “Office Chair × 2, Desk Lamp”, cut at 250 characters.
detailsstring
What it pays and your company’s name: “Order S00042 at Example Furniture”, or “Invoice INV/2026/00017 at …”.
client_reference_idstring
The transaction’s reference: “S00042”, or “S00042-1” for the next try.
metadataobject
odoo_reference (the transaction’s reference), odoo_documents (the orders’ or invoices’ numbers), and odoo_site — a short hash of the database, so two Odoo databases on one project never act on each other’s events.
customer_emailstring
The customer’s email, where Orboni sends the receipt when your project sends receipts.
localestring
The customer’s language in Odoo, as en-US.
success_url, cancel_urlstring
The module’s return address, which reads the payment back, records it and sends the customer on to Odoo’s payment status page; the cancel link is the same address marked as left.

No address, phone number or other customer data is sent. The transaction keeps the session’s id as its Provider Reference, so a payment in the dashboard, an export or a webhook leads to its transaction by client_reference_id, and a transaction to its payment by the Provider Reference.

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