Recurrence Schedule

Recurrence Schedules are used to automatically take payments on a regular basis, according to a defined schedule.

For Direct Debits, a Payment must happen at least every 12 months, if not the Direct debit is cancelled at 13 months by the paying bank.

If subscribed, SmarterPay Cloud will notify you, via a webhook, whenever the state of a Recurrence Schedule changes.

Please note that in the event of a mandate being cancelled either by a requested change or a BACS report change, any recurrence schedules will be cancelled along with any unsubmitted payments attached to the mandate.

Method Purpose
POST Create a Recurrence Schedule
PUT Update a Recurrence Schedule
DELETE Disable a Recurrence Schedule
GET (Singular) Return Recurrence Schedule details
GET (List) Return Recurrence Schedule details in a list

POST

Action: Create a Recurrence Schedule.
Method: POST
URL: https://api.smarterpaycloud.com/service.svc/recurrenceschedule

Request Parameters - Ongoing Schedule

Property Mandatory Description
amount True Amount in pence – no decimal point
auddis True Unique auddis identifier
collection_day True Set to either “1” – “28” or “last day”, this is not required on weekly collections
collection_period True Can be set to either monthly or weekly
collection_stretch True This is the collection stretch of the period, for example setting the field “1” would be every cycle of the collection_period
custom_reference False Custom reference text (Maximum 50 characters) - Will be passed to created payments, if set.
description True description of the recurrence schedule (Maximum 44 characters)
end_date False 10 digit date, will be ignored if left blank or null
firstCollectionInSameMonthAsNextCollection False Default is “False”. When set to “True” will allow the first two collections in the same month. This can happen when the first collection date is less than the collection day.
first_collection_amount True First Collection Amount
first_collection_date False When the first collection will be attempted. Will use start date if not supplied
start_date True 10 digit start date in the format of “YYYY-MM-DD”
type False If not specified will use “DDOngoingPayment”.

Request Sample - Ongoing Schedule

{
    "recurrence_schedule": {
        "amount": "2250",
        "auddis": "REFP01006",
        "collection_day": "04",
        "collection_period": "monthly",
        "collection_stretch": "1",
	"custom_reference": "custom ref 04",
        "description": "Payment Schedule",
        "firstCollectionInSameMonthAsNextCollection": false,
        "first_collection_amount": "2250",
        "first_collection_date": "2021-07-30",
        "start_date": "2021-07-30",
	"type":"DDOngoingPayment"      
    }
}

Request Parameters - Payment Plan

Property Mandatory Description
amount True Amount in pence – no decimal point
auddis True Unique auddis identifier
collection_day True Set to either “1” – “28” or “last day”, this is not required on weekly collections
collection_period True Can be set to either monthly or weekly
collection_stretch True This is the collection stretch of the period, for example setting the field “1” would be every cycle of the collection_period
custom_reference False Custom reference text (Maximum 50 characters) - Will be passed to created payments, if set.
description True description of the recurrence schedule (Maximum 44 characters)
end_date False 10 digit date, will be ignored if left blank or null
firstCollectionInSameMonthAsNextCollection False Default is “False”. When set to “True” will allow the first two collections in the same month. This can happen when the first collection date is less than the collection day.
first_collection_date False When the first collection will be attempted. Will use start date if not supplied
installments True For a Payment Plan - Used to specify the number of payments to collect the amount over.
start_date True 10 digit start date in the format of “YYYY-MM-DD”
type True For a Payment Plan needs to be “DDPaymentPlan”.

Request Sample - Payment plan

{
    "recurrence_schedule": {
        "amount": "2250",
        "auddis": "REFP01006", 
        "collection_day": "04",
        "collection_period": "monthly",
        "collection_stretch": "1",
	"custom_reference": "custom ref 04",
	"description": "Monthly Subscription",
	"end_date": null,
        "firstCollectionInSameMonthAsNextCollection": false,
        "first_collection_date": "2021-07-30",
	"installments":"3",
        "start_date": "2021-07-30",
	"type":"DDPaymentPlan"
    }
}

