Periodic payments

❗️
As for single payment, you need first to do the Verification Of Payee (VOP) for the recipients (payee) for which you didn't do a KYB! Contact [email protected] for more information.

A periodic payment refers to a recurring payment instruction where a PSU authorizes their Payment Service Provider (PSP) to execute regular payments of the same amount to the same beneficiary at predetermined intervals. Key characteristics of periodic payments:

Regular schedule: Payments occur at defined intervals (weekly, monthly, quarterly, etc.) Single authorization: The payer gives one-time consent for the series of future payments, rather than authorizing each transaction individually Same beneficiary: All payments in the series go to the same recipient

Request model

The periodic payment request model is an extension of the single payment request model. It adds the necessary fields to tell the bank when to start and end and the frequency.

Compared to a "normal" single payment, the periodic payment has five more fields:

startDate: date, the first applicable day of execution.
endDate: date, the last applicable day of execution. If not given, it is an infinite standing order.
frequency: integer, the frequency of the recurring payment
- 0: unknown, just for default parsing, not to be used.
- 1: daily.
- 2: weekly.
- 3: every two weeks.
- 4: monthly.
- 5: every two months.
- 6: quarterly.
- 7: semi annual.
- 8: annual.
- 9: every four months.
- 10: every three months.
- 11: monthly variable
dayOfExecution: integer, day of execution
monthsOfExecution: integer list, months when the payment should occur. This attribute is supplied if and only if the frequency equals "MonthlyVariable".

Options

Of course, each bank might have its own rules. To ensure that your code is independent from the selected connector, we've added some options to drive your interface or logic.

In each top section, DomesticTransfers, InstantDomesticTransfers, SepaCreditTransfers or InstantSepaCreditTransfers, you'll find a PeriodicPayments section containing the options for periodic payment.

{
	"sepaCreditTransfers": {
  	"singlePayments": {},
    "periodicPayments": {
        "paymentInitiationRequestOptions": {
          "startDate": 0,
          "endDate": 1,
          "executionRule": 2,
          "supportedExecutionRules": null,
          "frequency": 0,
          "supportedFrequencies": [2,4,6,7,8],
          "dayOfExecution": 1,
          "dayOfExecutionAllowedValues": [1,2,3,4,5,31],
          "dayOfExecutionDescription": "Days of the week 1 through 5 starting on Monday if frequency is Weekly. 31 is used as last day of the month if frequency is Monthly, Quarterly, SemiAnnual or Annual.",
          "monthsOfExecution": 2,
          "allowedMonthsOfExecutionValues": [1,2,3,4,5,6,7,8,9,10,11,12],
          ...
        },
				"supported": true,
				"cancelSupported": true,
			}
	}
}

In the path product type.periodicPayments.paymentInitiationRequestOptions

startDate: the date at which the periodic payment should start. 0: required, 1: optional, 2: unused.
endDate: the date at which the periodic payment should start. 0: required, 1: optional, 2: unused.
executionRule: execution rule. 0: required, 1: optional, 2: unused.
SupportedExecutionRules: list of supported rules to follow when the payment date lands on a holiday or weekend:
- 0: Unknown, just for default parsing, not to be used.
- 1: Following, payment will happen on the working day following the weekend/holiday.
- 2: Preceding, payment will happen on the working day preceding the weekend/holiday.
frequency: 0: required, 1: optional, 2: unused.
supportedFrequencies: Frequency Type based on ISO 20022 codes (EventFrequency7Code: https://www.iso20022.org/standardsrepository/type/EventFrequency7Code). See request.frequency here above for possible values.
dayOfExecution: 0: required, 1: optional, 2: unused.
dayOfExecutionAllowedValues: list of day of the month (1 to 31) that can be used.
dayOfExecutionDescription: extra textual description about the day of execution.
monthsOfExecution: 0: required, 1: optional, 2: unused.
allowedMonthsOfExecutionValues: list of allowed values for monthsOfExecution

Flows

Creation

As for single payment flow, you have roundtrips to the bank for the Strong Customer Authentication and payment confirmation. This could be done in one flow or in multiple (one for the login and one for the confirmation) depending on the bank. The principle is the same as for single payment. See the page PIS flow and the programming principle of single payment in that same page.

You first call POST /ob/Pis/payments/periodic to initiate the payment with the request,
do the roundtrip to the bank and
call PUT /ob/Pis/payments/periodic to finalize the payment with the received query string, verbatim.

Example of POST/initiation:

{
  "connectorId": 2,
  "userContext": "the user context",
  "paymentInitiationRequest": {
    "recipient": {
      "name": "Jane Doe",
      "iban": "BE12345678901234",
      "currency": "EUR"
    },
    "debtor": {
      "name": "John Doa",
      "iban": "BE123456789012134"
    },
    "psuIp": "public IP of the PSU",
    "paymentPriority": 0,
    "paymentProduct": 1,
    "redirectUrl": "Your app redirect URL",
    "endToEndId": "the end to end id, max 35 chars",
    "amount": 5.00,
    "currency": "EUR",
    "flowId": "Your id of the payment",
    "remittanceInformationUnstructured": "This is your remittance unstructured",
    "startDate": "2026-06-01",
    "endDate": "2026-12-01",
		"frequency": 4 // Monthly
  }
}

Example of PUT/finalization:

{
    "flow": "the flow context from POST response",
    "dataString": "?flowId=ABC-Query string received by your callback, verbatim",
    "userContext": "the user context"
}

You can also call POST /ob/Pis/payments/periodic/status to get the status of the payment. Note that it's the same response you get from the PUT /ob/pis/payments/periodic with a resultStatus DONE(1).

Cancelation

If the cancelation is available for the bank (see payment option "payment product.periodicPayments.cancelSupported), you'll have to do the SCA roundtrip to the bank has for payment creation with the same logic:

POST /ob/Pis/payments/periodic/cancel for initiation,
roundtrip to the bank and
PUT /ob/Pis/payments/periodic/cancel for finalization with the received query string, verbatim.