Variable Defined Schedule

VariableDefinedSchedule creates a mandate that allows debits up to a max amount on specific calendar dates you list up front. Use it for project milestones or staged billing where each date is known but the amount can vary within a per-date ceiling.

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

The schedule object is the same shape as Fixed Defined Schedule, except each paymentSchedule entry takes maxAmount instead of amount.

When To Use

Use VariableDefinedSchedule when each payment has a specific calendar date and a maximum amount for that date. The final debit can be lower than the ceiling based on the contract with the payer. The dates need not follow a regular daily, weekly, monthly, or yearly pattern.

Typical products:

Project completion-based payments
Staged billing where dates are fixed but executed amounts can vary up to a per-date maximum

For a fixed amount per date on the same model, use Fixed Defined Schedule.

Example use case

A payer agrees to four payments to a service provider on a non-regular schedule. Each date has a known maximum amount. The amounts you initiate can be lower than those ceilings when contractual conditions are met.

Instructions

Field	Presence	Description
`paymentSchedule`	Required	Non-empty list of dated max amounts. Domestic max 53 entries.
`maxCumulativeAmount`	Optional	Maximum cumulative value of payments over the lifetime of the consent. When set, must equal the total of all entry `maxAmount` values listed in `paymentSchedule`.
`maxCumulativeNumberOfPayments`	Optional	Maximum cumulative number of payments over the lifetime of the consent. When set, must equal the number of payments listed in `paymentSchedule`. Must be greater than zero.
`isInternationalPayment`	Optional	When `true`, `paymentSchedule` must contain exactly one entry.

`paymentSchedule[]` entry

Field	Presence	Description
`paymentExecutionDate`	Required	Future date (not today). Unique within the array.
`maxAmount`	Required	Ceiling for that date. Must be greater than zero.

Example Request

Complete body for a four-milestone Variable Defined Schedule. When you include lifetime caps, maxCumulativeAmount is the sum of the entry ceilings (AED 15000.00) and maxCumulativeNumberOfPayments is 4.

{
  "type": "VariableDefinedSchedule",
  "creditorType": "MERCHANT",
  "creditorReference": "PROJECT88",
  "merchantReference": "vds-project-88",
  "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": 4,
    "maxCumulativeAmount": { "amount": "15000.00", "currency": "AED" },
    "paymentSchedule": [
      {
        "paymentExecutionDate": "2026-09-01",
        "maxAmount": { "amount": "2500.00", "currency": "AED" }
      },
      {
        "paymentExecutionDate": "2026-10-15",
        "maxAmount": { "amount": "4000.00", "currency": "AED" }
      },
      {
        "paymentExecutionDate": "2026-12-01",
        "maxAmount": { "amount": "3500.00", "currency": "AED" }
      },
      {
        "paymentExecutionDate": "2027-02-01",
        "maxAmount": { "amount": "5000.00", "currency": "AED" }
      }
    ]
  }
}

What Fails

Spare rejects the create when:

paymentSchedule is missing or empty
paymentSchedule has more than 53 entries on a domestic request
isInternationalPayment is true and paymentSchedule has more than one entry
any paymentExecutionDate is today or in the past
two or more entries share the same paymentExecutionDate
an entry is missing maxAmount, or the nested amount value is zero or negative
maxCumulativeAmount is set and does not equal the sum of all entry maxAmount values
maxCumulativeNumberOfPayments is set and does not equal the number of paymentSchedule entries
maxCumulativeNumberOfPayments is set to zero or a negative value
root maxCumulativeAmount is negative

See Error codes for response shapes.

Continue learning

Payment Request Deep Dives

Shared root fields and the payment-type picker.

Fixed Defined Schedule

Fixed amount per date on an explicit date list.

Payment Requests

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

When To Use

Instructions

paymentSchedule[] entry

Example Request

What Fails

On this page

`paymentSchedule[]` entry