Wero

Description

Wero is a new pan-European digital wallet and payment system created by the European Payments Initiative (EPI) to enable instant, account-to-account transfers across Europe. It allows users to send and receive money in seconds using a mobile number or email address, working both online and in stores.

Availability

Wero is for ecommerce in Germany available. Belgium, France, Luxembourg and Netherlands will follow soon.

Transaction Types

The following transaction types are currently available:

• Payment
• Refund (Full and partial refund)

Integration Types

The following integration type is currently available:

• Payment Page Redirect

Payment Flow

Example of Wero Payment Redirect On Mobile

API Implementation

Required value for payment_type parameter: wero

Payment Page Redirect

Redirect the customer to the Wero payment page.

Implementation flow:

1. Make a Payment API request.
2. Receive API response with client_action.
3. Redirect your customer to the payment page URL in action_data.
4. Customer is redirected to success_url or error_url.
5. Receive asynchronous postback notifications to postback_url about transaction status.

Payment API Request

payment_typeStringrequired

wero

order_idStringrequired

Any alphanumeric string to identify the Merchant's order

amountFloatrequired

Amount of the transaction including all taxes and shipping fees

currencyStringrequired

3 letter currency code

merchant_referenceStringrequired

Will be shown in remittance information. Maximum 35 characters. Valid characters: a-zA-Z0-9/-?():.,'+ and space

additional_transaction_dataString

Additional payment information provided by you. This will be shown in the dashboard as well as when you query for transaction data. It will also be sent back to your postback_url as part of the postback data.

postback_urlStringrequired

The URL for updates about transaction status are posted

success_urlStringrequired

Where to redirect the user after a successful transaction

error_urlStringrequired

Where to redirect the user after a failed transaction

Example Request

POST /rest/payment
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"payment_type": "wero",
"order_id": "12345678",
"amount": "15.90",
"currency": "EUR",
"merchant_reference": "12345678 - Test Shop",
"additional_transaction_data": "customer_id=123ABC, billing_info=12345678",
"postback_url": "https://your-postback.url.com",
"success_url": "https://your-success.url.com",
"error_url": "https://your-error.url.com"
}

Payment API Response

transaction_idString

ID of the created transaction

payment_typeString

Payment type of the transaction

status_codeInteger

Status code of the transaction

statusString

Status of the transaction

order_idString

Order ID of the transaction

messageString

Optional additional information about the transaction result. When declined, this field contains the decline code (e.g. AC01)

additional_transaction_dataString

Additional transaction data provided by you. This will be shown in the dashboard as well as when you query for transaction data. It will also be sent back to your postback_url as part of the postback data.

amountFloat

Amount of the transaction

included_feesString

Included fees for the transaction

error_codeInteger

Error code for the response

client_actionString

Indicates the required client-side action after a payment request. Possible values: redirect (redirect to the url in action_data) or postform (build and submit a POST form using the data in action_data). When not returned, no client-side action is required.

action_dataObject

Present when client_action is specified. Contains: url (target URL of the action) and, in case of a postform, fields (key/value pairs of the data to be posted).

Example Response

{
"transaction_id": "d1bf9fdf-7268-406f-9e08-8d5a9540ab97",
"payment_type": "wero",
"status_code": 1,
"status": "started",
"order_id": "12345678",
"message": null,
"additional_transaction_data": "customer_id=12345678, billing_info=12345678",
"amount": 15.9,
"included_fees": "0.00",
"error_code": 0,
"client_action": "redirect",
"action_data": {
  "url": "https://testapi.betterpayment.de/payment/d1bf9fdf-7268-406f-9e08-8d5a9540ab97"
}
}

Refund API Request

transaction_idStringrequired

ID of the transaction to be refunded

merchant_referenceString

Will be shown in remittance information. Default value if not provided: merchant_reference from original transaction. Maximum 35 characters. Valid characters: a-zA-Z0-9/-?():.,'+ and space

amountFloat

When not given, full amount will be refunded. Can be smaller but not larger than the original amount

commentString

If provided, must be one of: RETURNED_GOODS, WRONG_AMOUNT_CORRECTION, PRE_DISPUTE_REFUND, SUBSCRIPTION_REFUND, SERVICE_LATE_CANCELLATION, OTHER

Example Request

POST /rest/refund
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"transaction_id": "d1bf9fdf-7268-406f-9e08-8d5a9540ab97",
"merchant_reference": "12345678 - Test Shop",
"amount": "10.00",
"comment": "RETURNED_GOODS"
}

