Skip to main content
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 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 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 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 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 (VRP / top-up)

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
    }
  }
}
Some providers require an explicit recurrence interval as part of the consent. If you intend to use a provider that requires this (such as Capitec VRP), include recurrence on the on_demand mandate. Without it, those providers will not be available as payment method options at checkout.
{
  "mandate_options": {
    "type": "on_demand",
    "amount": {
      "max": 5000
    },
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "monthly",
      "interval_count": 1
    }
  }
}

​
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, 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
    }
  }
}