Fixed On Demand

FixedOnDemand creates a mandate where the payer pre-authorizes a fixed 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 Fixed On Demand instructions only.

When To Use

Use FixedOnDemand when the amount is fixed and you initiate each payment at any time after the payer authorizes the consent. There is no fixed payment date list.

Typical products:

Account top-up
Fixed-amount wallet or prepaid reloads you trigger when your product needs them

For a variable amount with the same trigger model, use Variable On Demand.

Example use case

A payer wants to top up a savings account at another bank. The savings account allows up to AED 6,000 per year and AED 500 per month. The payer authorizes a fixed individual payment of AED 100. Your service triggers that AED 100 debit whenever the payer's balance exceeds a threshold by at least AED 100.

Instructions

Field	Presence	Description
`periodicSchedule`	Required	Consent window, fixed debit amount, rolling period (`frequency`), and `controls`.
`maxCumulativeAmount`	Optional	Maximum cumulative value of payments over the lifetime of the consent. When set, must be greater than `periodicSchedule.amount`.
`maxCumulativeNumberOfPayments`	Optional	Maximum cumulative number of payments over the lifetime of the consent. Must be greater than zero when set.

`periodicSchedule`

Field	Presence	Description
`frequency`	Required	Rolling period for `controls`: `Day`, `Week`, `Month`, or `Year`. Limits in `controls` reset at the start of each new period.
`startDate`	Required	Mandate window start. May be today or a future date.
`endDate`	Required	Inclusive end bound. Must be after `startDate` and in the future.
`amount`	Required	Fixed amount for each triggered debit. Must be greater than zero.
`controls`	Required (partial)	Rolling per-period limits. You must supply at least one of `maxCumulativeAmountPerPeriod` or `maxCumulativeNumberOfPaymentsPerPeriod`.

`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.

Field	Presence	Description
`maxCumulativeAmountPerPeriod`	Conditional	Maximum cumulative value of payments within the defined period. When set, must be greater than zero and greater than `periodicSchedule.amount`. Provide this field, or `maxCumulativeNumberOfPaymentsPerPeriod`, or both.
`maxCumulativeNumberOfPaymentsPerPeriod`	Conditional	Maximum cumulative number of payments within the defined period. When set, must be greater than zero. Provide this field, or `maxCumulativeAmountPerPeriod`, or both.

Example Request

Complete body for a Fixed On Demand wallet top-up with a weekly rolling amount cap.

{
  "type": "FixedOnDemand",
  "creditorType": "MERCHANT",
  "creditorReference": "TOPUP22",
  "merchantReference": "fod-topup-22",
  "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": 5,
    "maxCumulativeAmount": { "amount": "200.00", "currency": "AED" },
    "periodicSchedule": {
      "frequency": "Week",
      "startDate": "2026-08-12",
      "endDate": "2027-08-01",
      "amount": { "amount": "2.50", "currency": "AED" },
      "controls": {
        "maxCumulativeAmountPerPeriod": { "amount": "100.00", "currency": "AED" }
      }
    }
  }
}

What Fails

Spare rejects the create when:

periodicSchedule is missing
frequency, startDate, endDate, or amount is missing inside periodicSchedule
amount is zero or negative
neither maxCumulativeAmountPerPeriod nor maxCumulativeNumberOfPaymentsPerPeriod is provided in controls
maxCumulativeAmountPerPeriod is set and is not greater than periodicSchedule.amount
maxCumulativeAmount is set and is not greater than periodicSchedule.amount
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.

Continue learning

Payment Request Deep Dives

Shared root fields and the payment-type picker.

Variable On Demand

Variable amount; you trigger each debit.

Mandates

How on-demand mandates work after create.

Payment Requests

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

When To Use

Instructions

periodicSchedule

controls (rolling period)

Example Request

What Fails

On this page

`periodicSchedule`

`controls` (rolling period)