API reference

PrestaShop

The Orboni module adds crypto to PrestaShop’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 once a payment is seen PrestaShop makes the order and sends its emails, as with any other payment.

It is a module for PrestaShop 8 and 9, tested end to end on 8.2.9 with the Classic theme and 9.2.1 with Hummingbird. It is free, and its source is open, under the MIT license: orboni/prestashop-payment on GitHub.

Set it up

  1. 1Download orboni.zip from the newest release. In PrestaShop’s back office, open Modules → Module Manager → Upload a module and drop the zip there.
  2. 2Then Configure on Orboni crypto payments in the Module Manager.
  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 at the top of the module’s page, with every event, or at least the checkout.session.* ones, and paste its signing secret (whsec_…) into Webhook signing secret. Save.
  5. 5Have your server call the Cron address shown under it every 15 minutes, or add it to PrestaShop’s Cron tasks manager module: it reads back payments whose webhook did not arrive.
  6. 6Place an order with Crypto, and on its payment page, signed in to the dashboard, press Simulate payment: the order is made, Payment accepted. Then swap in your live key (sk_live_…) and the live endpoint’s secret. The key decides test or live at Orboni.

How orders move

Choosing Crypto and placing the order sends the customer to Orboni’s payment page for the cart’s total, and makes no order yet: the cart becomes an order once a payment is seen, so stock and the order emails wait for it, and a customer who leaves the payment page leaves no order behind. 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. What happened is told in a private message on the order, which the customer never sees.

PaymentOrboni saysIn PrestaShop
Paid in fullcomplete, paidThe order made as Payment accepted, the session’s id as its payment’s transaction, a message naming the coin and the network; the order confirmation and payment emails go out
On the chain, not final yetprocessingThe order made as Awaiting crypto confirmation, with its confirmation email; Payment accepted once final
Part paidpartially_paidThe order made as Crypto payment needs attention, saying how much came; the payment page asks the customer for the rest
Held for your reviewheldCrypto payment needs attention, giving the reason; accept it in the dashboard and the order is Payment accepted
Left by the page’s back link, nothing sentopen, unpaidNo order: the customer is back at the checkout, the cart still full, to pay another way
Ran out with nothing paidexpired, unpaidNo order; placing the cart again opens a new page
Ran out part paidexpired, partially_paidCrypto payment needs attention, saying what arrived of what was due; settle the rest with the customer
Paid for a cart changed after its page openedcomplete, paidCrypto payment needs attention, with what was paid and what the order totals; check it before sending
Money that paid it left the chainpayment_reversedCrypto payment needs attention until the dashboard shows it paid again
More came after it was paidextra_receivedA message saying what came in all; send the extra back from your wallet if the customer asks
A second page for the same cart paid toocomplete, paidA message on the order, which stays paid: send the second payment back from your wallet

The states for paid, awaiting confirmation and needs attention can be changed in the module’s settings; an order you marked shipped or delivered before its payment arrived keeps its state. Without a webhook a payment is still recorded once the customer comes back from the payment page, and the cron address reads back open pages whose webhook did not arrive; set up the webhook all the same. A shop in maintenance still takes Orboni’s webhooks.

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 cart’s total in it, and the customer pays its worth in the coin they pick. PrestaShop offers Crypto only when the cart’s currency is one of them, and Payment → Preferences decides, as for any payment module, which currencies, countries, groups and carriers offer it.
  • 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 stays at the checkout to choose another way to pay.
  • Going back to the payment page of the same cart gives the same page while it has more than five minutes left, never a second session.
  • Refunds: the money is in your wallet, so send it back from there, record the refund in the dashboard, and mark the order refunded in PrestaShop.
  • Several PrestaShop installations can share one Orboni project: each adds its own endpoint and acts only on its own carts.
  • The settings show the keys only by their last characters. Debug log writes each request and webhook to Advanced Parameters → Logs; errors are written either way, keys and secrets never.

What the module sends

Each cart makes a checkout session through POST /v1/checkout/sessions, with an idempotency key of the installation, the cart 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 cart’s total with shipping and taxes, in the currency’s smallest unit: cents, or whole yen.
currencystring
The cart’s currency, in lower case: usd, eur, jpy…
descriptionstring
The cart’s products, as “Mug × 2, Poster”, cut at 250 characters.
detailsstring
The cart’s number and your shop’s name: “Cart 42 at Example Shop”.
client_reference_idstring
The cart’s number: “42”. PrestaShop’s order page shows the cart it was made from.
metadataobject
prestashop_cart_id (the cart’s number) and prestashop_site — a random key of the installation, so two PrestaShop 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 customer’s language in your shop, as en-US.
success_url, cancel_urlstring
The module’s return address, with the cart and a key of its own, which reads the payment back and shows PrestaShop’s order confirmation; and the checkout, the cart still full.

No address, phone number or other customer data is sent. The order keeps the session’s id as its payment’s transaction, so a payment in the dashboard, an export or a webhook leads to its cart, and so 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/prestashop.md. Something missing or unclear? Write to us from the dashboard’s Help & Support.