Examples

The examples below show mandate_options configuration fragments for common billing patterns. They are passed as part of a first_in_series payment session request. See Quickstart: Recurring Payments for the full end-to-end flow.

Common Examples

Daily billing

A mandate authorising a fixed daily payment:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 500,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "daily",
      "interval_count": 1
    }
  }
}

Weekly billing

A mandate authorising one payment per week:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 1000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "weekly",
      "interval_count": 1
    }
  }
}

A mandate authorising one payment per week on Mondays:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 1000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "weekly",
      "interval_count": 1,
      "on": {
        "days": ["mon"]
      }
    }
  }
}

Monthly billing

A mandate authorising one payment per month:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 2000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "monthly",
      "interval_count": 1
    }
  }
}

A mandate authorising one payment per month on the 1st:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 2000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "monthly",
      "interval_count": 1,
      "on": {
        "type": "day_of_month",
        "days": [1],
        "adjustment": "nearest_weekday"
      }
    }
  }
}

Quarterly billing

A mandate authorising one payment per quarter:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 6000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "monthly",
      "interval_count": 3
    }
  }
}

A mandate authorising one payment per quarter on the 1st of the month:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 6000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "monthly",
      "interval_count": 3,
      "on": {
        "type": "day_of_month",
        "days": [1],
        "adjustment": "nearest_weekday"
      }
    }
  }
}

Annual billing

A mandate authorising one payment per year:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 24000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2028-12-31"
    },
    "recurrence": {
      "type": "yearly",
      "interval_count": 1
    }
  }
}

A mandate authorising one payment per year on January 1st:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 24000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2028-12-31"
    },
    "recurrence": {
      "type": "yearly",
      "interval_count": 1,
      "on": {
        "type": "day_of_year",
        "dates": [
          { "month": 1, "day": 1 }
        ]
      }
    }
  }
}

On-demand (card top-up)

A mandate authorising merchant-initiated collections of up to 50.00 ZAR:

{
  "mandate_options": {
    "type": "on_demand",
    "amount": {
      "max": 5000
    },
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    }
  }
}

A mandate authorising merchant-initiated collections of up to 50.00 ZAR, no more than 10 times per month, capped at 200.00 ZAR monthly:

{
  "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
    }
  }
}

on_demand mandates do not carry a recurrence. Payment methods whose consent surface requires an interval (such as Capitec VRP) are not eligible on on_demand. See the next example for the VRP equivalent of this pattern.

On-demand (Capitec VRP top-up)

Capitec VRP does not support true on-demand collection; its consent surface always requires a cadence. A scheduled mandate with a daily recurrence approximates it instead, authorising merchant-initiated collections of up to 50.00 ZAR on any day:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": {
      "max": 5000
    },
    "recurrence": {
      "type": "daily",
      "interval_count": 1
    },
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    }
  }
}

See Recurring Payments for how mandate type and payment method eligibility fit together.

Installment (periodic)

A mandate for 4 equal monthly payments of 250.00 ZAR, 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"
    },
    "timezone": "Africa/Johannesburg",
    "retry_policy": {
      "max_retries": 2,
      "min_days_between_retries": 3,
      "max_days_since_failure": 14
    }
  }
}

Installment (fixed)

A mandate for 3 payments on specific dates with a larger final payment, totalling 1000.00 ZAR:

{
  "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" }
      ]
    },
    "validity_period": {
      "start_date": "2026-04-01",
      "end_date": "2026-06-30"
    },
    "timezone": "Africa/Johannesburg",
    "retry_policy": {
      "max_retries": 2,
      "min_days_between_retries": 3,
      "max_days_since_failure": 14
    }
  }
}

Some providers require a declared collection interval as part of consent registration. For fixed terms, add a recurrence hint to terms to satisfy this requirement. It has no scheduling role: payment dates are still 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" }
      ]
    }
  }
}

Complete Example

A mandate for a monthly subscription capped at 12 payments over one year:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 2000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "max_occurrences": 12,
    "recurrence": {
      "type": "monthly",
      "interval_count": 1
    }
  }
}

A mandate for a monthly subscription capped at 12 payments over one year, scheduled on the 1st and 15th of each month, with no more than one payment per month, and up to 3 retries within 30 days of a failure:

{
  "mandate_options": {
    "type": "scheduled",
    "amount": 2000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "max_occurrences": 12,
    "timezone": "Africa/Johannesburg",
    "recurrence": {
      "type": "monthly",
      "interval_count": 1,
      "on": {
        "type": "day_of_month",
        "days": [1, 15],
        "adjustment": "nearest_weekday"
      }
    },
    "period_limits": {
      "period": "month",
      "max_count": 1,
      "max_amount": 2000
    },
    "retry_policy": {
      "max_retries": 3,
      "min_days_between_retries": 3,
      "max_days_since_failure": 30
    }
  }
}

Getting Started

Collect

Stored Value

Billing

Network

Reconciliation and Reporting

Help

Common Examples

Daily billing

Weekly billing

Monthly billing

Quarterly billing

Annual billing

On-demand (card top-up)

On-demand (Capitec VRP top-up)

Installment (periodic)

Installment (fixed)

Complete Example

​Common Examples

​Daily billing

​Weekly billing

​Monthly billing

​Quarterly billing

​Annual billing

​On-demand (card top-up)

​On-demand (Capitec VRP top-up)

​Installment (periodic)

​Installment (fixed)

​Complete Example

Common Examples

Daily billing

Weekly billing

Monthly billing

Quarterly billing

Annual billing

On-demand (card top-up)

On-demand (Capitec VRP top-up)

Installment (periodic)

Installment (fixed)

Complete Example