Response Parameters

Property Description
amount Amount
auddis Auddis reference
card_id For a “cardpayment” schedule - Card ID to be used for taking payments
collection_day Can be either “1” - “28” or “last day”
collection_period Can be set to either monthly or weekly
collection_stretch Stretch of collection period
created_at Datetime formatted as ISO8601
custom_reference Custom reference text
description Reference description – will be included in outgoing email if enabled
end_date 10 digit date in the format of “YYYY-MM-DD”
firstCollectionInSameMonthAsNextCollection Will be “false”. This can be used in the PUT to override default behaviour.
first_collection_amount Amount that will be taken for the first collection
first_collection_date When the first collection will be attempted
id Unique identifier
installments For a “DDPaymentPlan” schedule - Total number of installments for the schedule.
mandate Id of the parent Mandate
next_collection_date Next collection date
payment_type Type of payment for the Schedule. Can be either “cardpayment” or “directdebit”
start_date 10 digit date in the format of “YYYY-MM-DD”
status Returns “active” or “inactive”
type Type of Schedule. Can be either “DDOngoingPayment” or “DDPaymentPlan”
upcoming_payments JSON formatted collections

Response Sample

{
    "recurrence_schedule": {
        "amount": "2532",
        "auddis": "FBMAN02814872",
        "card_id": "",
        "collection_day": "19",
        "collection_period": "monthly",
        "collection_stretch": "1",
        "created_at": "2022-05-17T12:09:19Z",
        "custom_reference": "",
        "description": "",
        "end_date": "",
        "firstCollectionInSameMonthAsNextCollection": false,
        "first_collection_amount": "2532",
        "first_collection_date": "2022-05-19",
        "id": "FTBRS00112373",
        "installments": "",
        "mandate": "M01741EJ519Y51P3XGL",
        "next_collection_date": "2022-06-20",
        "payment_type": "DirectDebit",
        "start_date": "2022-05-19",
        "status": "active",
        "type": "DDOngoingPayment",
        "upcoming_payments": "[{\"collection_date\":\"2022-06-20\",\"amount\":\"2532\"},{\"collection_date\":\"2022-07-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-08-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-09-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-10-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-11-21\",\"amount\":\"2532\"},{\"collection_date\":\"2022-12-19\",\"amount\":\"2532\"}]"
    }
}

Action: Update a Recurrence Schedule.
Method: PUT
URL: https://api.smarterpaycloud.com/service.svc/recurrenceschedule/{ID}

Request Parameters - Ongoing Schedule

Property Mandatory Description
amount False Changes the ongoing collection Amount. Amount is in pence. Upcoming Payments are regenerated to relect the ongoing amount change.
collection_day False Changes the collection day for the schedule. Valid options are “1” - “28” or “last day”. Does NOT change the next collection date. Upcoming Payments are regenrated to reflect the change of the ongoing collection date.
collection_stretch False Changes the collection Stretch of the selected Period. Upcoming Payments are regenerated to reflect the change of collection Stretch.
end_date False Changes the End Date of the schedule. Valid options are either a date in the future or empty “” string to clear the date. Upcoming Payments are regenerated to reflect the change of End Date.
firstCollectionInSameMonthAsNextCollection False Default is “False”. When set to “True” will allow the first two collections in the same month. This can happen when the first collection date is less than the collection day.
first_collection_amount False Changes the First Collection Amount, if NOT already taken. Upcoming Payments are regenerated to reflect the First Collection Amount change, if applicable.
first_collection_date False Changes the First collection Date, if NOT already taken. Upcoming Payments are regenerated to reflect the First Collection Date change, if applicable.
next_collection_date False Changes the Next Collection Date only. If no collections have been made will also change the First Collection Date. Upcoming Payments are regenerated to reflect the change in Next Collection Date.
upcoming_payments False* Allows changes to the Upcoming Payment Schedule.

NOTES:

  • The “upcoming_payments” property cannot be used in combination with any other Property.
  • At least one property, with valid value, needs to be passed in the PUT.
  • When the upcoming payments are regenerated, the system always takes into account non-banking days, and your advanced notice days.

