Frequently Asked Questions

What is wero?

Wero is a real-time, QR-based European payment method built on SEPA Instant A2A transfers. Created by EPI and launched in 2024, it allows users in multiple EU countries to send and request payments in under 10 seconds without using IBANs. Designed for merchant integration, it enables fast, secure, and seamless online and upcoming in-store payments across participating European markets.

---

Registration

How and where can I sign a contract with wero?

If you want to integrate wero into your shop you need an legal agreement for accepting wero. The contract can be signed through your cooperative bank or via the VR Payment Sales Team.

What credentials are required to authenticate a payment for Wero?

• clientId
• client secret
• API credentials

All needed credentials will be provided after contract signment completion.

---

Implementation

How is the data flow?

App/Shop <-> Merchant Server <-> VR Payment <-> EPI

Is IP whitelisting possible?

Yes, it is possible to whitelist IPs.

How long is a Access Token (bearer) valid?

300 seconds.

What is the difference between Single Immediate Payment and Event Dependent Payment?

A Single Immediate Payment is executed right after the customer authorizes it. The funds are captured immediately, making it ideal for one-time purchases, digital goods, or instant donations.

An Event Dependent Payment, on the other hand, is created up front but only executed once a specific business event occurs (for example, shipment confirmation, service start, or a pre-order release). Until then, the payment remains pending, and if the event does not happen within the defined timeframe, it expires automatically.

Which status responses are available in status queries?

pending, successful, failed

Why are there different types of status queries?

Different flows in the payment process (payment, consent, capture, refund) have their own lifecycle. The API provides dedicated status queries for each part of the payment flow.

Each payment flow can be created, updated or fail independently of the others and depending on the payment plan. Using different status endpoints ensures that complex flows like event Event Dependent Payments, partial captures or multiple refunds remain traceable.

Example: Consent was given, but the payment linked to it might later fail when the payer's bank rejects the authorization.

When should each status be queried?

The timing depends on the type of transaction.

In addition:

• after 10 minutes (session time out)
• with the returnURL

How long are payment request and consent request valid?

10 minutes (session time out). After the time out the payment expires and the consent can no longer be confirmed by the payer.

Are the access credentials identical for the test system and the live system?

No. Test and live environments use separate credentials. Merchants receive dedicated access data for the sandbox (test system) and for the production (live system) environment to ensure separation of test transactions and real payments.

Which endpoints are available?

For an overview please check the API reference

For a detailed overview for Single Immediate Payment check Payment Plan Types - Single Immediate.

For a detailed overview for Event Dependent Payment check Payment Plan Types - Event Dependent.

Which customer-specific data must the merchant provide at least?

• billing address

The shipping address is conditional, meaning in general it is not mandatory to provide the shipping address, but if provided, all required data fields for shipping address must be send.

Annotation: The information must be requested from the customer and included in the consent request.

When is the customer redirected to the returnURL?

The customer is redirected to the returnURL once the payment flow has been completed. This happens:

• when the customer declines the consent
• when the payment session times out
• after the customer has finished the interaction with their bank or wallet (authorization).

The redirect ensures that the merchant’s system can resume the checkout process and display the final result to the customer.

---

Event Dependent

How does a merchant know until when he must capture an Event Dependent Transaction?

