Skip to main content
The examples below show mandate_options and subscription_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 subscription collecting 5.00 ZAR every day throughout 2026: 
{
  "mandate_options": {
    "type": "scheduled",
    "amount": 500,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "recurrence": {
      "type": "daily",
      "interval_count": 1
    }
  },
  "subscription_options": {}
}

​
Weekly billing

A subscription collecting 10.00 ZAR every Monday throughout 2026: 
{
  "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"]
      }
    }
  },
  "subscription_options": {}
}

​
Monthly billing

A subscription collecting 20.00 ZAR on the 1st of each month throughout 2026: 
{
  "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"
      }
    }
  },
  "subscription_options": {}
}

​
Quarterly billing

A subscription collecting 60.00 ZAR on the 1st of every third month throughout 2026: 
{
  "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"
      }
    }
  },
  "subscription_options": {}
}

​
Annual billing

A subscription collecting 240.00 ZAR on January 1st each year, valid for three years: 
{
  "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 }
        ]
      }
    }
  },
  "subscription_options": {}
}

​
Installment (periodic)

A subscription automating 4 equal monthly installments of 250.00 ZAR, totalling 1000.00 ZAR, collected at 9:00 AM on the 1st of each month: 
{
  "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"
  },
  "subscription_options": {
    "active_period": {
      "start_date": "2026-04-01",
      "end_date": "2026-07-31"
    },
    "amount": 25000,
    "scheduled_time": "09:00"
  }
}

​
Complete Example

A subscription for monthly payments of 20.00 ZAR on the 1st and 15th of each month, active throughout 2026, with a nearest-weekday adjustment: 
{
  "mandate_options": {
    "type": "scheduled",
    "amount": 2000,
    "validity_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "max_occurrences": 24,
    "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": 2,
      "max_amount": 4000
    }
  },
  "subscription_options": {
    "active_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    },
    "amount": 2000,
    "scheduled_time": "09:00"
  }
}