← API Index

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

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.

  1. Mark the order as used_paycode = 7 (WERO).
  2. Initiate with /api/client/wero/transaction1, passing the cart totals (total, vatsum, shipping, count, and relvoucherid if a relative voucher is in the cart) and a returnPath. On success you get back a redirectUrl (the bank's landing page) and a paymentId. The paymentId is tracked on your session for you — you do not need to store it, and there is nothing to pass it to. The description parameter is ignored here: an order-attached payment is always labelled Order <oid> to the bank.
  3. 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.
  4. 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.
  5. Resubmit the order to /api/client/neworder8 (or /api/client/changeorder8 for a change to an existing order), with used_paycode = 7 re-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:

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

Response types