Refund API Response

note

The response is attributed to the Refund object — not the transaction. Thus, the status_code and status will differ from transaction values.

transaction_idString

ID of the refunded transaction

refund_idString

ID of the created refund object

statusString

Status of the refund (STARTED, SUCCESS, ERROR)

status_codeInteger

Status code of the refund (0 for STARTED, 1 for SUCCESS, 2 for ERROR)

error_codeInteger

Error code for the response

Example Response

{
"transaction_id": "d1bf9fdf-7268-406f-9e08-8d5a9540ab97",
"refund_id": "2ce3297b-1bda-4637-9375-ecf224cdefc7",
"status_code": 1,
"status": "successful",
"error_code": 0
}

Postbacks

For the full list of payment postback fields, see the Payment API. For refund postbacks, see the Refund API. For retry policy and signature verification, see Postbacks.

Test Data

Please request access to the Wero UAT mobile app for iOS or Android from your onboarding manager to make test transactions.

Test Scenarios for Payment Methods

The following test scenarios are required for Wero Go Live certification. Each scenario must be executed successfully in the UAT environment. Scenarios marked as Required must be completed for certification; Optional scenarios are recommended but not mandatory.

Required Scenarios

TC-CONSENT-GRANTED-01 — Happy Case: Consumer approves consent

Description: Consumer approves consent in Wero UAT app without errors or declines.

Steps:

1. Create payment: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.

Pass Criteria: Verify expected status in postback received: completed

Evidence Requirement: transaction_id from postback

TC-CONSENT-DENIED-01 — Unhappy Case: Consumer denies consent

Description: Consumer denies consent in Wero UAT app.

Steps:

1. Create payment: POST /rest/payment
2. Open redirect_url and deny consent with Wero UAT app.

Pass Criteria: Verify expected status in postback received: canceled

Evidence Requirement: transaction_id from postback

Client Evidence: Screenshot of error page including error message

TC-AUTH-FAILED-1 — Unhappy Case: Technical failure during authorisation

Description: Technical failure during authorisation.

Steps:

1. Create payment with 1993.62 as amount: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.

Pass Criteria: Verify expected status in postback received: error

Evidence Requirement: transaction_id from postback

Client Evidence: Screenshot of error page including error message

TC-AUTH-REJECTED-01 — Unhappy Case: Decline with reason code

Description: Decline with reason code. Possible reason codes:

• AM04: Consumer does not have sufficient funds in their account
• AM02: Transaction amount is greater than the maximum allowed for the consumer's account
• AM21: Transaction amount exceeds limits agreed between consumer's bank and consumer
• AC03: Merchant's IBAN did not pass validity checks
• AC05: The consumer's account is closed
• AC06: Consumer/merchant's account is blocked
• AG01: Limitation on consumer/merchant's account

Steps:

1. Create payment with one of the amounts below: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.

Possible amounts:

• 1993.63 for reason_code "AM04" (Insufficient funds)
• 1993.64 for reason_code "AM02" (Invalid amount)
• 1993.65 for reason_code "AM21" (Limit exceeded)
• 1993.66 for reason_code "AC03" (Invalid creditor account)
• 1993.67 for reason_code "AC05" (Closed debtor account)
• 1993.87 for reason_code "AC06" (Blocked account)
• 1993.88 for reason_code "AG01" (Transaction forbidden)

Pass Criteria: Verify expected status in postback received: declined

Evidence Requirement: transaction_id from postback

TC-R-VOP-01 — Happy Case: Refund Settled & VoP Match

Description: Refund Settled & VoP Match.

Steps:

1. Create payment with <corporate-id-vop-mtch> as shop_id: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create refund using the transaction_id from payment: POST /rest/refund

Pass Criteria: Verify expected refund_status_code in refund postback received: 1 (Successful)

Evidence Requirement: transaction_id from postback

TC-R-VOP-03 — Unhappy Case: Refund Rejected in case of VoP Close Match

Description: Refund Rejected in case of VoP Close Match.

Steps:

1. Create payment with <corporate-id-sepa-mock-cmtc-1> as shop_id: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create refund using the transaction_id from payment: POST /rest/refund

Pass Criteria: Verify expected refund_status_code in refund postback received: 5 (Declined)

Evidence Requirement: transaction_id from postback

