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
- 1From your Magento’s root, run
composer require orboni/module-payment, thenbin/magento module:enable Orboni_Paymentandbin/magento setup:upgrade; in production mode alsosetup:di:compileandsetup:static-content:deploy. Without Composer, unziporboni-module-payment-…zipfrom the newest release intoapp/code/Orboni/Payment/and run the same commands. - 2In Magento’s admin, open Stores → Configuration → Sales → Payment Methods, and there Orboni (crypto payments).
- 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. - 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 thecheckout.session.*ones, and paste its signing secret (whsec_…) into Webhook Signing Secret. - 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.
- 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.
| Payment | Orboni says | In Magento |
|---|---|---|
| Paid in full | complete, paid | Invoiced and Processing, with a comment naming the coin and the network; the order and invoice emails go out |
| On the chain, not final yet | processing | Payment Review; invoiced once final |
| Part paid | partially_paid | Payment Review, saying how much came; the payment page asks the customer for the rest |
| Held for your review | held | On Hold, giving the reason; accept it in the dashboard and the order is invoiced |
| Left by the page’s back link, nothing sent | open, unpaid | Canceled, and the customer gets their cart back; the page is closed at Orboni |
| Ran out with nothing paid | expired, unpaid | A comment; the order stays Pending Payment until Magento’s Pending Payment Order Lifetime cancels it |
| Ran out part paid | expired, partially_paid | On Hold, saying what arrived of what was due; settle the rest with the customer |
| Money that paid it left the chain | payment_reversed | On Hold until the dashboard shows it paid again |
| More came after it was paid | extra_received | A comment saying what came in all; send the extra back from your wallet if the customer asks |
| Paid after the order was canceled | held | A 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.