Request Sample - Ongoing Schedule

{
    "recurrence_schedule": {
        "amount": "2250",
        "collection_day": "10",
        "end_date": "2022-01-10",
        "firstCollectionInSameMonthAsNextCollection": true,
        "first_collection_amount": "2300",
        "first_collection_date": "2021-09-13",
        "next_collection_date": "2021-09-13"
    }
}


Request Sample - Ongoing Schedule - upcoming_payments

{
    "recurrence_schedule": {
        "upcoming_payments": "[{\"collection_date\":\"2021-09-13\",\"amount\":\"2300\"},{\"collection_date\":\"2021-11-01\",\"amount\":\"2275\"},{\"collection_date\":\"2021-11-30\",\"amount\":\"2275\"},{\"collection_date\":\"2021-12-31\",\"amount\":\"2275\"}]"
    }
}


Request Parameters - Payment Plan

Property Mandatory Description
amount False Changes the Total Amount to be taken by the payment Plan. Amount is in pence. Upcoming Payments are regenerated to reflect the Instalment Amount change.
collection_day False Changes the collection day for the schedule. Valid options are “1” - “28” or “last day”. Does NOT change the next collection date. Upcoming Payments are regenerated to reflect the change of collection date.
collection_stretch False Changes the collection Stretch of the selected Period. Upcoming Payments are regenerated to reflect the change of collection Stretch.
firstCollectionInSameMonthAsNextCollection False Default is “False”. When set to “True” will allow the first two collections in the same month. This can happen when the first collection date is less than the collection day.
installments False Changes the number of Payments to collect the Amount. Upcoming Payments are regenerated to reflect the change of number of instalments, minus what's already been collected. The End Date may be updated as part of this change.
next_collection_date False Changes the Next Collection Date only. If no collections have been made will also change the First Collection Date. Upcoming Payments are regenerated to reflect the change in Next Collection Date.
upcoming_payments False* Allows changes to the Upcoming Payment Schedule. As this property cannot be used in combination with any other, the total amount and number of instalments must match what is set in the other properties.

NOTES:

  • The “upcoming_payments” property cannot be used in combination with any other Property.
  • At least one property, with valid value, needs to be passed in the PUT.
  • When the upcoming payments are regenerated, the system always takes into account non-banking days, and your advanced notice days.
  • Amount is the total of upcoming payments and payments already taken.
  • Instalments is the number of upcoming payments and payments already taken.

Request Sample - Payment Plan - properties

{
    "recurrence_schedule": {
        "amount": "2250",
        "collection_day": "10",
        "firstCollectionInSameMonthAsNextCollection": true,
        "installments": "8",
        "next_collection_date": "2021-09-13"
    }
}


Request Sample - Payment Plan - upcoming_payments

{
    "recurrence_schedule": {
        "upcoming_payments": "[{\"collection_date\":\"2021-09-13\",\"amount\":\"2300\"},{\"collection_date\":\"2021-11-01\",\"amount\":\"2275\"},{\"collection_date\":\"2021-11-30\",\"amount\":\"2275\"},{\"collection_date\":\"2021-12-31\",\"amount\":\"2275\"}]"
    }
}


Response Parameters

Property Description
amount Amount
auddis Auddis reference
card_id For a “cardpayment” schedule - Card ID to be used for taking payments
collection_day Can be either “1” - “28” or “last day”
collection_period Can be set to either monthly or weekly
collection_stretch Stretch of collection period
created_at Datetime formatted as ISO8601
custom_reference Custom reference text
description Reference description – will be included in outgoing email if enabled
end_date 10 digit date in the format of “YYYY-MM-DD”
firstCollectionInSameMonthAsNextCollection Will be “false”. This can be used in the PUT to override default behaviour.
first_collection_amount Amount that will be taken for the first collection
first_collection_date When the first collection will be attempted
id Unique identifier
installments For a “DDPaymentPlan” schedule - Total number of installments for the schedule.
mandate Id of the parent Mandate
next_collection_date Next collection date
payment_type Type of payment for the Schedule. Can be either “cardpayment” or “directdebit”
start_date 10 digit date in the format of “YYYY-MM-DD”
status Returns “active” or “inactive”
type Type of Schedule. Can be either “DDOngoingPayment” or “DDPaymentPlan”
upcoming_payments JSON formatted collections