TC-R-VOP-05 — Unhappy Case: Refund fails when VoP is Not Applicable (NOAP)

Description: Refund fails when VoP is Not Applicable (NOAP).

Steps:

1. Create payment with <corporate-id-vop-noap> as shop_id: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create refund using the transaction_id from payment: POST /rest/refund

Pass Criteria: Verify expected refund API response error_message received: Name match: Not applicable

Evidence Requirement: transaction_id from postback

TC-R-VOP-06 — Unhappy Case: Refund fails in case of Payee Mismatch (NMTC)

Description: Refund fails in case of Payee Mismatch (NMTC).

Steps:

1. Create payment with <corporate-id-vop-nmtc> as shop_id: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create refund using the transaction_id from payment: POST /rest/refund

Pass Criteria: Verify expected refund API response error_message received: Name match: No match

Evidence Requirement: transaction_id from postback

TC-R-ERR-01 — Unhappy Case: Refund a non-settled payment

Description: Refund a non-settled payment.

Steps:

1. Create payment with 1993.73 as amount: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create refund using the transaction_id from payment: POST /rest/refund

Pass Criteria: Verify expected refund API response error_message received: Capture with id(s) "<transaction_id>" not found.

Evidence Requirement: transaction_id from postback

Optional Scenarios

TC-CONSENT-ERR-01 — Unhappy Case: Missing required field

Description: Missing required field.

Steps:

1. Create payment with missing required field (e.g. amount): POST /rest/payment

Pass Criteria: Verify error_message in API response: Field 'paymentPlan.amount' is invalid.

TC-CONSENT-ERR-02 — Unhappy Case: Invalid Data Type

Description: Invalid Data Type.

Steps:

1. Create payment with invalid data type (e.g. amount as text "abc"): POST /rest/payment

Pass Criteria: Verify error_message in API response: Field 'paymentPlan.amount' is invalid.

TC-CAP-PENDING-01 — Processing Case: Capture Pending

Description: Capture Pending.

Steps:

1. Create payment with 1993.73 as amount: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.

Pass Criteria: Verify expected status in postback received: pending

Evidence Requirement: transaction_id from postback

TC-CAP-REJECTED-01 — Unhappy Case: Capture Rejected

Description: Capture Rejected.

Steps:

1. Create payment with 1993.74 as amount: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.

Pass Criteria: Verify expected status in postback received: declined

Evidence Requirement: transaction_id from postback

TC-CAP-FAILED-01 — Unhappy Case: Capture Failed

Description: Capture Failed.

Steps:

1. Create payment with 1993.75 as amount: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.

Pass Criteria: Verify expected status in postback received: error

Evidence Requirement: transaction_id from postback

TC-R-VOP-02 — Unhappy Case: Refund rejects in case of VoP Match

Description: Refund rejects in case of VoP Match.

Steps:

1. Create payment with <corporate-id-sepa-mock-mtch-1> as shop_id: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create refund using the transaction_id from payment: POST /rest/refund

Pass Criteria: Verify expected refund_status_code in refund postback received: 2 (Error)

Evidence Requirement: transaction_id from postback

TC-R-ERR-02 — Unhappy Case: Refund Amount Exceeds Capture Amount

Description: Refund Amount Exceeds Capture Amount.

Steps:

1. Create payment: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create refund using the transaction_id from payment and higher amount than the payment: POST /rest/refund

Pass Criteria: Verify expected API response error_message received: The refunded amount cannot exceed the original amount.

TC-R-ERR-04 — Unhappy Case: Refund a capture that has already been fully refunded

Description: Refund a capture that has already been fully refunded.

Steps:

1. Create payment: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create refund using the transaction_id from payment: POST /rest/refund
4. Create refund again using the transaction_id from payment: POST /rest/refund

Pass Criteria: Verify expected API response error_message received: The refunded amount cannot exceed the original amount.

TC-R-ERR-05 — Unhappy Case: Multiple partial refunds exceeding original capture amount

Description: Multiple partial refunds on a captured payment, where the final refund attempt causes the total refunded amount to exceed the original capture amount.

Steps:

1. Create payment: POST /rest/payment
2. Open redirect_url and approve consent with Wero UAT app.
3. Create partial refund using the transaction_id from payment and lower amount than the payment: POST /rest/refund
4. Create refund again using the transaction_id from payment: POST /rest/refund

Pass Criteria: Verify expected API response error_message received: The refunded amount cannot exceed the original amount.