The merchant can check the timeframe by using the GET STATUS for authorization ("createdAt":YYYY-MM-DDThh:mm:ss.sssZ"). Based on this value, the number of seconds must then be added (maximum 864.000 if requested in the consent/payment request; otherwise 604800).

Please note: the time reference is UTC.

---

Consent

What happens when the customer actively declines the consent?

The consent status result changes to failed. Due to the declined consent, the payment authorization request is not initiated and the customer will be redirected to the returnURL.

What happens when the consent is not provided (no customer interaction)?

The general timeframe for a wero payment session is 10 minutes. If the consent is not granted by the customer within the given time, the session times out and the payment status changes to failed.

What happens when the consent process is aborted midway?

The payment consent fails.

What happens after the consent request timed out?

The customer will be redirected to the returnURL.

Is a renewed payment attempt possible after a consent timed out?

No. When the consent timed out, the payment status is failed and a renewed payment authorization is not possible. For a renewed payment to be initiated a new payment request and payment consent is needed.

What happens when the consent was given, but the money transfer failed?

A money transfer for Single Immediate Payments is only possible when consent is given and the authorization was also successful. If one or both states are unsuccessful the payment gets the status failed. The customer will be redirected to the returnURL.

Is it possible to check, if a consent was declined by the costumer or timed out?

see Transaction Flow and Status Retrieval

---

Authorization

How long is an authorization valid for event dependent payments?

Based on the merchant industry 7 respectively 10 days.

---

Capture

Is partial capture supported/possible?

Yes, but only for event dependent payments.

What is the result if a capture is attempted after the Event Dependent Payment validity has expired?

A attempted capture after the Event Dependent Payment validity expired is not possible and results in an failed capture request.

What happens if the capture exceeds the authorized amount?

It is not possibe to capture more than the authorized amount. If the merchant still attempts to capture more than the authorized amount, the capture can't be processed and gets the status.result = failed.

Is it possible to cancel a capture?

No, only a pre-authorization in connection with the Event Dependent use case can be canceled. A capture must be refunded.

With which ID is it possible to process a capture?

It is possible to process a capture using the ID that is returned in the payment/consent request response, named paymentId.

Is the endpoint for a payment consent different from the one for a payment capture?

Yes. The wero payment model knows different payment "stages" (consent, authorization, capture, refund) which can also have different status results (successful, pending, failed). That's why the endpoints for payment consent and payment capture are different. For more details see API reference.

Is the merchant responsible for executing the capture?

Yes, the merchant must execute the capture.

How many captures can the merchant execute?

As much as needed.

Important: if multiple captures are planned, the parameters partialCapture and multiCapture must be set to true.

What is the difference between partialCapture and multipleCapture?

A partialCapture allows captures less than the full authorized amount in a single operation. MultipleCapture allows several captures, executed in sequence, that may or may not add up to the full authorized amount.

Must the parameter finalCapture be send?

No, the parameter finalCaptureis optional, but:

The final capture is particularly important in scenarios with multiple captures, as it might finalize a different amount than the originally authorized amount. This situation can occur if the merchant is unable to fully fulfill the order (for example, when certain items are no longer available).

With the status finalCapture set to true, the payment is officially processed and any remaining part of the reserved authorized amount is released back to the customer.

This is not relevant Single Immediate Payment as authorization and capture happen together.

Why is the default value of timeToCapture different from the maximum allowed value?

Most merchants are allowed to capture up to 10 days (864000 seconds). Certain merchant categories (MCCs), however, are restricted to a maximum of 7 days (604800 seconds) due to regulatory or risk considerations.

The default value of timeToCapture is set to 7 days (604800 seconds) and applies:

• if the merchant falls in a merchant category, for which the restriction is set.
• if merchants who are technically allowed to capture up to 10 days, but leave the timeToCapture field empty.

To use the longer capture period, such merchants must explicitly set timeToCaptureto a value higher than 604800, but not exceeding 864000.

Merchant categories for which the restriction of 7days (604800seconds) applies are:

Additional note: All merchants listed here are limited to a maximum capture amount of 50 EUR, regardless of their allowed capture period.

---

Refunds

What preconditions must be fulfilled in order to process a refund?

• The original payment must be captured - refunds cannot be issued for failed or expired payments.
• The refund amount must not exceed the captured amount.
• Partial refunds are possible, but the sum of all refunds must not exceed the total captured amount.
• In case of partial/multiple captures, the capture IDs must be retrieved for matching partial/multiple refunds.

Is a partial refund possible?

Yes — limited to the amount captured. In case of partial captures, limited to the amount that has been captured.

---

Cancellation

When does the merchant needs to send a cancellation?

The moment the merchant knows there will be no additional captures, he is obliged to send an authorization cancellation.

Example: Two out of three products are delivered, but the last product is not available anymore hence the merchant can't fulfill the complete order.

Which endpoint does the merchant need to call to cancel a transaction?

A cancellation is only possible for Event Dependent pre-authorizations.
To cancel such a payment before it is captured, the merchant calls the following endpoint /payments/{paymentId}/authorizations/{authorizationId}

Captures cannot be canceled. If a capture has already been executed, the merchant must create a refund instead.

Which data/information must be provided in a cancellation?

2. authorizationId
3. paymentId

What happens, if a merchant fails to send a cancellation?

As long as the authorization is active the authorized and not yet captured amount on the customer's bank account are blocked. The customer is not able to dispose of the reserved amount until the payment is confirmed or released which results in an unhappy customer experience.

In general, the authorization expires after 7 or 10 days at the latest – depending on the merchant’s industry.

---

Subscription

Which payment intervals are supported for the Subscription payment plan?

• WEEKLY
• MONTHLY
• QUARTERLY
• HALF_YEARLY
• YEARLY

Which parameters are required when sending a Subscription?

For a detailed overview for Subscription Parameters check Payment Parameters

How and when is a subscription-based payment executed?

Payments must be initiated by the merchant to the endpoint POST /{paymentId}/authorizations for the first time at the timestamp specified in the consent (parameter firstPaymentAt). Subsequent recurring payments must be sent based on the payment interval at the calculated due date.

Example - Consent Request:

"repetition": "WEEKLY",

"startAt": "2026-07-01T07:45:00Z",

"firstPaymentAt": "2026-07-01T07:45:00Z"

The first payment will take place on July 1, 2026, at 09:45 CET, and the next payment will follow on July 8, 2026, at 09:45 CET.

Is providing a specific time required when creating a subscription?

Yes, providing the time is mandatory for the parameters startAt, firstPaymentAt and endAt.

Do I have to strictly adhere to the payment interval?

Generally, the merchant is required to stick to the scheduled payment interval. However, a time deviation of up to 5 days (120 hours) from the intended date is permissible, regardless of the interval. It is not possible to repeatedly change or fluctuate the interval.

Is the amount approved by the customer automatically authorized during subscription creation?

No. When a subscription is created, it initially only represents an approval (consent) by the customer. Authorization and actual booking only occur once a transaction is submitted to the endpoint

POST /{paymentId}/authorizations

What can a merchant do if an authorization fails?

The merchant can attempt to request authorization again, but only after informing the customer about the failure. A maximum of 3 attempts within a 3-day window are permitted.

Example of a failed authorization response:

({ "result": "FAILED", "detail": "AUTHORIZATION_REJECTION_RETRYABLE", "description": "Authorization was rejected. Please contact user before triggering a retry."

})

Why can an authorization fail?

If an authorization fails, it is usually due to an issue with the customer or their bank. Possible causes include:

• The account has insufficient funds.
• A transaction limit caused the transaction to be rejected.

Can a subscription switch to a different payment interval later on?

No, this is not possible. The payment interval remains unchanged over time. Payments that do not match the specified interval will not be authorized.

Can the amount be changed within the Subscription payment plan?

Yes. It is possible to increase the amount approved by the customer, but not more than once every 6 months. However, this does not apply to the first payment. The first payment must exactly match the amount specified during the subscription setup ( given consent).

Furthermore, maximum amount increases are capped depending on the payment interval. An increase is only possible up to the following maximum amounts per interval:

Note: If the amount of the initially granted consent is already higher than the respective limit (e.g., weekly is already at €165), an amount increase is not permitted.

What happens if an amount needs to be increased more than once within 6 months?

If the amount needs to be increased more than once within a 6-month period, the merchant must send a new Consent Request to the customer for approval.

Is it possible to reduce the subscription amount?

Yes, reducing the amount is possible at any time and can be done multiple times. There are no restrictions or limits like there are for amount increases.

Can the amount be increased again after a previous reduction?

Yes, increasing the amount after a reduction is possible at any time and can be done multiple times up to the originally agreed consent amount. However, any increase beyond the original amount within a 6-month window is restricted to the maximum cap allowed for that specific payment interval.

Can a subscription be backdated?

Yes, a subscription can be configured with a start date (parameter startAt) in the past. However, the firstPaymentAt parameter must correspond to at least the current date and time.

Can the first payment for a subscription be scheduled in the future?

Yes, the date of the first payment (parameter firstPaymentAt) can be set in the future, meaning it can take place after the subscription's start date (parameter startAt).

Can a Subscription be paused?

Yes, it is possible to pause (or suspend) a wero subscription. To do so omit the authorization call for the duration of the planned suspension.

Can a subscription be canceled?

Yes. A subscription can be canceled by the merchant via the endpoint DELETE / {paymentId} consents. Following cancellation, no further payments can be processed. The customer can also cancel the subscription directly through their bank.

How does the merchant find out if a subscription was canceled by the customer?

Prior to executing any subsequent payment authorization, the merchant is required to check the validity of the consent via the endpoint GET / {paymentId}/consents.

---

Testing

Is there a wero-test-app with which it is possible to simulate wero payments?

There doesn't exist a wero-test-app at the moment. Merchant can use the test-consumer (WERO HERO) as shown in section Testing .

---

Commonly Used Terms