Response Sample

{
    "recurrence_schedule": {
        "amount": "2532",
        "auddis": "FBMAN02814872",
        "card_id": "",
        "collection_day": "19",
        "collection_period": "monthly",
        "collection_stretch": "1",
        "created_at": "2022-05-17T12:09:19Z",
        "custom_reference": "",
        "description": "",
        "end_date": "",
        "firstCollectionInSameMonthAsNextCollection": false,
        "first_collection_amount": "2532",
        "first_collection_date": "2022-05-19",
        "id": "FTBRS00112373",
        "installments": "",
        "mandate": "M01741EJ519Y51P3XGL",
        "next_collection_date": "2022-06-20",
        "payment_type": "DirectDebit",
        "start_date": "2022-05-19",
        "status": "active",
        "type": "DDOngoingPayment",
        "upcoming_payments": "[{\"collection_date\":\"2022-06-20\",\"amount\":\"2532\"},{\"collection_date\":\"2022-07-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-08-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-09-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-10-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-11-21\",\"amount\":\"2532\"},{\"collection_date\":\"2022-12-19\",\"amount\":\"2532\"}]"
    }
}

Action: Disable a Recurrence Schedule.
Method: DELETE
URL: https://api.smarterpaycloud.com/service.svc/recurrenceschedule/{ID}

{ID} denotes ID of record.

Response Parameters

Property Description
amount Amount
auddis Unique auddis identifier
card_id For a “cardpayment” schedule - Card ID to be used for taking payments
collection_day Set to either “1” - “28” or “last day”
collection_period Can be set to either monthly or weekly
collection_stretch Stretch of collection period
created_at Datetime formatted as ISO8601
custom_reference Custom reference text
description Reference description – will be included in outgoing email if enabled
end_date 10 digit date in the format of “YYYY-MM-DD”
existing_card For a “cardpayment” schedule - is the card an existing card. Can be either “false” or “true”
first_collection_amount Amount that will be taken for the first collection
first_collection_date When the first collection will be attempted
id Unique identifier
installments For a “DDPaymentPlan” schedule - Total number of installments for the schedule.
next_collection_date Next collection date
payment_type Type of payment for the Schedule. Can be either “cardpayment” or “directdebit”
start_date 10 digit date in the format of “YYYY-MM-DD”
status Returns “active” or “inactive”
type Type of Schedule. Can be either “DDOngoingPayment” or “DDPaymentPlan”
upcoming_payments JSON formatted collections

Response Sample

{
    "recurrence_schedule": {
        "amount": "2250",
        "auddis": "REFP01006",
        "card_id": "",
        "collection_day": "04",
        "collection_period": "monthly",
        "collection_stretch": "1",
        "created_at": "2021-07-21T09:56:32Z",
        "custom_reference": "custom ref 04",
        "description": "Payment Schedule",
        "end_date": "",
        "firstCollectionInSameMonthAsNextCollection": false,
        "existing_card": false,
        "first_collection_amount": "2250",
        "first_collection_date": "2021-07-30",
        "id": "FTBRS00001435",
        "installments": "",
        "next_collection_date": "2021-07-30",
        "payment_type": "directDebit",
        "start_date": "2021-07-30",
        "status": "inactive",
        "type": "DDOngoingPayment",
        "upcoming_payments": "[]"
    }
}

Action: Return Recurrence Schedule details.
Method: GET
URL: https://api.smarterpaycloud.com/service.svc/recurrenceschedule/{ID}

{ID} denotes ID of record.

Response Parameters

