REST API Wero

Wero is a pan-European digital wallet initiative developed by EPI (European Payments Initiative), designed to provide a unified, secure and instant payment experience across participating EU countries. Built on SEPA Instant Credit Transfer (SCT Inst) rails, Wero aims to be a direct competitor to other mobile wallets and promote cross-border, real-time payments in the euro area.

With a focus on both online and in-store use cases, Wero allows users to send and receive money instantly enhancing convenience while maintaining compliance with European regulatory standards.

Get started

1. Contact Paygate Support to activate Wero payment method for your merchant profile.

2. Integrate by choosing the integration option tailored to your needs.

Integration options

NEXI Paygate supports Wero payments through the following integration types:

• Hosted Payment Page: Initiate Hosted Payment Page by calling Create checkout session.

• Hosted forms: Initiate Hosted forms by calling Create payment with: 

  "paymentMethods": {
    "type": "WERO",
    "integrationType": "HOSTED"
  }
  

Notice: For Wero with captureMethod.type=MANUAL the initial payment request translates to an event dependent payment plan.

Reverse payment

If a payment needs to be voided before settlement, you can initiate a reversal using the Reverse payment endpoint. Only unsettled Wero payments can be reversed.

Capture payment

If the payment was initiated with a manual capture flow (captureMethod.type=MANUAL), you must explicitly capture the authorized amount using the Capture payment endpoint.

If the initial transaction did not include the MANUAL capture method, the payment will be auto-captured by default.

Wero Transaction Statuses

The meaning of a transaction status depends on the Wero payment flow being used. Merchants should interpret the returned status according to the endpoint and transaction type.

1. Single Immediate Payment

A Wero Single Immediate Payment is processed as a single-step payment from the merchant's perspective.

Internally, the transaction consists of the following processing steps:

1. Consent approval followed by payment authorization

2. Automatic capture initiated by Paygate

Following payment processing, Paygate sends a webhook notification containing the unique PayID. The merchant must retrieve the latest payment information using GET Payment by PayID or GET Payment by TransID.

Payment status interpretation

The GET Payment response represents the overall payment status at the time of the inquiry, rather than the individual result of each processing operation.

A successful authorization is initially represented by OK. However, the overall payment status may subsequently change due to automatic capture processing.

Therefore, merchants must evaluate the amount fields in addition to the overall payment status and response code.

For intermediate processing statuses such as CAPTURE_REQUEST or CREDIT_REQUEST, the corresponding amount remains zero until the operation is successfully completed.

Merchant fulfillment rules

For Single Immediate Payments, successful authorization establishes the payment guarantee, allowing merchants to fulfill the order without waiting for capture completion.

Important

The overall payment status FAILED does not necessarily indicate a failed authorization. It may also represent an unsuccessful automatic capture attempt.

If amount.value is positive, authorization was successful and the merchant may proceed with fulfillment, even if the overall status subsequently changes to FAILED due to capture processing.

If amount.value is zero, no successful authorization is confirmed and the merchant must not ship the goods.

These fulfillment rules assume that the payment has not subsequently been cancelled or refunded.

Automatic capture and retry

Following successful authorization, Paygate automatically initiates capture on behalf of the merchant.

If an automatic capture attempt fails, Paygate retries capture daily for up to 16 consecutive days, without merchant intervention.

During this period:

• amount.value remains positive, confirming the successful authorization.

• amount.capturedValue remains zero until capture succeeds.

• The overall payment status may change from FAILED to OK following a successful retry.

Merchants can retrieve the latest capture result using GET Payment. No additional webhook notification is sent for subsequent automatic capture retries or status changes.

If automatic capture remains unsuccessful after the retry period, settlement is handled through a manual procedure between the participating banks in accordance with EPI operating rules.

Merchants must not initiate or retry capture for Single Immediate Payments. Capture processing and recovery are managed exclusively by Paygate and the participating banks.

2. Event-dependent payment (manual capture)

An Event-dependent payment is processed as a two-step transaction:

1. Consent and authorization (same as Single Immediate)

2. Merchant-initiated capture

Once the business event defined by the merchant occurs (for example, shipment of goods or completion of a service), the merchant submits a capture request using the Capture API.

The default period allowed between authorization and capture for Wero event dependent payments is 7 days.

Authorization status

Capture status

After the merchant submits the capture request, the following statuses may be returned:

Under normal SEPA Instant processing conditions, the capture should reach a final status within approximately 10 seconds.

The merchant should periodically call the Inquiry API until either OK or FAILED is returned.

Unlike Single Immediate Payments, Event-dependent payments currently do not include an automatic capture retry mechanism. Support for automatic retries is being evaluated for a future release.

3. Refund

Refunds are initiated by the merchant through the dedicated Refund API.

After a refund request has been accepted, the following statuses may be returned:

Under normal SEPA Instant processing conditions, the refund should reach a final status within approximately 10 seconds.

The merchant should periodically call the Inquiry API until either OK or FAILED is returned.

4. Delayed settlement and inquiry

In exceptional situations, settlement between the acceptor bank and the consumer bank may take longer than the standard SEPA Instant processing time.

For capture and refund transactions that remain in a non-final state, Paygate automatically checks and update the transaction status according to the following schedule:

• Approximately 1 minute after submission

• Approximately 5 minutes after submission

• Approximately 1 hour after submission

• After 24 hours thereafter

• After 48 hours thereafter

These background checks help Paygate maintain the latest transaction state but do not replace the merchant's responsibility to retrieve the final result.

For all Event-cependent capture and refund requests, merchants should periodically call the Inquiry API until a final status (OK or FAILED) is returned.

No Inquiry polling is required for Single Immediate Payments because the merchant receives only the authorization result (AUTHORIZED) while Paygate manages capture and settlement transparently.