Developer Documents

Schedules can be defined in a variety of ways to cover many conceivable scenarios. Pay360 schedules definitions have been designed with 3 broad approaches in mind – Fixed, Frequency and Pattern.

Fixed

A list of pre-defined dates when transactions should be processed.

Frequency

A Schedule defined in terms of intervals of temporal units. This may be defined in multiples of days, weeks, months or years.
For example every 3 days, every 4 weeks, every 1 month or every 2 years.

In addition the frequency can set to be fixed or relative. In the general, problem-free, running of the schedule this should result in the same behaviour but if there is a problem taking a payment and the payment is taken 2 days late if the definition is FIXED the next scheduled payment (episode) will be unaffected (assuming it is scheduled to occur after the problem payment is resolved), if it is relative it will be recalculated from when the transaction succeeded. So for example if the schedule started on the 1st March and was scheduled to be taken at monthly intervals. If the June payment failed and was not successfully processed until 7th June. If the scheduled was defined as fixed the next transaction would be attempted on 1st July, if relative on 7th July (and on the 7th as long as the schedule continues).

Pattern

A pattern specifies on which days transactions are processed, this can include which days of the week, weeks of the month, days of the month, and months of the year.

Optional Schedule Configurations

There are various options that can be included in a schedule definition and these can be seen in the request specification table below. A more detailed clarification of the purpose of some of these options includes

Start Date: The date on which the first scheduled transaction will occur. If using a fixed schedule it is best practice not to set a start date, the schedule will start on the first date in the fixed dates list.

Time of Day: The time of day that scheduled transaction will occur. This time will be used for all transactions triggered by the schedule. The transaction time is not guaranteed due to volume. In most conditions the repeat will happen within 15 minutes of the given time. Due to this potential variation and adjustments for British Summer Time, we recommend not using a time right at the start or end of the day.

Amount: A list of amounts to process. If the number of episodes in the schedule is greater than the number of amount values the last value specified will be used for the remainder of the schedule.

Terminator: A number of options may be used to set a limit on how long the schedule remains active. This can be defined by a number of episodes or using an end date. If using a fixed schedule it is best practice to not set a terminator, the schedule will finish after the last date in the fixed dates list.

Retry: This option is used to define the behaviour that follows an unsuccessful transaction, or series of attempts to perform a transaction, on a schedule. By default there is no retry behaviour.

Merchant Reference: This option is used to provide a common merchant reference on all payments triggered by the schedule.

Description: This option is used to provide a common description on all payments triggered by the schedule.

{
  "schedule": {
    "startDate": "2021-09-15", 
    "frequency": {
      "unit": "MONTH",
      "quantity": 2
    },
    "terminator": {
      "episodeLimit": 5,
      "suspend": {
        "failureCount": 3
        }
    },
    "merchantRef": "reference_{DATE}",
    "description": "transaction on {DATE} was episode number {EPISODE_INDEX}" 
  } 
} 

{
  "schedule": {
    "startDate": "2021-09-15",
    "pattern": {
      "dayOfWeek": "WEDNESDAY",
      "weekOfMonth": 1
    },
    "terminator": {
      "endOn": "3031-11-15",
      "suspend": {
        "failureCount": 2
      }
    },
    "retry": {
      "unit": "DAY",
      "quantity": 1,
      "maxRetries": 3,
      "catchupAfterRetrying": true
    },
    "amounts": [
      15,
      20,
      12
    ]
  }
}

{
  "schedule": {
    "timeOfDay": "12:00:00",
    "fixed": [
      "2021-01-07",
      "2021-01-13",
      "2021-01-19",
      "2021-01-25",
      "2021-01-31"
    ],
    "retry": {
      "unit": "WEEK",
      "quantity": 1,
      "maxRetries": 3,
      "catchupAfterRetrying": true
    }
  }
}