Standalone Wero payments
This document is for an authorized external client charging a payment on its own — one
with no associated shop order and no logged-in shopper behind it. If you are instead paying
for a real shop order on behalf of a logged-in shopper, see
Wero payments in a customer context — that flow needs no special
permission and confirms through the order submit rather than through /api/wero/confirm1.
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.
Permission
Both endpoints require the session to be logged on as an API-role executor (see
api/logon4) that has additionally been granted the
API_WERO_ACCESS permission. This permission is per-tenant and not granted by
default — ask the tenant to grant it to your API account. Without it, both endpoints
return 401 not_auth.
The transaction flow
- Initiate with /api/client/wero/transaction1,
passing a
description(shown to the bank) and areturnPath— where the customer's browser should land after the bank redirect. It may be any absolute URI pointing anywhere: anhttps://URL, a plainhttp://one, or your app's own scheme (see Return destinations below). On success you get back aredirectUrl(the bank's landing page) and apaymentId. StorepaymentIdyourself — there is no session on this side to remember it for you. - 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. - Confirm with /api/wero/confirm1, passing the
paymentIdfrom step 1, to verify consent and trigger the capture.
| Result | Meaning |
|---|---|
response with captureId |
consent was successful, payment captured |
wero_denied |
consent was explicitly declined at the bank |
wero_pending |
consent hasn't completed yet — retry shortly |
wero_error |
consent could not be verified, or the payment could not be captured |
not_found (404) |
no payment exists for that paymentId |
Letting us finish the payment for you (autoConfirm)
The flow above needs the customer's browser to come back to you, and needs you to call
confirm1. Often neither happens. Wero's QR code is routinely scanned on a different device
than the one that started the checkout — for a till, kiosk or unattended terminal that's the normal
case, not an edge case — so there is no return redirect at all. The customer may also just close
the tab, or land on a deep link their phone has no app registered for.
Pass autoConfirm=1 to
/api/client/wero/transaction1 and we own that whole tail
instead:
- The return is always routed through us, whatever your
returnPathis. - We verify consent and capture the payment server-side — you never call
confirm1. - We write the terminal outcome into the
msgqueuetable, which you poll over SQL.
The outcome is written whether or not the customer ever comes back. If the return never arrives, a background sweep settles the payment and writes the same row within a few minutes.
Like werotest, this cannot be combined with a shop order — if a delivery date or order is
selected in your session, the call is refused with X-oekobox-error: ERROR. An order-attached
payment is captured by the checkout itself, so letting us own it too would put two writers on one
capture. Refused rather than ignored, so you never end up polling for a row nothing will write.
Polling for the outcome
One row per payment, at a predictable id you can compute from the paymentId you already stored:
SELECT msg FROM msgqueue WHERE id = CONCAT('wero:', ?);
Poll by id, not by topic. id carries the table's UNIQUE index; topic is unindexed, so
filtering on it scans a table the backend is also writing to.
msg is JSON:
{"paymentId":"65ba…","result":"captured","captureId":"7155…","amount":"29.75","currency":"EUR","test":true}
result |
Meaning | Paid? |
|---|---|---|
captured |
consent given, payment captured — captureId is present |
yes |
denied |
consent explicitly declined at the bank | no |
expired |
consent was checked and stayed pending until the deadline — the customer never completed it | no |
unverified |
we could never reach the bank to check consent at all (outage, credential problem) | unknown |
capture_unconfirmed |
consent succeeded, but we could not read the capture back before the deadline | probably yes |
The last two do not mean "not paid". A Wero payment authorizes and captures automatically the
moment the customer consents, so for unverified — and especially for capture_unconfirmed, where
we know consent succeeded — the money may well have moved and we simply lost sight of it. Treat
both as needs reconciliation, not as a failed payment. Only denied and expired are safe to
treat as unpaid.
A consentResult field (PENDING/SUCCESSFUL/FAILED) is included whenever the bank ever gave us
an answer, so you can see for yourself how far the payment got.
No row yet means "still in progress" — keep polling. There is deliberately never a pending
row: the id is unique, so a payment gets exactly one row ever, and it's always the final answer.
The three deadline outcomes above are what guarantee your poll terminates rather than running
forever on an abandoned payment.
returnPath still matters for where the customer ends up — it just no longer carries any
responsibility for confirming the payment.
Return destinations
returnPath can be any absolute URI, not just an https:// one:
returnPath |
Use case |
|---|---|
https://yourshop.example/done |
ordinary web checkout |
http://localhost:3000/return |
local development |
myapp://checkout/done |
native app deep link |
Wero itself only accepts an https:// return URL — its API rejects anything else outright. You
don't have to work around that: when your returnPath isn't https, we give the bank an https URL
on our own domain and redirect the customer on to your destination from there. The hop is
transparent, and weroReturn=1 still arrives on your URL exactly as described above.
Two things to know about it:
- The hop is visible in the browser's history and in any referrer, so don't rely on the customer arriving directly from the bank's domain.
javascript:,data:,vbscript:,file:,blob:andabout:are refused at initiation, withX-oekobox-error: ERRORand no payment created. These are script/local-resource schemes rather than navigation targets; nothing else is restricted, so an app scheme of your own choosing is fine.
If your destination is already https://, none of this applies — it's passed to the bank
unchanged, with no extra hop.
Testing against the sandbox
You can rehearse the whole flow without moving real money: pass werotest=1 to
/api/client/wero/transaction1. That one payment goes to
VR Payment's test environment instead of production.
POST /api/client/wero/transaction1?werotest=1&total=...&description=...&returnPath=...
- It applies to that transaction only — nothing else in your session changes, so the same session can create test and real payments side by side. Production is always what you get without the flag.
- Do not repeat it on
confirm1. ApaymentIdstays bound to the environment it was created in, so confirm (and any later refund) automatically goes to the right place. - It requires the same
API_WERO_ACCESSpermission as the endpoints themselves. Without that permission the parameter is silently ignored and you get an ordinary production payment — so check that you actually hold the permission rather than assuming test mode took effect. - It cannot be combined with a shop order. If a delivery date or order is selected in your session,
a
werotest=1call is refused withX-oekobox-error: ERROR— sandbox money may never pay for real goods. - Normally the tenant needs to configure nothing — test payments run against a shared sandbox
merchant id. (A tenant who holds their own Wero test contract can set
weroMerchantIdTestto have them booked against that instead.) Iftransaction1returnsX-oekobox-error: ERRORin test mode, the deployment has no sandbox merchant id at all — that's a server-side setting, so tell us rather than the tenant.
Check the X-oekobox-error header, not the status code. Apart from 401 not_auth, this
endpoint reports failures as HTTP 200 with that header set and an empty redirectUrl — the
409s in its generated reference describe intent, not what you'll actually observe.
- Test transactions are not hidden — they appear in the tenant's admin transaction list marked
TEST. - There is no real wallet app in the sandbox — you simulate the customer's consent instead of scanning anything. See below.
Giving or denying consent in the sandbox
Step 3 of the flow (the customer authorizing in their banking app) has no real counterpart in the sandbox. Use VR Payment's UAT consumer-PSP simulator instead:
https://example-consumer-psps.werouat.eu/wallets/44084ef4-ecd1-453f-869a-0158807c6424/payment-means/e7e6cbe6-e0a0-4198-b670-f5992280aa9a/consents/create
Open redirectUrl as usual and take the Wero short code from its "pay with a Wero code" panel,
then paste that code into the simulator's short id field. The page loads the transaction and
offers two buttons, which are how you drive both outcomes of step 4:
| Simulator action | What confirm1 then returns |
|---|---|
| Approve Consent | a captureId — consent successful, payment captured |
| Deny Consent | wero_denied |
| neither (yet) | wero_pending |
Enter the code with no separators. The landing page displays it grouped for readability
(e.g. 34D - FMPK - 6GR), but the lookup wants the raw alphanumeric string (34DFMPK6GR). You can
also append it straight to the URL — .../consents/create/34DFMPK6GR. With the dashes or spaces
left in, it fails with "consent for short id ... is not existing" even for a payment created
seconds earlier; that looks like a broken sandbox but is only the wrong id format. The code itself
is valid for 10 minutes.
Nothing needs to be told about the simulator — confirm1 verifies consent live against VR Payment,
so just call it once you've clicked Approve or Deny.
VR Payment can change this simulator's URL or flow without notice, and their docs also describe a pre-built "WERO HERO" test wallet we haven't used. If the URL above stops working, check VR Payment's own testing guide at wero.readme.io/docs/testing for the current documented flow before assuming the integration is at fault.
Things not to forget
- 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. - A payment is captured automatically the instant it's authorized — there's no separate "capture now" step to call.
weroReturn=1is only a resume marker. Always callconfirm1rather than trusting its mere presence.
Response types
- WeroAuthorize — returned by /api/client/wero/transaction1
- WeroConfirm — returned by /api/wero/confirm1