Implement Scheduling API to debit payer (UK specific)

Before you can implement the scheduling API to debit a payer, ensure you have already read and understand the API workflow to create a Payer Record with a payment method.

Refer to the below to review steps:

Our API offers two scheduling options:

Schedule a single payment
- Adds a single payment to the default schedule for an existing payer that will be processed at a future time. If the payer does not have a processing status of ACTIVE on the scheduled date, then the payment will not be processed. See the Change a Payers status request for more details.
- Recommended solution to implement as the payments become much easier to manage should there be any changes to the debit date, amount and frequency. This API allows you to send the API as and when required.
Schedule multiple future payments
- Adds multiple payments to the default schedule for an existing payer that will be processed at a future time. If the payer does not have a processing status of ACTIVE on the scheduled date, then the payment will not be processed. See the Change a Payers status request for more details.

Note - In the UK, a Bank Account direct debit schedule in the UK must allow 6 business days notice before the payment due date. Scheduled Bank Account debits may not be altered or removed once it is within the 6 business day notice period as per UK regulations. A Credit Card direct debit does not fall under the same UK BACS requirements for the 6 business day rule and can be scheduled, altered or removed at any time prior to processing.

The flow for implementing our scheduling API:

Schedule single or multiple payments
Determine result of scheduled debit - GET Search for transaction status change
Remove transaction from data set - POST Acknowledge transaction status change

Step 1a - Initiate a scheduled debit

API

POST Schedule a single payment

Minimum fields required:
- ‘Date' - must be 6 business days in the future as per UK requirements, or will return error and not process
- ‘Amount’
- ‘Reference’ is recommended but optional

Scheduled Payment Model

This model details property requirements and description of each property type for the API request.

Sample JSON

Example Request

JSON

{{url}}/businesses/{{business-id}}/payers/{{payer-reference}}/schedules/payments

JSON

{
    "Date": "2024-04-04",
    "Amount": 33.75,
    "Reference": "Scheduled-Payment-001",
    "Description": "This is the first scheduled payment",
    "SubBusinessId": null,
    "ServiceDate": "2024-04-01T10:00:00+10:00",
    "Audit": {
      "Username": "Example-User",
      "UserIP": "1.2.3.4"
    }
}

Example Response

JSON

{
  "scheduledPaymentId": "213813"
}

Step 1b - Initiate Schedule multiple future payments

API

POST Schedule multiple future payments

Minimum required fields:
- ‘ScheduleType’
- ‘StartDate’ - must be 6 business days in the future as per UK requirements, or will return error and not process
- ‘Amount’
- ‘Frequency’

Schedule Generate API model

This model details property requirements and description of each property type for the API request.

Sample

Example Request

JSON

{{url}}/businesses/{{business-id}}/payers/{{payer-reference}}/schedules/

JSON

{
    "ScheduleType": "UNENDING",
    "StartDate": "2024-04-04",
    "Amount": 100,
    "Frequency": "FORTNIGHTLY",
    "FrequencyDay": 5,
    "RemoveAllPaymentsBeforeStartDate": true,
    "Audit": {
        "Username": "Example-User",
        "UserIP": "1.2.3.4"
    }
}'

Example Response

This request does not return any response body

Final Steps to determine the result of the scheduled debit transaction

As you should be aware, scheduled debit are processed via BECS (Bulk Electronic Clearing System) and have a 2 business day processing time. To determine the result of the transaction, settled or rejected (failed), simply follow the 2 API steps below:

Step 2 - GET Search for transaction status

API

Call our GET Search for transaction status changes around 9AM AEST daily which will pull a set of all transactions for your business that have had a change of transaction status.

When a transaction is initially processed in the debit run, the transaction status will be ‘P’ (Pending - Bank Debit) or 'C’ (Cleared - Card Debit)
On the 2nd business day, the result will be returned by the bank which will change the status to ‘S' (Settled) or 'R’ (Rejected - Transaction failed)
- If a transaction is rejected with a decline reason supplied by the issuer we will return this response. Refer to Transaction Sub-Status Code.

Sample

Example Request

JSON

{{url}}/businesses/{{business-id}}/transactions/new

Example Response

JSON

