Variable On Demand

VariableOnDemand creates a mandate where the payer pre-authorizes up to a max amount per debit, and you trigger each debit later. Payments can be initiated at any time within the consent window. There is no fixed payment date list.

Shared root fields (type, creditorAccount, redirects, and the rest) live on the Payment Request Deep Dives intro. This page covers Variable On Demand instructions and the type-specific root field additionalCreditorAccounts.

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

When To Use

Use VariableOnDemand when each debit amount can vary up to a defined maximum, and you initiate payments at any time after the payer authorizes the consent. There is no fixed payment date list.

Typical products:

• Account sweeping
• Cab booking and similar apps that charge when a trip completes
• Point-of-sale or in-app purchases where amount and timing depend on the payer's activity

For a fixed amount with the same trigger model, use Fixed On Demand.

Type-Specific Root Fields

Instructions

Minimum control set

You must provide at least two of these three parameters:

1. maxCumulativeAmount
2. controls.maxCumulativeAmountPerPeriod (must be greater than periodicSchedule.maxAmount)
3. controls.maxCumulativeNumberOfPaymentsPerPeriod

periodicSchedule

controls (rolling period)

controls applies to on-demand types only. It sets limits for one frequency period. When that period ends, the counters reset and the same limits apply again.

Example: frequency is Week and maxCumulativeAmountPerPeriod is AED 100. Within that week you may initiate debits up to AED 100 in total. Anything beyond AED 100 in the same week is rejected. The AED 100 allowance resets at the start of the next week.

Example Request

Complete body for a Variable On Demand balance sweep. The example meets the minimum control set with maxCumulativeAmount and maxCumulativeAmountPerPeriod.

{
  "type": "VariableOnDemand",
  "creditorType": "MERCHANT",
  "creditorReference": "SWEEP01",
  "merchantReference": "vod-sweep-01",
  "purpose": "GDDS",
  "creditorAccount": {
    "schemeName": "IBAN",
    "identification": "AE070331234567890123456",
    "name": "Acme Trading LLC"
  },
  "additionalCreditorAccounts": [
    {
      "schemeName": "IBAN",
      "identification": "AE070331234567890123457",
      "name": "Acme Settlements LLC"
    }
  ],
  "successRedirectUrl": "https://merchant.example/payments/success",
  "failureRedirectUrl": "https://merchant.example/payments/failure",
  "instructions": {
    "maxCumulativeNumberOfPayments": 20,
    "maxCumulativeAmount": { "amount": "200.00", "currency": "AED" },
    "periodicSchedule": {
      "frequency": "Week",
      "startDate": "2026-08-12",
      "endDate": "2027-08-01",
      "maxAmount": { "amount": "50.00", "currency": "AED" },
      "controls": {
        "maxCumulativeAmountPerPeriod": { "amount": "100.00", "currency": "AED" }
      }
    }
  }
}

What Fails

Spare rejects the create when:

• additionalCreditorAccounts is set on any type other than VariableOnDemand
• Primary plus additionalCreditorAccounts total more than 10 accounts
• An account in additionalCreditorAccounts duplicates creditorAccount or another additional entry by scheme + identification
• periodicSchedule is missing
• frequency, startDate, endDate, or maxAmount is missing inside periodicSchedule
• maxAmount is zero or negative
• fewer than two of maxCumulativeAmount, maxCumulativeAmountPerPeriod, and maxCumulativeNumberOfPaymentsPerPeriod are provided
• maxCumulativeAmountPerPeriod is set and is not greater than periodicSchedule.maxAmount
• maxCumulativeAmount is set and is not greater than periodicSchedule.maxAmount
• root maxCumulativeAmount is negative
• controls.maxCumulativeAmountPerPeriod is set to zero or a negative value
• maxCumulativeNumberOfPayments or a per-period count cap is set to zero or a negative value
• startDate is in the past
• endDate 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.