Consent

A consent defines what the customer is agreeing to and the boundaries within which the merchant may collect future payments. It is captured during a first_in_series payment session by passing mandate_options, and becomes the durable record of customer authorisation that governs every subsequent next_in_series payment.

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.

A consent is made up of the mandate type, amount, recurrence, validity period, and maximum number of payments. Each is covered below.

Mandate Type

The type field declares the kind of mandate the customer is consenting to.

Scheduled mandates

The customer consents to collection on a fixed cadence, defined by recurrence.

{
  "mandate_options": {
    "type": "scheduled",
    "recurrence": {
      "type": "monthly",
      "interval_count": 1
    }
  }
}

Payment methods whose consent surface displays an interval (for example, Capitec VRP) require scheduled or installment.

On-demand mandates

The customer consents to collection without a fixed cadence. Use for wallet top-ups, card-on-file ad-hoc charges, or any flow where the customer has not agreed to a rhythm.

{
  "mandate_options": {
    "type": "on_demand"
  }
}

Payment methods that require a cadence at consent (for example, Capitec VRP) are not eligible on on_demand. Use scheduled instead.

Installment mandates

The customer consents to a fixed payment plan: a defined number of payments totalling total_amount. The structure is set by terms:

periodic: equal payments on a fixed cadence. recurrence and max_occurrences are both required inside terms.
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
      },
      "max_occurrences": 4
    }
  }
}

A 3-payment fixed plan with a larger final payment:

{
  "mandate_options": {
    "type": "installment",
    "total_amount": 100000,
    "terms": {
      "type": "fixed",
      "items": [
        { "amount": 30000, "due_date": "2026-04-01" },
        { "amount": 30000, "due_date": "2026-05-01" },
        { "amount": 40000, "due_date": "2026-06-01" }
      ]
    }
  }
}

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. Not available on type: on_demand (no cadence is consented). For type: installment, recurrence is set inside terms. 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 month:

{
  "mandate_options": {
    "type": "scheduled",
    "recurrence": {
      "type": "monthly",
      "interval_count": 1
    }
  }
}

Payments every week on Mondays:

{
  "mandate_options": {
    "type": "scheduled",
    "recurrence": {
      "type": "weekly",
      "interval_count": 1,
      "on": {
        "days": ["mon"]
      }
    }
  }
}

Payments every week:

{
  "mandate_options": {
    "type": "scheduled",
    "recurrence": {
      "type": "weekly",
      "interval_count": 1
    }
  }
}

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.

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.

For full configuration examples, see Mandates: Examples. For the complete schema, see the API Reference.

Getting Started

Collect

Stored Value

Billing

Network

Reconciliation and Reporting

Help

Mandate Type

Scheduled mandates

On-demand mandates

Installment mandates

Amount

Recurrence

Validity Period

Max Occurrences

​Mandate Type

​Scheduled mandates

​On-demand mandates

​Installment mandates

​Amount

​Recurrence

​Validity Period

​Max Occurrences

Mandate Type

Scheduled mandates

On-demand mandates

Installment mandates

Amount

Recurrence

Validity Period

Max Occurrences