API reference

OpenCart

The Orboni extension adds crypto to your OpenCart checkout, with no code. The customer chooses crypto, confirms the order, 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 the order is confirmed by itself once the payment is final on the chain.

There is a package for each OpenCart: orboni.ocmod.zip for OpenCart 4.0.2.0 or later (PHP 8.0 or later), and orboni-oc3.ocmod.zip for OpenCart 3.0.3.0 or later (PHP 7.1 or later). They work the same way; the few places where they differ are said below.

Set it up

  1. 1Download the package for your OpenCart from the extension’s page in the OpenCart Marketplace. In your admin, open Extensions → Installer and upload it.
  2. 2Open Extensions → Extensions, choose Payments, install Orboni (crypto), then edit 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 extension’s Secret key.
  4. 4Under Developers → Webhooks, add an endpoint at the Webhook address shown on the extension’s settings page, with every event, or at least the checkout.session.* ones. Paste its signing secret (whsec_…) into Webhook signing secret, set Status on and save.
  5. 5Keep a cron running, for payments whose webhook was lost. OpenCart 4: the extension adds an hourly task to OpenCart’s own cron, which runs when your server calls index.php?route=cron/cron. OpenCart 3 has no cron of its own: have your server call the Cron address shown on the settings page every 10 to 15 minutes.
  6. 6Place an order and pay with crypto, and on the payment page, signed in to the dashboard, press Simulate payment: the order turns Processing. Then swap in your live key and the live endpoint’s secret. The key decides test or live; with a test key the checkout says no real money is taken.

How orders move

The extension 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. Until a payment is seen the order is one of OpenCart’s missing orders, so no stock is taken and no order email is sent for a checkout that was never paid. Each change is a line in the order’s history.

PaymentOrboni saysIn OpenCart
Paid in fullcomplete, paidThe Paid status (Processing unless you pick another); the customer is emailed
On the chain, not final yetprocessingThe Awaiting confirmation status (Pending): the order is placed and the customer told the payment is on its way; it turns Paid by itself once final
Part paidpartially_paidThe Needs your attention status (Pending), with a note of how much came; the payment page asks the customer for the rest
Held for your reviewheldNeeds your attention, with the reason; accept it in the dashboard and the order turns Paid
Ran out with nothing paidexpired, unpaidNothing: the order stays a missing order
Ran out part paidexpired, partially_paidNeeds your attention, with what arrived: settle it with the customer
Money that paid it left the chainpayment_reversedNeeds your attention, with a note; it turns Paid again if the payment completes again
More came after it was paidextra_receivedA note in the history; the status stays

You choose the three statuses on the settings page. A paid order is never taken back by anything else, and an order you already set to one of your store’s complete statuses by hand keeps its status. Without a webhook the order still moves once the customer comes back from the payment page, and a payment still on its way then is read again by the cron. Errors go to orboni.log in OpenCart’s logs folder, and every request and webhook too with Debug log on.

Good to know

  • The customer’s 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, at your store’s own exchange rate, and the customer pays its worth in the coin they pick. Crypto is not offered in a currency Orboni does not take; the settings page warns when your default currency is one.
  • The least is worth $1.00. Crypto is not offered for a smaller dollar order; in another currency the button says the order is below the minimum.
  • A customer who presses the button again gets the same payment page while it has more than five minutes left, never a second session for the same order and amount.
  • An order whose total grew after its payment page opened is not marked paid: it gets Needs your attention, with both amounts. An order paid twice keeps its status, with a note of the second payment: send that back from your wallet.
  • Subscriptions (recurring products in OpenCart 3) are not offered: crypto is hidden while one is in the cart.
  • A title for the checkout in each of your languages, and a geo zone to offer it in, are on the settings page.
  • Refunds: the money is in your wallet, so send it back from there and record the refund in the dashboard.
  • Several OpenCart stores can share one Orboni project: each adds its own endpoint and acts only on its own orders.
  • The extension never logs the key or the signing secret.

What the extension sends

Each order makes a checkout session through POST /v1/checkout/sessions, with an idempotency key of the store, the order, the amount and its currency, and the try, so a retry never makes a second one.

amountinteger
The order’s total, in the currency’s smallest unit: cents, or whole yen.
currencystring
The customer’s currency, in lower case: usd, eur, jpy…
descriptionstring
The order’s products, as “T-shirt × 2, Mug”, cut at 250 characters.
detailsstring
The order’s number and your store’s name: “Order 1042 at Pixel Shop”.
client_reference_idstring
The OpenCart order’s id.
metadataobject
opencart_order_id, and opencart_site — a short hash of the store’s address, so two stores 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’s language the customer sees: en-GB, de-DE…
success_url, cancel_urlstring
The extension’s return page, which reads the payment and goes on to OpenCart’s success page; and the checkout, its cart still full.

The order’s history names the session, so a payment in the dashboard, an export or a webhook leads to its order by client_reference_id, and the order to its payment by the session’s id.

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