Drupal Commerce
The Commerce Orboni module adds crypto to Drupal Commerce’s checkout, with no code. The customer chooses Crypto at the payment step and 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 the payment is completed by itself once it is final.
It is an off-site payment gateway for Commerce 3 on Drupal 10.3 and 11, tested end to end on Drupal 11 with Commerce 3.3. It is free, and its source is open, under the GNU GPL (version 2 or later): commerce_orboni on drupal.org, with its releases and issue queue.
Set it up
composer require drupal/commerce_orboni
drush en commerce_orboni- 1Install it with Composer and switch it on with the two commands above. It needs Commerce’s Payment, Checkout and Log modules, which Composer and Drush bring with it.
- 2In the Orboni dashboard, set the wallets you want to be paid to under Wallets, and copy a secret key under Developers → API keys — a test key (
sk_test_…) first. - 3In Drupal, open Commerce → Configuration → Payment gateways → Add payment gateway, choose Orboni (crypto), paste the secret key and save.
- 4Open the gateway again: it shows its Webhook address. Under Developers → Webhooks, add an endpoint at it, with every event or at least the
checkout.session.*ones, and paste its signing secret (whsec_…) into Webhook signing secret. Save. - 5Make sure Drupal’s cron runs: it reads back payments whose webhook did not arrive, and voids those whose page ran out unpaid.
- 6Place an order with Crypto, and on its payment page, signed in to the dashboard, press Simulate payment: the order is placed and paid. Then swap in your live key (
sk_live_…) and the live endpoint’s secret. The key decides test or live at Orboni.
The keys are kept in the gateway’s configuration, like any Commerce gateway’s. If you deploy configuration through Git, keep them out of it with an override in settings.php, with the gateway’s machine name in place of orboni:
$config['commerce_payment.commerce_payment_gateway.orboni']['configuration']['secret_key'] = getenv('ORBONI_SECRET_KEY');
$config['commerce_payment.commerce_payment_gateway.orboni']['configuration']['webhook_secret'] = getenv('ORBONI_WEBHOOK_SECRET');How payments move
Each visit to the payment step makes a checkout session for the order’s balance and a Commerce payment for it in the New state, then sends the customer to its page. The module reads the session back from Orboni before it changes anything, and the payment follows it as it is now — whether the webhook, the customer’s return or cron comes first, twice or out of order. Each change is a line in the order’s activity, with the coin and the network a payment came in.
| Payment | Orboni says | In Drupal Commerce |
|---|---|---|
| Paid in full | complete, paid | Completed, counted in the order’s total paid; the order is placed, and a cart left at the payment step is placed paid |
| On the chain, not final yet | processing | Pending; the customer’s return places the order, and the payment is completed once final |
| Part paid | partially_paid | Pending, saying how much came; the payment page asks the customer for the rest |
| Held for your review | held | Pending, giving the reason; accept it in the dashboard and the payment is completed |
| Left by the page’s back link, nothing sent | open, unpaid | Still New: the customer is back at checkout to pay another way; returning to the page leads back to it |
| Ran out with nothing paid | expired, unpaid | Voided, saying why; a cart left at the payment step is unlocked to pay again |
| Paid for an order changed after its page opened | complete, paid | Completed, with a line saying what is still due; check it before shipping |
| Money that paid it left the chain | payment_reversed | Back to Pending and off the order’s total paid, told not to ship until the dashboard shows it paid again |
| More came after it was paid | extra_received | A line saying what came in all; send the extra back from your wallet if the customer asks |
Without a webhook a payment is still read back when the customer comes back from the payment page, and by cron afterwards; set up the webhook all the same.
Good to know
- The currency: the order’s — US dollars, euros, pounds, yen or any other currency a checkout session takes (Currencies in the API reference). The payment page shows the order’s balance in it, and the customer pays its worth in the coin they pick. Crypto is offered only when the order’s currency is one of them.
- The least is worth $1.00. In dollars Crypto is not offered below it; in another currency the customer is told the order is below the minimum and is back at checkout to choose another way to pay.
- Going back to the payment step for the same balance reuses the open page while it has more than five minutes left; after that, or for another balance, it makes a new one.
- Refunds: the money is in your wallet, so send it back from there and record the refund in the dashboard.
- Several Drupal sites can share one Orboni project: each adds its own endpoint and acts only on its own orders.
- What could not be done — a session that could not be read back, a payment reversed or paid twice — is written to Drupal’s log under commerce_orboni (Reports → Recent log messages); keys and secrets never.
What the module sends
Each payment page is a checkout session made through POST /v1/checkout/sessions, with an idempotency key of the site, the order, its balance and the try, so a retry never makes a second one. Nothing is sent until the gateway has your key and a customer pays with it.
- amountinteger
- The order’s balance, in the currency’s smallest unit: cents, or whole yen.
- currencystring
- The order’s currency, in lower case: usd, eur, jpy…
- descriptionstring
- The order’s products, as “Mug × 2, Poster”, cut at 250 characters.
- detailsstring
- The order number and your store’s name: “Order 42 at Example Store”.
- client_reference_idstring
- Commerce’s id of the order: “42”.
- metadataobject
- commerce_order_id, commerce_payment_gateway and commerce_site — a key made from your Drupal site’s hash salt, so two sites on one project never act on each other’s events.
- customer_emailstring
- The order’s email, where Orboni sends the receipt when your project sends receipts.
- localestring
- The customer’s language on your site, as en.
- success_url, cancel_urlstring
- Commerce’s own return and cancel addresses for the order’s payment step.
No address, phone number or other customer data is sent. A payment in the dashboard, an export or a webhook leads to its order by client_reference_id, and an order to its payment by the session id, the payment’s remote id in Commerce.
This page as Markdown, for a program or an AI assistant: /docs/drupal-commerce.md. Something missing or unclear? Write to us from the dashboard’s Help & Support.