API reference

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
  1. 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.
  2. 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.
  3. 3In Drupal, open Commerce → Configuration → Payment gateways → Add payment gateway, choose Orboni (crypto), paste the secret key and save.
  4. 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.
  5. 5Make sure Drupal’s cron runs: it reads back payments whose webhook did not arrive, and voids those whose page ran out unpaid.
  6. 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.

PaymentOrboni saysIn Drupal Commerce
Paid in fullcomplete, paidCompleted, 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 yetprocessingPending; the customer’s return places the order, and the payment is completed 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 the payment is completed
Left by the page’s back link, nothing sentopen, unpaidStill New: the customer is back at checkout to pay another way; returning to the page leads back to it
Ran out with nothing paidexpired, unpaidVoided, saying why; a cart left at the payment step is unlocked to pay again
Paid for an order changed after its page openedcomplete, paidCompleted, with a line saying what is still due; check it before shipping
Money that paid it left the chainpayment_reversedBack 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 paidextra_receivedA 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.