Variable Periodic Schedule

VariablePeriodicSchedule creates a mandate that debits up to a max amount on a regular recurring schedule (daily, weekly, monthly, or yearly). Use it for utilities or usage-based billing where the schedule is fixed but each debit amount can vary within the ceiling.

Shared root fields (type, creditorAccount, redirects, and the rest) live on the Payment Request Deep Dives intro. This page covers Variable Periodic Schedule instructions only.

The schedule object is the same shape as Fixed Periodic Schedule, except periodicSchedule takes maxAmount instead of amount.

periodicSchedule.controls is not used on periodic types. Rolling per-period caps apply only to on-demand types.

When To Use

Use VariablePeriodicSchedule when payments run on a regular recurring day or date, and each debit amount can vary up to a defined maximum.

Typical products:

Person-to-merchant utility payments
Usage-based billing on a fixed billing day each period

For a fixed amount on the same schedule model, use Fixed Periodic Schedule.

Example use case

A payer has a one-year service contract. The merchant initiates a payment on the 15th of each month. The amount varies with usage, and the payer sets a maximum individual payment of AED 400 so no debit can exceed that value.

Instructions

Field	Presence	Description
`periodicSchedule`	Required	Recurring schedule and max amount for each payment.
`maxCumulativeAmount`	Optional	Maximum cumulative value of payments over the lifetime of the consent. When set, must be greater than `periodicSchedule.maxAmount`, and must equal `periodicSchedule.maxAmount` multiplied by the number of payments initiated over the lifetime of the consent.
`maxCumulativeNumberOfPayments`	Optional	Maximum cumulative number of payments over the lifetime of the consent. When set, must equal the total number of payments that will be initiated over the schedule. Must be greater than zero.

`periodicSchedule`

Field	Presence	Description
`frequency`	Required	How often the payment runs: `Day`, `Week`, `Month`, or `Year`.
`startDate`	Required	Schedule start. Must be a future date (not today).
`maxAmount`	Required	Ceiling per debit in each period. Must be greater than zero.
`endDate`	Optional	Inclusive end bound. When set, must be after `startDate` and in the future.

Example Request

Complete body for a 12-month Variable Periodic Schedule. maxCumulativeNumberOfPayments is 12 and maxCumulativeAmount is 12 × AED 400.00.

{
  "type": "VariablePeriodicSchedule",
  "creditorType": "MERCHANT",
  "creditorReference": "UTIL15",
  "merchantReference": "vps-util-15",
  "purpose": "GDDS",
  "creditorAccount": {
    "schemeName": "IBAN",
    "identification": "AE070331234567890123456",
    "name": "Acme Trading LLC"
  },
  "successRedirectUrl": "https://merchant.example/payments/success",
  "failureRedirectUrl": "https://merchant.example/payments/failure",
  "instructions": {
    "maxCumulativeNumberOfPayments": 12,
    "maxCumulativeAmount": { "amount": "4800.00", "currency": "AED" },
    "periodicSchedule": {
      "frequency": "Month",
      "startDate": "2026-09-01",
      "endDate": "2027-08-01",
      "maxAmount": { "amount": "400.00", "currency": "AED" }
    }
  }
}

What Fails

Spare rejects the create when:

periodicSchedule is missing
frequency, startDate, or maxAmount is missing inside periodicSchedule
maxAmount is zero or negative
maxCumulativeAmount is set and is not greater than periodicSchedule.maxAmount
maxCumulativeAmount is set and does not equal maxAmount × lifetime payment count
maxCumulativeNumberOfPayments is set and does not equal the lifetime payment count on the schedule
root maxCumulativeAmount is negative
maxCumulativeNumberOfPayments is set to zero or a negative value
startDate is today or in the past
endDate is set and is on or before startDate, or is not in the future
isInternationalPayment is true (not supported on this type)

See Error codes for response shapes.

Continue learning

Payment Request Deep Dives

Shared root fields and the payment-type picker.

Fixed Periodic Schedule

Fixed amount on a regular recurring schedule.

Payment Requests

API reference for create, get, list, and delete.