← API Index

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

  1. Initiate with /api/client/wero/transaction1, passing a description (shown to the bank) and a returnPath — where the customer's browser should land after the bank redirect. It may be any absolute URI pointing anywhere: an https:// URL, a plain http:// one, or your app's own scheme (see Return destinations below). On success you get back a redirectUrl (the bank's landing page) and a paymentId. Store paymentId yourself — there is no session on this side to remember it for you.
  2. Redirect the customer's browser to redirectUrl with a top-level navigation (window.top.location.href = redirectUrl), not an iframe or popup — the bank page won't work embedded.
  3. The customer authorizes on their bank/Wero app. The bank then redirects the browser back to your returnPath, with weroReturn=1 appended to the query string. Its presence just means "resume here" — it is not itself proof that consent was given.
  4. Confirm with /api/wero/confirm1, passing the paymentId from 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:

  1. The return is always routed through us, whatever your returnPath is.
  2. We verify consent and capture the payment server-side — you never call confirm1.
  3. We write the terminal outcome into the msgqueue table, 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:

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=...

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.

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

Response types