Creating a Schedule
Developer Documents‣Common features‣Creating a Schedule

The key request to create a schedule is the same regardless of the mechanism chosen to create the schedule. This is documented on the Schedule Definition page.

The endpoints and their usages are documented below.

Creating a schedule while requesting an initial authorisation

API

A schedule can be attached to a transaction when it is initially requested. If the transaction is successful the schedule will be created, if the transaction is not successful it will not be created. If for some reason the schedule is not successfully created the transaction will be unaffected and will complete as expected. The cause of the error in the schedule creation will be returned in the response. The schedule can be re-created by creating a schedule on an existing transaction which is documented below.

API examples
Sample Payment (for a new customer)


POST /acceptor/rest/transactions/{instId}/payment
{
  "transaction": {
    "currency": "GBP",
    "amount": "1000.0",
    "commerceType": "MOTO",
    "recurring": true
  },
  "paymentMethod": {
    "card": {
      "pan": "9900000000005159",
      "cv2": "123",
      "expiryDate": "0125",
      "startDate": "1111",
      "cardType": "MC_DEBIT",
      "nickname": "John",
      "cardHolderName": "John Smith",
      "defaultCard": "false"
    }
  },
  "schedule": {
    "startDate": "2021-01-30",
    "pattern": {
      "dayOfMonth": 20
    }
  }
}

HTTP/1.1 201
{
  "processing": {
    "authResponse": {
      "statusCode": "00",
      "message": "ACQUIRER OK",
      "authCode": "100000",
      "status": "AUTHORISED"
    },
    "route": "MCPE"
  },
  "paymentMethod": {
    "card": {
      "cardToken": "rusq9CmgRC2o39RYx9HAlA",
      "cardFingerprint": "0hbdt0r/7ofTCqA5qKilqtHeeJg=",
      "new": true,
      "cardType": "MC_DEBIT",
      "cardUsageType": "DEBIT",
      "cardCategory": "DEBIT",
      "cardScheme": "VISA",
      "maskedPan": "990000******5159",
      "expiryDate": "0115",
      "issuer": "Lloyds",
      "issuerCountry": "GBR",
      "cardHolderName": "John Smith",
      "cardNickname": "John",
      "validDate": "1111"
    },
    "paymentClass": "CARD"
  },
  "transaction": {
    "transactionId": "13501566687",
    "merchantRef": "mer_txn_1234556",
    "status": "SUCCESS",
    "type": "PAYMENT",
    "amount": 1000,
    "consumerSpend": 1000,
    "currency": "GBP",
    "transactionTime": "2021-01-06T12:25:30.902Z",
    "receivedTime": "2021-01-06T12:25:30.902Z",
    "channel": "MOTO"
  },
  "schedule": {
      "schedule": "GUID123456789010" 
  }, 
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  }
}
Sample Verification (with default card)

POST /acceptor/rest/transactions/{instId}/verify

{
  "transaction" : {
    "currency" : "GBP",
    "commerceType" : "MOTO",
    "recurring": true
  },
  "paymentMethod" : {
    "fromCustomer" : {
      "cv2" : "123"
    }
  },
  "customer" : {
    "merchantRef" : "mer_cust_131241412"
  },
  "verification" : {
    "acquirerPaymentMethod" : true
  },
  "schedule": {
    "startDate": "2021-01-30",
    "end": "2031-06-30",
    "time": "13:30:00",
    "frequency": {
        "unit": "WEEK",
        "quantity": 2
    },
    "amounts": [
      5.00,
      3.00
    ],
    "retry": {
        "unit": "DAY",
        "limit": 2
    }
  } 
}

HTTP/1.1 201
{
  "processing" : {
    "authResponse" : {
      "acquirerName" : "HSBC Merchant Services Domestic",
      "message" : "TEST AUTH",
      "authCode" : "9999",
      "gatewayMessage" : "TEST AUTH",
      "status" : "AUTHORISED"
    },
    "route" : "GATEWAY"
  },
  "paymentMethod" : {
    "registered" : true,
    "card" : {
      "cardToken" : "MT_wpL9AdPDQnyeVHoh74AhHQ",
      "new" : false,
      "cardType" : "VISA_DEBIT",
      "cardUsageType" : "DEBIT",
      "cardScheme" : "VISA",
      "cardCategory" : "CREDIT",
      "maskedPan" : "444433******1111",
      "expiryDate" : "0118",
      "issuer" : "DATACASH",
      "issuerCountry" : "GBR",
      "cardHolderName" : "John Smith",
      "cardNickname" : "John",
      "validDate" : "1111"
    },
    "paymentClass" : "CARD"
  },
  "customer" : {
    "id" : "10983",
    "merchantRef" : "mer_cust_131241412"
  },
  "transaction" : {
    "transactionId" : "13133368188",
    "merchantRef" : "mer_txn_1234556",
    "merchantDescription" : "Sample Transaction",
    "status" : "SUCCESS",
    "type" : "VERIFY",
    "transactionTime" : "2017-01-13T14:43:30.826Z",
    "receivedTime" : "2017-01-13T14:43:30.826Z"
  },
  "outcome" : {
    "status" : "SUCCESS",
    "reasonCode" : "S100",
    "reasonMessage" : "Authorised"
  },
  "schedule": {
      "schedule": "GUID123456789010" 
  }
}

