Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.momentco.io/llms.txt

Use this file to discover all available pages before exploring further.

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.

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