Payments
Ten drivers ship in the box, and all but one arrive disabled. That is not an oversight: an enabled acquirer holding somebody else's keys sends money to somebody else's account. Enable the one you have a contract for.
How a payment method is put together
A payment method is a row in pb_shop_methods, and a driver is optional.
| Column | What it is for |
|---|---|
key | the identifier, lowercase. It is part of the callback URL |
name, description, logo | what the buyer sees |
driver | which gateway serves it. Empty means offline |
currencies | a JSON list of codes. Empty means "any currency" |
properties | the gateway keys and options — the form below |
published_at | an unpublished method is not offered to anyone |
A method without a driver is an offline one: the order waits in pending and the manager confirms the money arrived in the payments grid. A fresh install ships exactly one method enabled, manual ("Cash on delivery"), so an order goes through end to end before you have any contract at all.
The manager tells you when a method is misconfigured
A banner sits on all four pages of the shop section. It is yellow while no method is enabled, and red when an enabled method is missing its settings — a state that is otherwise invisible, because the buyer is deliberately not shown the gateway's own complaint.
Completeness is asked of the driver itself; there is no list of required fields in the core. The banner is not in the methods grid on purpose: that grid is the first tab of the fourth page, and after installing you land on "Orders".
The drivers and their fields
The field names below are literally what you fill in on the method's Properties; the install seed puts the empty skeleton there, so you can see that LiqPay wants a public_key and maib wants a signature_key without reading a readme. Bold fields are the ones the driver refuses to work without.
| Key | Gateway | Fields |
|---|---|---|
manual | Offline | none at all |
bill | Invoice, PDF | seller (per currency: name, reg_number, address, bank_name, bank_account), template |
liqpay | LiqPay / PrivatBank | public_key, private_key, language |
wayforpay | WayForPay | merchant_account, secret_key, domain, language |
fondy | Fondy | merchant_id, password, lang |
monobank | Monobank | token, test_token, validity |
portmone | Portmone | payee_id, login, key, password, lang |
maib | maib | project_id, project_secret, signature_key, biller_expiry, language |
stripe | Stripe | secret_key, webhook_secret, test_secret_key, test_webhook_secret, locale |
paypal | PayPal | client_id, client_secret, webhook_id, test_client_id, test_client_secret, test_webhook_id, brand_name, locale |
Three of these deserve a line of their own, because they will refuse in a way that looks like something else:
- WayForPay —
domainmust match the site's domain. It takes part in the signature, so a mismatch is not a cosmetic problem. - Portmone — needs
passwordas well as the signaturekey. Its notification is unsigned, so the driver re-asks the gateway for the verdict, and that query needs the password. - PayPal —
webhook_idis required in practice: without it the notification's signature cannot be checked at all.
Looking for YooKassa, T‑Bank, CloudPayments, YooMoney or PayAnyWay? They are in the free pbShopPay package — why is explained here.
The callback URL
One shape for every driver, with the method's key in it:
https://your-site/pay/{key}/resultSo /pay/maib/result, /pay/stripe/result, /pay/monobank/result. That is the address you paste into the gateway's dashboard. Two gateways want you to also pick the events:
- Stripe —
checkout.session.completed,.async_payment_succeeded,.async_payment_failedand.expired; - PayPal —
CHECKOUT.ORDER.APPROVEDandPAYMENT.CAPTURE.*.
Where the buyer comes back to is separate and is yours: pbshop_return_url (/ by default), plus pbshop_return_url_fail and pbshop_return_url_pending — empty means "use the first one".
The callback route carries no CSRF token and no captcha
It cannot: a payment system sends neither. The framework hangs both on every POST outside the manager, and this one route takes them off. That is why verification matters so much — see below.
The register's own callback, if you use one, is /pay/fiscal/{driver}/result.
Nobody trusts the callback
Two layers, and they are not redundant.
The driver verifies its own callback. Each one differently, because each gateway does it differently:
| Driver | How it is verified |
|---|---|
liqpay | base64(sha1(private + data + private)) |
wayforpay | HMAC‑MD5 over values joined in a documented order |
fondy | SHA‑1 over non-empty params, sorted |
monobank | ECDSA‑SHA256; the public key is fetched from the gateway and re-read when it rotates |
portmone | nothing is signed — the state is re-read through the API |
maib | SHA‑256 over amount, currency, status and order id |
stripe | HMAC‑SHA256 over timestamp.raw_body; several signatures may be present after a secret rotation |
paypal | PayPal verifies it itself, on a return request |
The service checks the amount on top of that, and never takes the amount from the callback on trust.
Verifying does not have to mean a signature. Where a notification is unsigned — Portmone — the verdict comes from reading the payment back out of the API. A driver that could not ask answers defer(): the payment row is left untouched and the gateway is asked to repeat the notification, rather than a guess being written down.
Drivers also defer when a notification is simply not theirs to act on — an event type they do not handle, a session belonging to another system, the echo of a refund they started themselves.
Two gateways break the assumption that "the buyer came back" means paid
Stripe — a completed Checkout Session does not mean the money arrived; their own documentation says processing may still be in progress, and with deferred methods days pass between the two events. Payment is confirmed by a separate field.
PayPal — payment happens in two steps. The buyer only approves; the money is taken by a capture call the shop has to make. This is the one driver that does not parse a notification so much as act on it.
If you are writing your own frontend against these two, do not treat the return redirect as confirmation.
Test mode
One global switch, pbshop_test_mode, on by default, and any method can override it with a test_mode of its own in properties.
What the switch does depends on the gateway, and the difference is worth knowing before you wonder why a live key is taking test money:
liqpay— sends asandboxflag with the same keys;monobank,stripe,paypal— use separate test credentials (test_token,test_secret_key,test_client_idand friends);wayforpay,fondy,portmone,maib— have no test switch of their own; the sandbox is arranged in the gateway's dashboard with the keys it gives you.
The cash register has its own switch, pbshop_fiscal_test_mode, and not this one: a register's test circuit is a different server under a different contract, and a shop with the gateway in sandbox and the register live is an ordinary state while debugging.
Refunds
Every driver with a gateway behind it can refund, in full or in part, from the payment window in the manager. Leave the amount empty for a full refund.
manual and bill cannot: there is no gateway to ask, and the money went back by whatever route it came.
A refund deliberately does not return the stock
The argument is in the code, and it is a decision rather than a debt: goods come back to stock by a change of order status, and doing it by two routes means returning the same item twice one day. One road, on purpose.
When it fails before the gateway
The buyer gets a translated line — "this payment method is unavailable, please choose another". The driver's own detail goes into the payment's properties.error and into the MODX log, not onto the checkout page: a buyer has no business reading the English names of a method's properties, which is what used to happen.
The gateway's own refusal — "card declined" — is a different thing. It arrives by callback and is not an error on the shop's side.
Paying an abandoned order again
POST /pay/orders/{uuid}/pay — a button and a method picker on the order page. The payment is new, because a gateway link is single-use; the order is the same one, and its totals are a snapshot, so the reservation and the promo code are not recalculated. The reservation is taken again first: an abandoned order loses it after an hour, and goods that ran out refuse before money is taken rather than after.
The gateway is sent the payment's uuid, not the order number, so a second attempt is a different order to it and there is no "this order_id was already processed" refusal.
The method list is filtered by the same rule the route uses to accept the choice, so an invoice is not offered on an order with no requisites. If the filter removes every method, the page says why instead of showing an empty list.
Events
pbShopPaymentCreate pbShopPaymentSuccess pbShopPaymentFail pbShopPaymentRefundEverything that ends in money arriving goes through one road — pbShopPaymentSuccess → the order is paid → the receipt, the mail, the stock and the history feed follow from there. A gateway callback, a recurring charge, a manager confirming an offline payment and a carrier transferring a cash-on-delivery amount all converge on it. That is deliberate: a second road to "paid" would mean one of those four one day arrives without a receipt.
Next
- Receipts — when the shop issues one and when the gateway does
- Subscriptions and cron — the five drivers that can charge again
- Currencies — which methods a buyer is offered and why