Payment method properties


Markets (consumer)	`DE` `BE`
Processing currencies	`EUR`
Consumer currencies	`EUR`
Authentication methods	`REDIRECT`
Authentication timeout	1 Hour

Create the payment agreement

To create a Wero payment agreement, provide the following information when calling our payment agreements endpoint:

Field	Description
`paymentMethod`	`WERO`
`amount.value`	The recurring charge amount in the smallest currency unit. This becomes the authorised amount for all subsequent charges.
`amount.currency`	`EUR`
`amount.type`	`EXACT`
`consumer.country`	The consumer country
`frequency.type`	The type of frequency between consecutive payment charges. Allowed: WEEKLY, MONTHLY or YEARLY.
`frequency.interval`	The interval between consecutive payment charges.
`startDate`	The date when the subscription mandate begins.
authenticationSettings: REDIRECT `settings.returnUrl`	Specify the URL to which the consumer should be redirected after completing the payment. This is required for the `REDIRECT` payment flow.

Optional Fields

Field	Description
`endDate`	The date when the subscription ends. If omitted, the mandate is open-ended until revoked.
`description`	The description of the agreement.

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call.

If you don't include an initialPaymentChargeduring agreement creation, you may make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the charges.

⚠️
First Charge Timing Restriction
If you separate the first charge from the agreement creation, then the first payment request cannot be triggered on the same calendar day as the agreement startDate. A minimum gap of 1 day is required between startDate and the first charge, as enforced by Wero.

Request

POST /v1/payment-agreements

{
    "paymentMethod": "WERO",
    "amount": {
        "value": 1000,
        "currency": "EUR"
    },
    "amountType": "EXACT",
    "frequency": {
        "interval": 1,
        "type": "MONTHLY"
    },
    "consumer": {
        "country": "DE"
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://www.ppro.com/"
            }
        }
    ]
}

{
    "paymentMethod": "WERO",
    "description": "Wero description",
    "amountType": "EXACT",
    "frequency": {
        "interval": 1,
        "type": "WEEKLY"
    },
    "amount": {
        "value": "1000",
        "currency": "EUR"
    },
    "consumer": {
        "name": "John Smith",
        "country": "DE",
        }
    },
    "initialPaymentCharge": {
        "amount": {
            "value": 1000,
            "currency": "EUR"
        }
    }
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://merchant.com/wero/return"
            }
        }
    ]
}

Response

You'll receive our standard payment agreement response:

{
    "id": "agr_2A8UGcOCRM2V8IKY640ti",
    "status": "AUTHENTICATION_PENDING",
    "paymentMethod": "WERO",
    "frequency": {
        "type": "MONTHLY",
        "interval": 1
    },
    "startDate": "2026-10-20T14:03:58.200Z",
    "amount": {
        "value": 1000,
        "currency": "EUR"
    },
    "instrumentId": "instr_YuTd3QaGNPVoczP5lRkqz",
    "amountType": "EXACT",
    "consumer": {
        "country": "DE"
    },
    "authenticationMethods": [
        {
            "details": {
                "requestUrl": "https://redirect.ppro.com/redirections/forward?redirection_token=samplepayment",
                "requestMethod": "GET"
            },
            "type": "REDIRECT"
        }
    ],
    "history": [
        {
            "id": "ahist_3zyXRPXJZmBjy6vRCmJTp",
            "status": "AUTHENTICATION_PENDING",
            "createdAt": "2026-10-20T14:03:58.570Z"
        }
    ],
    "revocations": [],
    "createdAt": "2026-10-20T14:03:58.570Z",
    "updatedAt": "2026-10-20T14:03:58.570Z"
}

Pick the desired authentication method

REDIRECT

Redirect your consumer to the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestUrl

For example, with the value of https://redirect.ppro.com/ using the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestMethod HTTP method.

Handling the payment result

After the consumer completes the payment, they are redirected back to the returnUrl specified by you in the payment charge creation request.
Upon redirect back to your checkout page, retrieve the latest payment status by performing a GET operation on the payment agreement, use the returned status attribute to determine the payment outcome and display it to the consumer.
Additionally, webhooks are triggered to notify you of the payment result. This ensures you receive the outcome even if the consumer closes their browser or fails to return to your website.

Create a recurring payment

To initiate a subsequent recurring payment, send a request against an active agreement using our payment agreements API.

Request

POST /v1/payment-agreements/agrId/payment-charges

{
  "amount": {
    "value": 1000,
    "currency": "EUR"
  }

Response

{
    "id": "charge_bP3r2Xxdy02fF3lfVhnNg",
    "paymentMethod": "WERO",
    "currency": "EUR",
    "country": "DE",
    "paymentDescriptor": "Payment Descriptor",
    "instrumentId": "instr_a1eqs9w5upxXgq5iTgbmz",
    "status": "CAPTURED",
    "consumer": {
        "name": "John Smith",
        "email": "[email protected]",
        "country": "DE",
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "Product Name 1",
                "quantity": 1,
                "amount": 1000
            }
        ],
        "industryData": []
    },
    "authorizations": [
        {
            "id": "authz_RvwG9SEaxe51Ku72QFirt",
            "amount": 1000,
            "status": "AUTHORIZED",
            "merchantPaymentChargeReference": "60502e33-3007-4e11-a38c-cf7c8bd80d41",
            "createdAt": "2026-09-07T20:27:42.248Z",
            "updatedAt": "2026-09-07T20:27:42.248Z"
        }
    ],
    "captures": [
        {
            "id": "capture_1ADkmpX3v4nSCsw9EPxan",
            "amount": 1000,
            "status": "CAPTURED",
            "merchantCaptureReference": "60502e33-3007-4e11-a38c-cf7c8bd80d41",
            "createdAt": "2026-09-07T20:27:42.654Z",
            "updatedAt": "2026-09-07T20:27:42.654Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2026-09-07T20:27:41.023Z",
    "updatedAt": "2026-09-07T20:27:42.654Z"
}

Recurring Amount Changes

Amount changes (under the same active agreement):

Frequency: Max one price change per 6 months (per semester).
Notice: Consumer must be notified 10 days in advance of the new price.
Increase up to the original consented agreement amount: No new agreement needed. Just update the amount in your next payment-charges request, provided frequency and notice rules are met.
Increase above the original consented agreement amount: The existing agreement can still be kept, as long as the new amount stays within the Wero's MaxAmount limits and the same frequency and notice rules are followed.

Frequency	Max Amount
WEEKLY	€150
MONTHLY	€500
YEARLY	€5000

⚠️
New consent required for price increases above Max Amount
Charging above the MaxAmount will end in the charge being rejected & it fails as PROVIDER_DECLINE. To proceed, the current agreement must be revoked and a new one needs to be created and authorized by the consumer again.