Creating a schedule while requesting a Repeat

API

A schedule can be created while requesting a repeat of a transaction. The schedule will be associated with the original, primary, transaction. If the transaction is successful the schedule will be created, if the transaction is not successful it will not be created. If for some reason the schedule is not successfully created the transaction will be unaffected and will complete as expected. The cause of the error in the schedule creation will be returned in the response. The schedule can be re-created by creating a schedule on an existing transaction which is documented below.

API examples
Create Schedule while Requesting repeat

POST /acceptor/rest/transactions/{instId}/{transactionId}/repeat

{
    "schedule" : {
        "startDate":"2021-09-15",
        "timeOfDay":"12:00:00", 
        "fixed": {
             "dates" : ["2021-09-15","3031-11-15"]
        },
        "terminator":{
            "episodeLimit":5,
            "endOn":"3031-11-15",
            "suspend":{
                "failureCount":3
             }
         },
        "retry":{
            "unit": "DAY",
            "quantity": 1,
            "maxRetries":3,
            "processWhileRetrying":false,
            "catchupAfterRetrying":true
        }
    }
}

HTTP/1.1 201
{
  "processing": {
    "model": "MANAGE",
    "authResponse": {
      "acquirerName": "FDMS International",
      "gatewayReference": "111gbpfa2941311412749ACee1000z00",
      "gatewayCode": "000.000.000",
      "gatewayMessage": "Transaction succeeded",
      "status": "AUTHORISED"
    },
    "route": "PAYON"
  },
  "paymentMethod": {
    "registered": false,
    "card": {
      "cardFingerprint": "Q1MtYTRiZGIzODYtYzQ2My00NTRlLTljZjYtYzY0OTEzZjUwMmVj",
      "new": false,
      "cardType": "VISA_CREDIT",
      "cardUsageType": "CREDIT",
      "cardScheme": "VISA",
      "cardCategory": "CREDIT",
      "maskedPan": "990300******5131",
      "expiryDate": "0125",
      "issuer": "PAY360 TESTING",
      "issuerCountry": "GBR",
      "cardHolderName": "John Smith"
    },
    "paymentClass": "CARD",
    "reuse": {
      "storage": "EXISTING",
      "agreement": "INSTALMENT",
      "originalSchemeReference": "111gbp2633976043a3f84FMee1000z00",
      "receivedSchemeReference": "111gbpfa2941311412749ACee1000z00"
    }
  },
  "transaction": {
    "transactionId": "10393828218",
    "deferred": false,
    "instalment": true,
    "status": "SUCCESS",
    "stage": "COMPLETE",
    "type": "REPEAT",
    "amount": 1000,
    "consumerSpend": 1000,
    "currency": "GBP",
    "transactionTime": "2020-11-13T16:02:32.261Z",
    "receivedTime": "2020-11-13T16:02:32.261Z",
    "relatedTransaction": {
      "transactionId": "10393828217"
    },
    "customerInitiated": false
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  },
  "schedule": {
      "schedule": "GUID123456789010" 
  }
}

Creating a schedule via Hosted Cashier or EmailPay

API

A schedule can be initiated as part of a request to a hosted cashier page whether this is done directly or via an EmailPay link. If you would like information about the schedule to be displayed on the form this will need to be done by the skin.

API examples
Requesting a Hosted Cashier session

POST /hosted/rest/sessions/{inst}/payments
or
POST /smartlink/links/{inst}/payment

{
  "session" : {
    "returnUrl" : {
      "url" : "http://www.example.com/hosted/transactionResult?ref=paymentHosted"
    }
  },
  "transaction" : {
    "merchantReference" : "paymentHosted",
    "money" : {
      "currency" : "GBP",
      "amount" : {
      	"fixed": 10.99
      }
    },
    "description" : "PaymentHosted"
  },
  "customer" : {
    "identity" : {
      "merchantCustomerId" : "customer1"
    },
    "details": {
    	"name": "Customer 1",
    	"address": {
    		"countryCode": "GBR"
    	}
    }
  },
  "schedule": {
    "startDate": "2021-01-30",
    "pattern": {
      "dayOfMonth": 15
    }
  }
}

Creating a schedule on an existing transaction

API

It is also possible to create a schedule on an existing successful transaction.

API examples
Create schedule on existing transaction

POST /acceptor/rest/transactions/{instId}/{transactionId}/addSchedule

{
  "schedule": {
    "frequency": {
      "unit": "MONTH"
    },
    "amounts": [
      5.00,
      3.00
    ]
  }
}