Property Description
amount Amount
auddis Auddis reference
card_id For a “cardpayment” schedule - Card ID to be used for taking payments
collection_day Can be either “1” - “28” or “last day”
collection_period Can be set to either monthly or weekly
collection_stretch Stretch of collection period
created_at Datetime formatted as ISO8601
custom_reference Custom reference text
description Reference description – will be included in outgoing email if enabled
end_date 10 digit date in the format of “YYYY-MM-DD”
firstCollectionInSameMonthAsNextCollection Will be “false”. This can be used in the PUT to override default behaviour.
first_collection_amount Amount that will be taken for the first collection
first_collection_date When the first collection will be attempted
id Unique identifier
installments For a “DDPaymentPlan” schedule - Total number of installments for the schedule.
mandate Id of the parent Mandate
next_collection_date Next collection date
payment_type Type of payment for the Schedule. Can be either “cardpayment” or “directdebit”
start_date 10 digit date in the format of “YYYY-MM-DD”
status Returns “active” or “inactive”
type Type of Schedule. Can be either “DDOngoingPayment” or “DDPaymentPlan”
upcoming_payments JSON formatted collections

Response Sample

{
    "recurrence_schedule": {
        "amount": "2532",
        "auddis": "FBMAN02814872",
        "card_id": "",
        "collection_day": "19",
        "collection_period": "monthly",
        "collection_stretch": "1",
        "created_at": "2022-05-17T12:09:19Z",
        "custom_reference": "",
        "description": "",
        "end_date": "",
        "firstCollectionInSameMonthAsNextCollection": false,
        "first_collection_amount": "2532",
        "first_collection_date": "2022-05-19",
        "id": "FTBRS00112373",
        "installments": "",
        "mandate": "M01741EJ519Y51P3XGL",
        "next_collection_date": "2022-06-20",
        "payment_type": "DirectDebit",
        "start_date": "2022-05-19",
        "status": "active",
        "type": "DDOngoingPayment",
        "upcoming_payments": "[{\"collection_date\":\"2022-06-20\",\"amount\":\"2532\"},{\"collection_date\":\"2022-07-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-08-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-09-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-10-19\",\"amount\":\"2532\"},{\"collection_date\":\"2022-11-21\",\"amount\":\"2532\"},{\"collection_date\":\"2022-12-19\",\"amount\":\"2532\"}]"
    }
}

Action: Return Recurrence Schedule details in a list.
Method: GET
URL: https://api.smarterpaycloud.com/service.svc/recurrenceschedules

Optional Parameters and filters are available, please see below.

Response Parameters

Property Description
amount Amount
auddis Auddis reference
card_id For a “cardpayment” schedule - Card ID to be used for taking payments
collection_day Can be either “1” - “28” or “last day”
collection_period Can be set to either monthly or weekly
collection_stretch Stretch of collection period
created_at Datetime formatted as ISO8601
custom_reference Custom reference text
description Reference description – will be included in outgoing email if enabled
end_date 10 digit date in the format of “YYYY-MM-DD”
firstCollectionInSameMonthAsNextCollection Will be “false”. This can be used in the PUT to override default behaviour.
first_collection_amount Amount that will be taken for the first collection
first_collection_date When the first collection will be attempted
id Unique identifier
installments For a “DDPaymentPlan” schedule - Total number of installments for the schedule.
mandate Id of the parent Mandate
next_collection_date Next collection date
payment_type Type of payment for the Schedule. Can be either “cardpayment” or “directdebit”
start_date 10 digit date in the format of “YYYY-MM-DD”
status Returns “active” or “inactive”
type Type of Schedule. Can be either “DDOngoingPayment” or “DDPaymentPlan”
upcoming_payments JSON formatted collections

Response Sample

