# OpenCart

Part of the Orboni API reference: https://orboni.com/docs. This page: https://orboni.com/docs/opencart.

The Orboni extension (https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=50540) 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. Download the package for your OpenCart from the extension’s page in the OpenCart Marketplace (https://www.opencart.com/index.php?route=marketplace/extension/info&extension_id=50540). In your admin, open Extensions → Installer and upload it.
2. Open Extensions → Extensions, choose **Payments**, install **Orboni (crypto)**, then edit it.
3. In 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. Under 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. Keep 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. Place 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.

| Payment | Orboni says | In OpenCart |
| --- | --- | --- |
| Paid in full | `complete, paid` | The Paid status (Processing unless you pick another); the customer is emailed |
| On the chain, not final yet | `processing` | The 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 paid | `partially_paid` | The Needs your attention status (Pending), with a note of how much came; the payment page asks the customer for the rest |
| Held for your review | `held` | Needs your attention, with the reason; accept it in the dashboard and the order turns Paid |
| Ran out with nothing paid | `expired, unpaid` | Nothing: the order stays a missing order |
| Ran out part paid | `expired, partially_paid` | Needs your attention, with what arrived: settle it with the customer |
| Money that paid it left the chain | `payment_reversed` | Needs your attention, with a note; it turns Paid again if the payment completes again |
| More came after it was paid | `extra_received` | A 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: https://orboni.com/docs#currencies). 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.

| Parameter | Type | What |
| --- | --- | --- |
| `amount` | integer | The order’s total, in the currency’s smallest unit: cents, or whole yen. |
| `currency` | string | The customer’s currency, in lower case: usd, eur, jpy… |
| `description` | string | The order’s products, as “T-shirt × 2, Mug”, cut at 250 characters. |
| `details` | string | The order’s number and your store’s name: “Order 1042 at Pixel Shop”. |
| `client_reference_id` | string | The OpenCart order’s id. |
| `metadata` | object | 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_email` | string | The customer’s email, where Orboni sends the receipt when your project sends receipts. |
| `locale` | string | The store’s language the customer sees: en-GB, de-DE… |
| `success_url, cancel_url` | string | 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.