HTTP/1.1 201
{
  "processing": {
    "model": "MANAGE",
    "authResponse": {
      "acquirerName": "AIB Merchant Services",
      "gatewayReference": "111gbp72d7be32e37d992AMeeee10z00",
      "gatewayCode": "000.000.000",
      "gatewayMessage": "Transaction succeeded",
      "cv2Check": "MATCHED",
      "status": "AUTHORISED"
    },
    "route": "PAYON"
  },
  "paymentMethod": {
    "registered": false,
    "card": {
      "cardFingerprint": "Q1MtNTRmNzc2ZjQtNDE3NC00ZjNkLTgxYzAtYTFlYTE3MTlmMjUx",
      "new": true,
      "cardType": "MC_DEBIT",
      "cardUsageType": "DEBIT",
      "cardScheme": "MASTERCARD",
      "cardCategory": "DEBIT",
      "maskedPan": "990000******0010",
      "expiryDate": "1221",
      "issuer": "PAY360 TESTING",
      "issuerCountry": "GBR",
      "cardHolderName": "John Smith"
    }
  },
  "transaction": {
    "transactionId": "11760200728",
    "recurring": true,
    "status": "SUCCESS",
    "stage": "COMPLETE",
    "type": "PAYMENT",
    "amount": 10.00,
    "consumerSpend": 10.00,
    "currency": "GBP",
    "transactionTime": "2021-03-08T13:35:22.575Z",
    "receivedTime": "2021-03-08T13:35:22.575Z",
    "customerInitiated": true
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  },
  "schedule": {
    "scheduleId": "ff80818177f809ea0178122793b20013"
  }
}
API Endpoint
endpoint: /acceptor/rest/transactions/{instId}/{transactionId}/addSchedule
method: POST
summary: Create schedule on existing transaction

parameters:

Name
Data Type
Description
instId
string
The installation id
transactionId
string
The transaction id
request body:

{
schedule {
startDate string
Format: “yyyy-MM-dd”
The date the schedule becomes active and, if relevant that epiode calculations start from
timeOfDay string
Format: “HH:mm:ss”
The time of day that any episodes will be triggered
frequency { Conditional
One and only one of Fixed, Frequency or Pattern must be provided
unit string
Possible Values: DAY, WEEK, MONTH, YEAR
Mandatory
unit must be provided for a frequency schedule
quantity integer
default: 1
rate string
Possible Values: FIXED, RELATIVE
default: RELATIVE
}
pattern { Conditional
One and only one of Fixed, Frequency or Pattern must be provided
dayOfWeek string
Possible Values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
The specific day of the week to peform the transaction
daysOfWeek array of string
Possible Values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
The specific days of the week to peform the transaction
dayOfMonth integer
There specific day of the month to peform the transaction (up to 31, in shorter months this will run on the last day of the month)
daysOfMonth array of integers
The specific days of the month to peform the transaction (up to 31, in shorter months this will run on the last day of the month)
weekOfMonth integer
The specific week of the month to peform the transaction (up to 4)
weeksOfMonth array of integers
The specific weeks of the month to peform the transaction (up to 4)
monthOfYear string
Possible Values: JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER
monthsOfYear array of strings
Possible Values: JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER
}
fixed { array of strings
Format: “yyyy-MM-dd”
Conditional
One and only one of Fixed, Frequency or Pattern must be provided
}
terminator {
episodeLimit integer
Conditional
One of episodeLimit or endOn must be specified
the number of episodes to run before the schedule is complete
endOn string
Conditional
One of episodeLimit or endOn must be specified
Format: “yyyy-MM-dd”
the scheduler will not run after this date. If there is an episode due on this date, it will be run.
suspend {
failureCount integer
The number episode failures before the Schedule suspends (this should be higher than the maximum retry count)
}
}
retry {
unit string
Mandatory
Possible Values: HOUR, DAY, WEEK, MONTH
combined with quantity when and should a retry be attempted
quantity integer
combined with unit when and should a retry be attempted
default: 1
maxRetries integer
How many retries shoudl be attewmpted before the episode fails.
default: 5
processWhileRetrying boolean
continue to process scheduled episodes while retrying a failed epsiode. default: false.
catchupAfterRetrying boolean
process any episodes missed while retrying a failed epsiode. default: false.
}
amounts array of decimals
specific amounts to process in order. If there are less amounts than episodes the final amount will repeat. If no amounts are specified the amount on the original transaction will be used.
merchantRef string
A merchant defined reference to be added to the repeated repeats triggered by the schedule. If the place-holder {DATE} is included this will be replaced by the date the payment is actually processed in yyyy-MM-dd format. If the place-holder {EPISODE_INDEX} is used this will be replaced with the index of the episode which triggered the transaction.
description string
A merchant defined description to be added to the repeated repeats triggered by the schedule. If the place-holder {DATE} is included this will be replaced by the date the payment is actually processed in yyyy-MM-dd format. If the place-holder {EPISODE_INDEX} is used this will be replaced with the index of the episode which triggered the transaction.
}
}
response:

The full response from the original transaction will be returned along with the schedule response included. For the specification of the existing response please see the response definition on the Card Payments page the schedule specification is detailed here.

{
schedule {
scheduleId string
The identifier for the created schedule
error string
Details of the causes of the error if an error occurred creating the schedule.
}
}