v1

latestOpenAPI 3.1.0© Modulr Finance2026-08-04207430590.4 KB

Direct Debits

Create the collection schedule for the given mandate-id.

Creates a Direct Debit collection schedule; the agreed to framework for the collections for the given mandate-id. This could be a single collection or multiple and includes the frequency and amounts of the planned payments.

post/mandates/{mandateId}/collectionschedules

Path parameters

mandateIdstring required

Id of mandate to create collection for.

Request body

Frequency for direct-debit collection. Can be one of: ONCE, WEEKLY, EVERY_TWO_WEEKS, EVERY_FOUR_WEEKS, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY.

numberOfPaymentsinteger required

Number of payments for direct-debit collection, must be '1' where frequency is 'ONCE'.

firstPaymentAmountnumber

Amount of the first collection payment. Note: your item limit is set during onboarding will be lower than field maximum and Bacs scheme item limit of £20m.

firstPaymentDatestring

Date of the first collection payment, format must be: yyyy-MM-dd

regularPaymentAmountnumber

Amount of the regular collection payments following first collection amount. Does not apply where the frequency is 'ONCE'. Note: your item limit is set during onboarding will be lower than field maximum and Bacs scheme item limit of £20m

regularPaymentStartDatestring

Start date of the regular collection payment, format: yyyy-MM-dd Note: Does not apply where the frequency is 'ONCE'.

currencystring required

Currency in which payment should be made. Must be 'GBP' currently.

externalReferencestring

External Reference for collection schedule, should contain only alphanumeric characters, underscore, hyphen and space. For your internal reconciliation only, not sent to Bacs scheme.

collectionReferencestring

An optional additional collection specific reference to be appended to the reference of the mandate. This is concatenated after the core reference of the mandate, and will be truncated if combined reference is >18 characters. Should only contain alphanumeric characters, dot, ampersand, forward-slash and hyphen only.

collectionCorrelationNamestring

(If enabled by Modulr) an optional collection specific reference appended to abbreviated SU name for the given collection schedule. If feature not enabled, any parameter supplied will be ignored. When is enabled, this value is concatenated to a Service User Name abbreviation (set by Modulr) to form a Service User name containing extra information that can be used by payer to correlate (identify) transaction easily. Characters restricted to: alphanumeric characters, numbers, space, dot, ampersand, forward-slash and hyphen only.

Example request

{
  "firstPaymentDate": "2018-01-10",
  "regularPaymentStartDate": "2018-01-10",
  "externalReference": "REFERENCE - 12",
  "collectionReference": "ABCD - EFGH",
  "collectionCorrelationName": "TEST/NAME-1.2"
}

Response

idstring required

Unique id for direct-debit collection.

frequencystring required

Frequency for direct-debit collection

numberOfPaymentsinteger required

Number of payments for direct-debit collection

firstPaymentAmountnumber

Amount of the first collection payment

firstPaymentDatestring

Date of the first collection payment. Format is yyyy-MM-dd.

regularPaymentAmountnumber

Amount of the regular collection payments

regularPaymentStartDatestring

Start date of the regular collection payment. Format is yyyy-MM-dd.

createdDatestring date-time required

Datetime when direct-debit collection was created.Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000

statusstring required

Status of the direct-debit collection. Can be one of

externalReferencestring

collectionReferencestring

Example response

{
  "id": "Q0000001",
  "frequency": "MONTHLY",
  "numberOfPayments": 12,
  "firstPaymentDate": "2018-01-10",
  "regularPaymentStartDate": "2018-01-10",
  "createdDate": "2017-01-28T01:01:01+0000",
  "status": "PROCESSING"
}