Implement Scheduling API to debit payer

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:

The Payrix 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 can be much easier to manage any changes to the debit date, amount and allows you to send the API on the morning of you require to debit the payer.
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.

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'
- ‘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’
- ‘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, it must be cancelled before Payrix has picked it up for processing. If the scheduled debit has already been processed, you can no longer cancel or stop the debit from processing. 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. Refer to our methods available for accepting payments.