API reference

Magento 2

The Orboni module adds crypto to Magento’s checkout, with no code. The customer chooses Crypto at the payment step, places the order 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 once the payment is final on the chain Magento invoices the order and sends its emails, as with any other payment.

It is a module, Orboni_Payment, for Magento Open Source and Adobe Commerce 2.4.7 and later, tested end to end on 2.4.7, 2.4.8 and 2.4.9. It is free, installed with Composer from Packagist as orboni/module-payment. Its source is open, under the MIT license: orboni/magento2-payment on GitHub.

Set it up

  1. 1From your Magento’s root, run composer require orboni/module-payment, then bin/magento module:enable Orboni_Payment and bin/magento setup:upgrade; in production mode also setup:di:compile and setup:static-content:deploy. Without Composer, unzip orboni-module-payment-…zip from the newest release into app/code/Orboni/Payment/ and run the same commands.
  2. 2In Magento’s admin, open Stores → Configuration → Sales → Payment Methods, and there Orboni (crypto payments).
  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 Secret Key.
  4. 4Under Developers → Webhooks, add an endpoint at the Webhook Address shown under it (https://your-store.com/orboni/webhook), with every event, or at least the checkout.session.* ones, and paste its signing secret (whsec_…) into Webhook Signing Secret.
  5. 5Set Enabled to Yes and save. Place an order with Crypto, and on its payment page, signed in to the dashboard, press Simulate payment: the order is invoiced and moves to Processing.
  6. 6Then swap in your live key (sk_live_…) and the live endpoint’s secret. The key decides test or live at Orboni, and each website can have its own.

How orders move

Placing an order with Crypto leaves it Pending Payment, without its confirmation email, and sends the customer to its payment page. The module reads the payment back from Orboni before it changes anything, and the order follows the payment as it is now — whether the webhook, the customer’s return or the cron comes first, twice or out of order. Each change is a comment in the order’s history.

PaymentOrboni saysIn Magento
Paid in fullcomplete, paidInvoiced and Processing, with a comment naming the coin and the network; the order and invoice emails go out
On the chain, not final yetprocessingPayment Review; invoiced once final
Part paidpartially_paidPayment Review, saying how much came; the payment page asks the customer for the rest
Held for your reviewheldOn Hold, giving the reason; accept it in the dashboard and the order is invoiced
Left by the page’s back link, nothing sentopen, unpaidCanceled, and the customer gets their cart back; the page is closed at Orboni
Ran out with nothing paidexpired, unpaidA comment; the order stays Pending Payment until Magento’s Pending Payment Order Lifetime cancels it
Ran out part paidexpired, partially_paidOn Hold, saying what arrived of what was due; settle the rest with the customer
Money that paid it left the chainpayment_reversedOn Hold until the dashboard shows it paid again
More came after it was paidextra_receivedA comment saying what came in all; send the extra back from your wallet if the customer asks
Paid after the order was canceledheldA comment on the canceled order; the money is held for your review in the dashboard: send it back from your wallet, or place a new order for the customer

Without a webhook a payment is still recorded once the customer comes back from the payment page, and every 15 minutes Magento’s cron reads back open orders whose webhook did not arrive; set up the webhook all the same, and keep the cron running. A payment that arrives after its page ran out, while the order is still Pending Payment, still pays it. Canceling an order in the admin closes its payment page, and money sent to it later is held for your review in the dashboard.

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 order’s total in it, and the customer pays its worth in the coin they pick. Magento offers Crypto 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, the order is canceled and the cart comes back.
  • Going back to the payment page of the same order gives the same page while it has more than five minutes left, never a second session.
  • One-time payments only: not for orders created in the admin, for checkout with multiple addresses, or for subscriptions.
  • Refunds: the money is in your wallet, so send it back from there, record the refund in the dashboard, and make an offline credit memo in Magento.
  • Several Magento installations can share one Orboni project: each adds its own endpoint and acts only on its own orders.
  • The keys are stored encrypted and shown masked. Debug Log writes each request and webhook to var/log/orboni.log; errors are written either way, keys and secrets never.

What the module sends

Each order makes a checkout session through POST /v1/checkout/sessions, with an idempotency key of the installation, the order and its amount, and the try, so a retry never makes a second one. Nothing is sent until the module has your keys and a customer pays with it.

amountinteger
The order’s grand total, 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 items, as “Office Chair × 2, Desk Lamp”, cut at 250 characters.
detailsstring
The order’s number and your store’s name: “Order 000000042 at Example Furniture”.
client_reference_idstring
The order’s number: “000000042”.
metadataobject
magento_order (the order’s number), magento_order_id (its id), and magento_site — a short hash of the installation, so two Magento installations 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 store view’s language, as en-US.
success_url, cancel_urlstring
The module’s return addresses, with the order and a key of its own: the first reads the payment back and shows Magento’s order success page, the second cancels the unpaid order and gives the cart back.

No address, phone number or other customer data is sent. The order keeps the session’s id as its payment transaction and shows it with the payment method in the admin, so 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.

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