{
    "recurrence_schedules": [
        {
            "amount": "2000",
            "auddis": "FBMAN02704807",
            "card_id": "",
            "collection_day": "02",
            "collection_period": "Weekly",
            "collection_stretch": "1",
            "created_at": "2022-05-12T11:21:37Z",
            "custom_reference": "API Postmant Test",
            "description": "Payment Schedule",
            "end_date": "",
            "firstCollectionInSameMonthAsNextCollection": false,
            "first_collection_amount": "1999",
            "first_collection_date": "2022-05-18",
            "id": "FTBRS00102372",
            "installments": "",
            "mandate": "M01NZWLJR15OWQJGQ91",
            "next_collection_date": "2022-06-01",
            "payment_type": "directDebit",
            "start_date": "2022-05-17",
            "status": "active",
            "type": "DDOngoingPayment",
            "upcoming_payments": "[{\"collection_date\":\"2022-06-01\",\"amount\":\"2000\"},{\"collection_date\":\"2022-06-08\",\"amount\":\"2000\"},{\"collection_date\":\"2022-06-15\",\"amount\":\"2000\"},{\"collection_date\":\"2022-06-22\",\"amount\":\"2000\"},{\"collection_date\":\"2022-06-29\",\"amount\":\"2000\"},{\"collection_date\":\"2022-07-06\",\"amount\":\"2000\"}]"
        },
        {
            "amount": "2000",
            "auddis": "FBMAN02704808",
            "card_id": "",
            "collection_day": "02",
            "collection_period": "Weekly",
            "collection_stretch": "1",
            "created_at": "2022-05-12T11:21:38Z",
            "custom_reference": "API Postmant Test",
            "description": "Payment Schedule",
            "end_date": "",
            "firstCollectionInSameMonthAsNextCollection": false,
            "first_collection_amount": "1999",
            "first_collection_date": "2022-05-18",
            "id": "FTBRS00102373",
            "installments": "",
            "mandate": "M016DZMJNE2QREJK325",
            "next_collection_date": "2022-06-01",
            "payment_type": "directDebit",
            "start_date": "2022-05-17",
            "status": "active",
            "type": "DDOngoingPayment",
            "upcoming_payments": "[{\"collection_date\":\"2022-06-01\",\"amount\":\"2000\"},{\"collection_date\":\"2022-06-08\",\"amount\":\"2000\"},{\"collection_date\":\"2022-06-15\",\"amount\":\"2000\"},{\"collection_date\":\"2022-06-22\",\"amount\":\"2000\"},{\"collection_date\":\"2022-06-29\",\"amount\":\"2000\"},{\"collection_date\":\"2022-07-06\",\"amount\":\"2000\"}]"
        }
    ]
}


Optional Parameters and filters
Optional parameters can be added to the GET URL by using a “?” in front of the first parameter and “&” in front of subsequent parameters, for example https://api.smarterpaycloud.com/Service.svc/BankAccounts?limit=2&page_no=1

Parameter Description
limit Limits the number of records returned by the request. Default=40 when not specified. Minimum=1. Maximum=500.
page_no Specifies which page of records are returned by the request. Default=1 when not specified.
sort_field specifies which field to sort on. Options are: “custom_reference”,“id”,“status”,“customer_id”,“mandate_id”,“created_at” (Default when not specified),“payment_type,record_type,next_collection_date”.
sort_order Specifies which order to sort on. Options are asc (ascending. Default when not specified) or desc (descending).
Filter Description
created_from Filter the list with records created after the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00).
created_to Filter the list with records created before the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00).
customer_id Filter the list using the customer_id. Matches will exactly match the provided value.
custom_reference Filter the list using the custom_reference. Matches will contain the provided value.
id Filter the list using the id. Matches will exactly match the provided value.
mandate_id Filter the list using the mandate_id. Matches will exactly match the provided value.
next_collection_date_from Filter the list with Next Collection date after the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00).
next_collection_date_to Filter the list with Next collection date before the datetime supplied. Format is YYYY-MM-DD HH:MM:SS (2022-05-13 10:15:00).
payment_type Filter the list using the payment_type of the record. Can be a comma seperated list of required values. Options are “DirectDebit”, “CardPayment”.
record_type Filter the list using the record_type of the record. Can be a comma seperated list of required values. Options are “DDPaymentPlan”, “DDOngoingPayment”.
status Filter the list using the status of the record. Can be a comma seperated list of required values. Options are “active”, “inactive”.
  • Last modified: 2023/07/17 13:21