Skip to main content
Mandates are created during a first_in_series payment session, when the customer authorises the saving of their payment method for future use. Subsequent payments are then initiated programmatically via next_in_series sessions, relying on the existing mandate. When creating a first_in_series session, you can pass a mandate_options object to define the boundaries and constraints of the mandate, specifying what the customer is consenting to.
Providing mandate_options is optional. Omitting it entirely creates an unconstrained mandate: valid indefinitely, for any amount, any number of times, with no declared intent.
The fields below cover the consent concern: what the customer is agreeing to, and the boundaries on what the merchant may collect. Period limits, spacing, allowed days, and retry behaviour are controls, covered in Controls.
For installment mandates, total_amount and terms replace amount, recurrence, and max_occurrences as the primary consent fields. See Installment mandates below.

​
Amount

Defines the amount the customer consents to in future payments. Fixed amount: the exact amount that may be collected each time: 
{
  "mandate_options": {
    "type": "scheduled",
    "amount": 2000
  }
}
Amount range: a minimum and/or maximum the payment may fall within: 
{
  "mandate_options": {
    "type": "on_demand",
    "amount": {
      "min": 1000,
      "max": 5000
    }
  }
}
If not specified, the amount from the originating first_in_series session is used as the consent ceiling and applies to all subsequent next_in_series payments under the mandate.

​
Recurrence

Defines the consented payment cadence: how frequently the customer has agreed to be charged. Required for type: scheduled. Optional for type: on_demand, where it can be included if the merchant intends to collect on a consistent cadence or wants providers to derive the implicit period window from it. This is used by the platform to schedule payments automatically when subscription_options is provided, and by providers to derive the implicit period window when no explicit period_limits are set. Payments every month on the 1st: 
{
  "mandate_options": {
    "type": "scheduled",
    "recurrence": {
      "type": "monthly",
      "interval_count": 1,
      "on": {
        "type": "day_of_month",
        "days": [1]
      }
    }
  }
}
Payments every week on Mondays: 
{
  "mandate_options": {
    "type": "scheduled",
    "recurrence": {
      "type": "weekly",
      "interval_count": 1,
      "on": {
        "days": ["mon"]
      }
    }
  }
}
If not specified, the mandate places no cadence constraint on collections. Payments may be collected at any frequency within the other active mandate constraints.

​
Validity Period

Restricts the mandate to a specific date range. Payments outside this range will be rejected. A mandate valid throughout 2026: 
{
  "mandate_options": {
    "type": "on_demand",
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    }
  }
}
If start_date is omitted, the mandate is active immediately from the date of creation. If end_date is omitted, the mandate does not expire.
All date boundaries are evaluated in UTC by default. Set timezone to an IANA timezone string to apply a consistent timezone across validity dates, period windows, and execution constraints:
{
  "mandate_options": {
    "type": "scheduled",
    "timezone": "Africa/Johannesburg"
  }
}
When using period_limits, set start_date to align with your period boundary.This ensures the first window is a full period and the mandate active date and window start are in sync. If they are misaligned, the first window may be partial and charges could occur closer together than expected across the boundary.

​
Max Occurrences

Caps the total number of successful payments allowed under the mandate. A mandate limited to 12 successful payments in total: 
{
  "mandate_options": {
    "type": "scheduled",
    "max_occurrences": 12
  }
}
If not specified, occurrences are unlimited.

​
Mandate Type

The type field declares the kind of mandate the customer is consenting to. It is the first field to set when configuring mandate_options.

​
Scheduled mandates

The customer consents to recurring payments on an explicit cadence. recurrence is required and forms part of the consent declaration. Use this for subscriptions and regular billing cycles where the merchant commits to a defined payment schedule. 
{
  "mandate_options": {
    "type": "scheduled",
    "recurrence": {
      "type": "monthly",
      "interval_count": 1,
      "on": {
        "type": "day_of_month",
        "days": [1]
      }
    }
  }
}

​
On-demand mandates

The customer consents to merchant-initiated collections where recurrence is not a required part of the consent. Use this for variable recurring payments (VRP), wallet top-ups, and usage-based billing. recurrence and subscription_options are both available and may be used if the merchant wants to automate collections on a consistent cadence. Setting type: on_demand with no other fields is equivalent to omitting mandate_options entirely, but explicitly records the merchant’s intent. Setting type is recommended in all cases. 
{
  "mandate_options": {
    "type": "on_demand",
    "amount": {
      "max": 5000
    },
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "period_limits": {
      "period": "month",
      "max_count": 10,
      "max_amount": 20000
    }
  }
}

​
Installment mandates

The customer consents to a fixed payment plan: a defined number of payments totalling total_amount. Unlike scheduled mandates, the consent is structured around the plan as a whole rather than an open-ended cadence. The payment structure is defined in terms, which is polymorphic:
  • terms.type: periodic: equal payments on a regular cadence. recurrence and max_occurrences are both required inside terms, fully defining the schedule at consent time.
  • terms.type: fixed: an explicit schedule with specific amounts and due dates per installment. Use when payment amounts vary or dates are irregular.
A 4-payment monthly installment plan totalling 1000.00 ZAR: 
{
  "mandate_options": {
    "type": "installment",
    "total_amount": 100000,
    "terms": {
      "type": "periodic",
      "recurrence": {
        "type": "monthly",
        "interval_count": 1,
        "on": {
          "type": "day_of_month",
          "days": [1],
          "adjustment": "nearest_weekday"
        }
      },
      "max_occurrences": 4,
      "amount": 25000
    },
    "validity_period": {
      "start_date": "2026-04-01",
      "end_date": "2026-07-31"
    }
  }
}
A 3-payment fixed plan with a larger final payment: 
{
  "mandate_options": {
    "type": "installment",
    "total_amount": 100000,
    "terms": {
      "type": "fixed",
      "adjustment": "nearest_weekday",
      "items": [
        { "amount": 30000, "due_date": "2026-04-01" },
        { "amount": 30000, "due_date": "2026-05-01" },
        { "amount": 40000, "due_date": "2026-06-01" }
      ]
    }
  }
}
For both periodic and fixed terms, subscription_options may be provided to automate collections. When omitted, each payment must be initiated via next_in_series sessions.
Subscription automation for fixed terms is coming soon. Currently, each installment must be initiated via next_in_series sessions on the due dates defined in items. Subscription support is available today for periodic terms.
Some payment providers require a declared collection interval at consent registration. For fixed terms, add a recurrence hint to terms to satisfy this requirement. It has no scheduling role: payment dates are defined by items. The platform derives amount.max for provider registration from the largest amount across the installment items. 
{
  "mandate_options": {
    "type": "installment",
    "total_amount": 100000,
    "terms": {
      "type": "fixed",
      "recurrence": {
        "type": "monthly",
        "interval_count": 1
      },
      "adjustment": "nearest_weekday",
      "items": [
        { "amount": 30000, "due_date": "2026-04-01" },
        { "amount": 30000, "due_date": "2026-05-01" },
        { "amount": 40000, "due_date": "2026-06-01" }
      ]
    }
  }
}