[
  {
    "business": {
      "businessId": "1234",
      "businessName": "Test Business Ltd"
    },
    "time": "2018-06-29T06:07:01.153+00:00",
    "transactionId": "121435",
    "secondaryTransactionId": "RT59581",
    "reference": "REAL-TIME-TXN-001",
    "description": "This is an example real-time transaction",
    "scheduleReference": null,
    "amount": 100.25,
    "amountRequested": 100.25,
    "amountRefunded": 10,
    "currency": "AUD",
    "type": "RT",
    "typeDescription": "Realtime Payment - Website",
    "statusCode": "C",
    "subStatusCode": "RF",
    "statusDescription": "Cleared",
    "paymentMethod": "VISA",
    "payer": null,
    "card": {
      "cardNumber": "411111xxxxxx1111",
      "cardholderName": "TEST Card",
      "cardExpires": "2023-10-01T00:00:00",
      "cardType": "Visa"
    },
    "bankAccount": null,
    "rejectionRecovery": null,
    "verification": null
  },
  {
    "business": {
      "businessId": "1234",
      "businessName": "Test Business Ltd"
    },
    "time": "2018-06-29T06:20:30.35+00:00",
    "transactionId": "121436",
    "secondaryTransactionId": "RT59582",
    "reference": "REAL-TIME-TXN-002",
    "description": "This is an example pre-auth real-time transaction",
    "scheduleReference": null,
    "amount": 200,
    "amountRequested": 200,
    "amountRefunded": 0,
    "currency": "AUD",
    "type": "RT",
    "typeDescription": "Realtime Payment - Website",
    "statusCode": "C",
    "subStatusCode": null,
    "statusDescription": "Cleared",
    "paymentMethod": "MASTERCARD",
    "payer": null,
    "card": {
      "cardNumber": "555555xxxxxx4444",
      "cardholderName": "TEST CARD",
      "cardExpires": "2023-10-01T00:00:00",
      "cardType": "Mastercard"
    },
    "bankAccount": null,
    "rejectionRecovery": null,
    "verification": null
  },

Step 3 - POST Acknowledge transaction status change

API

Following the above API, use our POST Acknowledge transaction status change to acknowledge the transactions and remove them from the data set when you next call the Get New Status Search above.

If the transaction status changes again after you have removed it from the data set, it will be returned in the GET Search for transaction status changes to notify you of the change in status.

Sample

Example Request

JSON

{{url}}/businesses/{{business-id}}/transactions/new

JSON

{
    "TransactionId": "121435",
    "StatusCode": "C",
    "Audit": {
		"Username": "Example-User",
    	"UserIP": "1.2.3.4"
    }
}

Example Response

This request does not return any response body

What to do if a scheduled debit has failed?

If the result of the transaction has returned and been identified as failed / rejected, pending on your application’s workflow, you can simply schedule another debit to capture payment and then identify the result of the following debit in the same flow, GET Search for transaction status then POST Acknowledge transaction status change.

Alternatively, you can utilise one of our features to manage collection on failed payments. Refer to our guide here and reach out to your Partner / Account manager to discuss.

How to cancel a scheduled debit from processing?

In order to cancel a scheduled debit from processing, you must follow the steps below:

If it is a Bank Account debit, it must be cancelled more than 6 days in advance to comply with the UK BACS requirements.
If it is a Credit Card debit, it must be cancelled before it has been picked up for processing on the due date.

Utilise any of the 'Find Schedule Details ' API in conjunction with the DELETE Delete Single Payment to confirm the scheduled debit was cancelled successfully.

Example

Call GET Look up a scheduled payment or GET Find a Payers scheduled payments or GET Search all scheduled payments to identify the 'scheduledpaymentid'.
- If the 'scheduledpaymentid' that you are planning to cancel is returned in this API call, the debit has not yet been picked up for processing and you are still able to cancel the scheduled debit.
- If the 'scheduledpaymentid' is not returned, the debit has been processed and can no longer be cancelled.
Cancel the scheduled debit by calling Delete Single Payment
- This will return a 200 response
Confirm the cancellation by calling either of the 3 GET API calls.
- If the 'scheduledpaymentid' is not returned, the scheduled debit has been deleted.

This concludes the API workflow of implementing scheduling payments to your application in the UK. Refer to our methods available for accepting payments.