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.type`	`EXACT`
`amount.value`	The recurring charge amount in the smallest currency unit. This becomes the authorised amount for all subsequent charges.
`amount.currency`	`EUR`
`consumer.country`	The country from which the consumer is shopping.
`instrument.type`	`PASSTHROUGH_WALLET`
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.
`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.

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 include this object, you'll need to specify:

The exact amount.value and amount.currency of the first payment.

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

⚠️
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",
    "description": "Description",
    "amountType": "EXACT",
    "frequency": {
        "interval": 1,
        "type": "WEEKLY"
    },
    "amount": {
        "value": "1000",
        "currency": "EUR",
    },
    "consumer": {
        "name": "John Smith",
        "country": "DE",
        }
    },
    "instrument": {
        "type": "PASSTHROUGH_WALLET",
        "details": {}
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://merchant.com/wero/return"
            }
        }
    ]
}

{
    "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"
        }
    },
    "instrument": {
        "type": "PASSTHROUGH_WALLET",
        "details": {}
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://merchant.com/wero/return"
            }
        }
    ]
}

Response

You'll receive our standard payment agreement response:

{
    "id": "agr_dqLrOcwMiuYOAbMCzihGa",
    "status": "AUTHENTICATION_PENDING",
    "description": "Description",
    "paymentMethod": "WERO",
    "frequency": {
        "type": "WEEKLY",
        "interval": 1
    },
    "startDate": "2026-09-07T19:40:11.845Z",
    "amount": {
        "value": 1000,
        "currency": "EUR"
    },
    "instrumentId": "instr_GcZjyRVEI69vKqyyxiJCv",
    "amountType": "EXACT",
    "consumer": {
        "name": "John Smith",
        "country": "DE",
        }
    },
    "authenticationMethods": [
        {
            "details": {
                "requestUrl": "https://redirections/example.mukEmRm4iRxIe0tu5aAbbZY6Sw",
                "requestMethod": "GET"
            },
            "type": "REDIRECT"
        }
    ],
    "history": [
        {
            "id": "ahist_aaMSpSkw99sEzlaNnuh83",
            "status": "AUTHENTICATION_PENDING",
            "createdAt": "2026-09-07T19:40:12.313Z"
        }
    ],
    "revocations": [],
    "createdAt": "2026-09-07T19:40:12.313Z",
    "updatedAt": "2026-09-07T19:40:12.313Z"

Pick the desired authentication method

REDIRECT

Redirect your consumer to the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestUrl . For example, with the value of https://redirection-target.ppro.com/ using the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestMethod HTTP method.

Handling the result

REDIRECT

After the consumer completes the authentication, they are redirected to the returnUrl specified in the payment charge creation request.
Upon redirect back to your site, retrieve the latest agreement status by performing a GET /v1/payment-agreements/{agreementId}. Use the returned status field to determine and display the final payment outcome 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/{agreement-id}/payment-charges

{
  "amount": {
    "value": 1999,
    "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"
}

Price Changes

Under the same active agreement, Wero allows a maximum of one price change per semester (every 6 months), according to the conditions below. The new price requires a 10-day advance notice to the consumer. Compliance with this communication is mandatory for the merchant.

Price increase below the original consent amount

Charging an amount below the original consent limit does not require a new agreement, as long as it adheres to the established frequency and mandatory communication rules outlined above. You can process this directly by updating the amount in your payment-charges request.

Price increase above the original consent amount

It is possible to change the price above the consent amount while maintaining the existing agreement, as long as the MaxAmount specified by the EPI is not inflicted. Adjustments below the MaxAmount can maintain the same active agreement, provided the communication rules mentioned above are followed.

As defined by Wero, the default MaxAmount per billing cycle are the following:

Frequency	Description
WEEKLY	€150
MONTHLY	€500
YEARLY	€5000

⚠️
New consent required for price increases above original amount
Charging above the MaxAmount will trigger a scheme rejection with error code AM21. To proceed, the current agreement must be revoked and a new one created and authorized by the consumer.

Revoking an active agreement

Consumer-initiated revocation

The consumer can cancel the subscription directly from the Wero app at any time. When this happens, PPRO sends a webhook to your notificationUrl.Once revoked, no further charges can be triggered against this agreement. You must create a new agreement if the consumer wishes to resubscribe.

Merchant-initiated revocation

To cancel the subscription on behalf of the consumer, call the revoke endpoint: POST /v1/payment-agreements/{agreement-id}/revoke.

Expected response (200):

{
  "id": "agr_wRk9mXtYpQzLvN3cJbD7F",
  "status": "REVOKED_BY_MERCHANT",
  "updatedAt": "2026-10-15T14:30:00.000Z"
}