Wero payments in a customer context
This document is for a client driving the checkout of a logged-in shopper with a real shop order behind it — a partner running their own frontend on top of this platform's customer API. If you instead want to charge a payment with no order and no shopper (using the platform purely as a payment rail), see standalone Wero payments — that is a different flow with a different permission and a different final call.
Wero is a pan-European instant payment scheme. Paying with Wero means the customer scans a QR code (or otherwise authorizes) with their own banking/Wero app — there is no JavaScript SDK or in-page overlay. Consent is a genuine full-page browser redirect to the bank and back. Only EUR is supported today.
See use the API for how to authenticate.
The standard shop's own cart already implements everything below. You only need this if you are building your own shop & checkout in place of it.
Prerequisites
- A session logged on as the shopper (see api/logon4). No special permission is needed — unlike the standalone flow, this is an ordinary customer action.
- The tenant has a Wero merchant id configured, so Wero is offered at all. Paycode
7(WERO) appears in the customer's allowed paycodes when it is.
The transaction flow
The shape to internalize: you never confirm the payment yourself. Consent verification and capture happen inside the order-store call, as a pre-flight gate. There is deliberately no "check my consent" round trip — you simply resubmit the order and the backend decides.
- Mark the order as
used_paycode = 7(WERO). - Initiate with /api/client/wero/transaction1,
passing the cart totals (
total,vatsum,shipping,count, andrelvoucheridif a relative voucher is in the cart) and areturnPath. On success you get back aredirectUrl(the bank's landing page) and apaymentId. ThepaymentIdis tracked on your session for you — you do not need to store it, and there is nothing to pass it to. Thedescriptionparameter is ignored here: an order-attached payment is always labelledOrder <oid>to the bank. - Redirect the customer's browser to
redirectUrlwith a top-level navigation (window.top.location.href = redirectUrl), not an iframe or popup — the bank page won't work embedded. - The customer authorizes on their bank/Wero app. The bank then redirects the browser
back to your
returnPath, withweroReturn=1appended to the query string. Its presence just means "resume here" — it is not itself proof that consent was given. - Resubmit the order to /api/client/neworder8 (or
/api/client/changeorder8 for a change to an existing
order), with
used_paycode = 7re-applied. Before writing anything, the backend verifies consent live against the bank and refuses to store the order unless it is successful; once stored, it reads back the authorization and capture the bank created automatically.
| Result | Meaning |
|---|---|
| normal order response | consent was successful, order stored, payment captured |
wero_denied |
consent was explicitly declined at the bank — nothing was stored |
wero_pending |
consent hasn't completed yet — nothing was stored, may resolve shortly |
wero_error |
consent could not be verified — nothing was stored |
These three are returned by the order endpoints, not by transaction1. On any of them the
order does not exist; you can start over from step 1 with a fresh payment.
What returnPath may be
Unlike the standalone flow, an ordinary customer session may not pass a full absolute
URI — that would make this an open redirect, so it is only honoured for a caller holding
API_WERO_ACCESS. Pass a path, in one of two shapes:
- Absolute, domain-root-relative path, with a leading slash (e.g.
/?p=cart) — resolved against your shop's own domain. This is the shape to use when your shop runs under your own domain or a friendly URL, so it is the one you almost certainly want; send the real current location (window.top.location.pathname + search) rather than a hardcoded path. If the domain the bank should return to differs from the shop's configured home address, the tenant can set a dedicated Wero return domain in the shop settings. - Relative path, no leading slash — resolved relative to the shop's own base address, app path included. Only useful for a page served from within the shop itself.
Either way the destination must be a real, renderable page — the bank performs a genuine browser navigation to it, so a bare JSON endpoint will not do.
Things not to forget
- Don't call
/api/wero/confirm1. That endpoint is for the orderless flow only. Resubmitting the order is the confirmation step here. - Your session must survive the redirect. The pending payment is tied to the session
that started it. If the customer comes back from the bank without it — a dropped cookie,
a different browser — the resubmit fails with
wero_errorrather than storing an order that was never paid for. Start over from step 1 in that case. - Force the resubmit through, even if nothing changed. The customer typically touches
nothing across the redirect — only
used_paycodechanged. Any "cart unmodified, skip the submit" guard on your side will silently drop the submit, and the payment then never gets captured at all. - Strip
weroReturn=1from the URL as soon as you act on it. If it survives in history, a later remount of that entry re-runs the resume against an already-consumed payment and reports a spurious failure right after a successful order. - The captured amount may exceed the cart total. A tenant can configure a payment surcharge, in which case the amount taken is raised accordingly and reconciled back down by a refund once the final order total is known. Don't assert that the captured amount equals the order total.
- No overlay/iframe. The consent page is a real bank site; embedding it defeats browser security checks banks rely on and will typically just fail to load.
- EUR only. There's currently no way to initiate a Wero payment in another currency.
- Amounts must be exact to the cent. Send plain two-decimal values (e.g.
12.34, not something that only rounds to it) — the bank API validates amounts strictly.
Response types
- WeroAuthorize — returned by /api/client/wero/transaction1
- ChangeOrderResult — returned by /api/client/neworder8 / /api/client/changeorder8