PPRO supports recurring payments for iDEAL through SEPA Direct Debit. You can offer iDEAL recurring payments easily with our payment agreements API.

📘
Note
When offering iDEAL at checkout for a recurring product, it is essential to secure explicit approval (a mandate) from the consumer to debit their account on a recurring basis via SEPA Direct Debit. Given the inherent chargeback risk associated with SEPA Direct Debits, transparency with the consumer is key to mitigating this risk.

Create the payment agreement

To create an iDEAL payment agreement, provide the following information when calling our payment agreements API:

Data Field	Required	Description
paymentMethod	M	`IDEAL`
consumer.name	M	Full name of the consumer.
consumer.country	M	The country from which the consumer is shopping.
instrument: BANK_ACCOUNT details.debitMandateId	M	When a consumer chooses iDEAL for recurring payments and agrees to a direct debit mandate, generate a mandate ID and store it. Provide this ID when creating the payment agreement with PPRO.
authenticationSettings: REDIRECT settings.returnUrl	M	Add the url where the consumer should be redirected to after they complete the payment. Required for the `REDIRECT` payment flow.
instrument: BANK_ACCOUNT details.bankCode	O	Providing the `bankCode` will bypass the bank selection. Optional and must meet the conditions listed above.

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 initialPaymentCharge when creating the agreement, a €0.01 verification payment will be made and immediately refunded to validate the bank account. You'll need to make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the first charge.

Request

POST /v1/payment-agreements

{
  "paymentMethod": "IDEAL",
  "consumer": {
    "name": "John Smith",
    "country": "NL"
  },
  "instrument": {
    "type": "BANK_ACCOUNT",
    "details": {
      "debitMandateId": "YOUR_GENERATED_MANDATEID"
    }
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://www.webshop.com/order-results-page"
      }
    }
  ]
}

{
  "paymentMethod": "IDEAL",
  "consumer": {
    "name": "John Smith",
    "country": "NL"
  },
  "instrument": {
    "type": "BANK_ACCOUNT",
    "details": {
      "debitMandateId": "YOUR_GENERATED_MANDATEID"
    }
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://www.webshop.com/order-results-page"
      }
    }
  ],
  "initialPaymentCharge": {
    "amount": {
      "value": 1000,
      "currency": "EUR"
    }
  }
}

Response

You'll receive our standard payment agreement response (see responses in the API Reference)

❗️
Note
Although no initial payment charge is submitted in the request, a €0.01 verification payment is authorized and immediately refunded to verify the agreement.

{
  "id": "agr_z3RcfOXROR7nmy3WlJI94",
  "status": "AUTHENTICATION_PENDING",
  "paymentMethod": "IDEAL",
  "startDate": "2025-04-15T17:11:59.354Z",
  "instrumentId": "instr_eU80TTzNzRPj7XfHwO3Q3",
  "consumer": {
    "name": "John Smith",
    "country": "NL"
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    }
  ],
  "history": [
    {
      "id": "ahist_lqBDnAWmqpluqCDo3MJi8",
      "status": "AUTHENTICATION_PENDING",
      "createdAt": "2025-04-15T17:12:00.019Z"
    }
  ],
  "initialPaymentChargeId": "charge_AoLMTgQe2AmGDq3ePPnav",
  "createdAt": "2025-04-15T17:12:00.019Z",
  "updatedAt": "2025-04-15T17:12:00.019Z"
}

{
  "id": "agr_rTOfYUHHaxfuEYQrCDc0L",
  "status": "AUTHENTICATION_PENDING",
  "paymentMethod": "IDEAL",
  "startDate": "2025-04-14T12:25:04.274Z",
  "instrumentId": "instr_UJ5dpTkpNZxL7kPgRSM7v",
  "consumer": {
    "name": "John Smith",
    "country": "NL"
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    }
  ],
  "history": [
    {
      "id": "ahist_pz7KWLQ993LgjaK5GzYNI",
      "status": "AUTHENTICATION_PENDING",
      "createdAt": "2025-04-14T12:25:04.712Z"
    }
  ],
  "initialPaymentChargeId": "charge_58Uoysih1v5uPAJhEoWpc",
  "createdAt": "2025-04-14T12:25:04.712Z",
  "updatedAt": "2025-04-14T12:25:04.712Z"
}

Pick the desired authentication method

APP_NOTIFICATION

Ask your consumer for the required identifier needed to initiate the push notification, often a consumer identifier like a phone, email address or tax identification.
The consumer will receive a push notification to complete the payment process.

Handling the result

APP_NOTIFICATION

The payment charge will remain in the AUTHENTICATION_PENDING state until the consumer confirms the payment.
Webhooks are sent to inform you of the agreement and/or payment outcome.
Alternatively, check the agreement and/or payment status and use the Status that you received to display the outcome to the consumer.
GET /v1/payment-agreements/{agreement-id}
GET [/v1/payment-charges/{paymentChargeId}]([https://developerhub.ppro.com/global-api/reference/getpaymentcharge](https://developerhub.ppro.com/global-api/reference/getpaymentcharge).
Store the Payment Agreement ID for subsequent payments.

Create a recurring payment

To initiate a subsequent recurring payment, send a request against an active agreement /v1/payment-agreements/{agreement-id}/payment-charges

Request

POST /v1/payment-agreements/{agreement-id}/payment-charges

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

Response

{
  "id": "charge_fmUbxp5wZi1zZj4mUDn4S",
  "paymentMethod": "SEPA_DIRECT_DEBIT",
  "currency": "EUR",
  "country": "NL",
  "instrumentId": "instr_UJ5dpTkpNZxL7kPgRSM7v",
  "status": "AUTHORIZATION_ASYNC",
  "consumer": {
    "name": "John Smith",
    "country": "NL"
  },
  "authorizations": [
    {
      "id": "authz_5WhS0eutxeiOHHLbAP7ad",
      "amount": 1100,
      "status": "AUTHORIZATION_ASYNC",
      "createdAt": "2025-04-14T12:30:56.522Z",
      "updatedAt": "2025-04-14T12:30:56.522Z"
    }
  ],
  "captures": [],
  "refunds": [],
  "voids": [],
  "createdAt": "2025-04-14T12:30:55.957Z",
  "updatedAt": "2025-04-14T12:30:56.522Z"
}

❗️
Since subsequent recurring charges are processed via SEPA Direct Debit, they are inherently susceptible to chargebacks, as outlined here