PaymentSchedule API

The Payment Schedule API turns an authorised NPP PayTo agreement into a set-and-forget recurring payment. Instead of calling the payment initiation API for every run, you tell us the schedule details once and Azupay initiates payments on the agreement's cadence.

This guide covers the full lifecycle: create a schedule, retrieve it, and pause or resume it. Every endpoint shown extends the existing Azupay REST API and reuses the same SecretKey authentication and error model conventions you already know.

You can also view a schedule's current status, cadence, and last run directly in the Azupay dashboard — see the Schedule panel on the Payment Agreements page.

Endpoints at a glance

To search for payment initiations, refer to our existing paymentInitiation API.

Create a Payment Schedule

Create a schedule by POSTing the agreement ID with the schedule details:

POST https://api.azupay.com.au/v1/paymentAgreement/{paymentAgreementId}/scheduler
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJG
Content-Type: application/json

{
  "PaymentScheduler": {
    "status": "ACTIVE",
    "frequency": "MONTHLY",
    "amount": "89.95",
    "startDate": "2026-08-01",
    "endDate": "2027-06-01",
    "timezone": "Australia/Sydney"
  }
}

Request fields

Successful response - 201 Created

{
  "PaymentScheduler": {
    "paymentAgreementId": "aa340b79a04571f989bed2f8d0f771b4",
    "status": "ACTIVE",
    "frequency": "MONTHLY",
    "amount": "89.95",
    "startDate": "2026-08-01",
    "endDate": "2027-06-01",
    "timezone": "Australia/Sydney"
  },
  "PaymentSchedulerStatus": {
    "version": 1,
    "createdDatetime": "2026-05-18T04:33:12.045Z",
    "updatedDatetime": "2026-06-23T02:42:32.753Z"
  }
}

Validation Errors - 4xx

See down below for a full list of 4xx errors and their corresponding messages.

{
  "message": "version does not match the current scheduler version",
  "details": {
    "failureCode": "AZP3.8",
    "failureReason": "version does not match the current scheduler version"
  }
}

How cadence is anchored

The cadence anchor is derived from startDate in combination with the agreement's frequency. This applies to recurring schedules only - a ONCE schedule has no cadence and runs on startDate alone.

• Weekly - same day-of-week as startDate, every week.
• Fortnightly - startDate, then every 14 days.
• Monthly - startDate.day every month. If startDate.day is 29, 30, or 31, the schedule executes on the last day of every month instead - so February is never silently skipped.
• Annually - same month and day as startDate, every year. Feb 29 resolves to the last day of February each year.

One-off payments - ONCE on an ADHOC agreement

Not every agreement is a recurring one. An agreement created with a frequency of ADHOC has no fixed cadence - the payer has authorised you to collect as needed, within the agreement's caps. When you want Azupay to initiate one of those collections on a nominated date, without your systems having to call the payment initiation API on the day, attach a schedule with a frequency of ONCE.

ONCE requires an ADHOC agreement. The rule does not run both ways: because an ADHOC agreement has no cadence of its own, it accepts any scheduler frequency - ONCE for a single collection, or a recurring frequency if you would rather put a regular cadence over it. Every other agreement must be matched exactly.

On an ADHOC agreement the schedule is what sets the cadence, since the agreement does not carry one.

Creating a one-off schedule

Everything else on the call is unchanged - same endpoint, same envelope, same authentication:

POST https://api.azupay.com.au/v1/paymentAgreement/{paymentAgreementId}/scheduler
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJG
Content-Type: application/json

{
  "PaymentScheduler": {
    "status": "ACTIVE",
    "frequency": "ONCE",
    "amount": "250.00",
    "startDate": "2026-09-15",
    "timezone": "Australia/Sydney"
  }
}

startDate is simply the day the payment runs, and endDate is left out altogether - there is no recurrence for it to bound.

Successful response - 201 Created

{
  "PaymentScheduler": {
    "paymentAgreementId": "b71e04c3f2a94d5eab6c8f1207d3e5a9",
    "status": "ACTIVE",
    "frequency": "ONCE",
    "amount": "250.00",
    "startDate": "2026-09-15",
    "timezone": "Australia/Sydney"
  },
  "PaymentSchedulerStatus": {
    "version": 1,
    "createdDatetime": "2026-08-27T23:14:06.512Z"
  }
}

After the one-off payment has run

Once the single payment has been initiated, the schedule moves to INACTIVE. The outcome reaches you on your existing Payment Initiation webhook, exactly as it would for an ad-hoc payment your own systems initiated.

The schedule is dormant rather than finished. To collect again on the same ADHOC agreement, amend it back to ACTIVE with a new startDate and amount, quoting the current version from your most recent GET:

{
  "PaymentScheduler": {
    "version": 2,
    "status": "ACTIVE",
    "frequency": "ONCE",
    "amount": "180.00",
    "startDate": "2026-10-02",
    "timezone": "Australia/Sydney"
  }
}

There is still only ever one schedule per agreement, so each subsequent one-off collection reuses this same resource. The full payload and a matching version are required, as they are for any amendment - see Amend an existing Payment Schedule below.

Retrieve a Payment Schedule

GET https://api.azupay.com.au/v1/paymentAgreement/{paymentAgreementId}/scheduler
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJF

Returns the request payload alongside the current state (status, cadence, last run).

Successful response - 200 OK

{
  "PaymentScheduler": {
    "paymentAgreementId": "aa340b79a04571f989bed2f8d0f771b4",
    "status": "ACTIVE",
    "frequency": "MONTHLY",
    "amount": "89.95",
    "startDate": "2026-08-01",
    "endDate": "2027-06-01",
    "timezone": "Australia/Sydney"
  },
  "PaymentSchedulerStatus": {
    "version": 2,
    "lastRunDatetime": "2026-06-01T04:33:12.045Z",
    "updatedDatetime": "2026-07-03T01:12:58.089Z",
    "createdDatetime": "2026-05-18T04:33:12.045Z"
  }
}

Amend an existing Payment Schedule

To amend an existing schedule, use the original POST /paymentAgreement/{paymentAgreementId}/scheduler

Semantics

• If no schedule exists for the paymentAgreementId, one will be created.
• If a schedule already exists, the full payload is required to amend a schedule
• There is only ever one schedule per payment agreement.
• Changes apply to future scheduled payments only.
• When amending, version is required and must match the current version returned by the most recent GET or POST. If the version does not match, the amendment is rejected with 409 Conflict - this prevents concurrent calls from silently overwriting each other.

Amendable fields

Example - amending amount and end date

The full payload is required to amend a schedule.

POST https://api.azupay.com.au/v1/paymentAgreement/{paymentAgreementId}/scheduler
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJF
Content-Type: application/json

{
  "PaymentScheduler": {
    "version": 2,
    "status": "ACTIVE",
    "frequency": "MONTHLY",
    "amount": "99.95",
    "startDate": "2026-08-01",
    "endDate": "2029-06-01",
    "timezone": "Australia/Sydney"
  }
}

Successful response - 200 OK

{
  "PaymentScheduler": {
    "paymentAgreementId": "aa340b79a04571f989bed2f8d0f771b4",
    "status": "ACTIVE",
    "frequency": "MONTHLY",
    "amount": "99.95",
    "startDate": "2026-08-01",
    "endDate": "2029-06-01",
    "timezone": "Australia/Sydney"
  },
  "PaymentSchedulerStatus": {
    "version": 3,
    "lastRunDatetime": "2026-06-01T04:33:12.045Z",
    "createdDatetime": "2026-05-18T04:33:12.045Z",
    "updatedDatetime": "2026-05-28T01:12:44.901Z"
  }
}

Example - pausing a schedule

The full payload is required to amend a schedule.

POST https://api.azupay.com.au/v1/paymentAgreement/{paymentAgreementId}/scheduler
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJF
Content-Type: application/json

{
  "PaymentScheduler": {
    "version": 3,
    "status": "INACTIVE",
    "frequency": "MONTHLY",
    "amount": "99.95",
    "startDate": "2026-08-01",
    "endDate": "2029-06-01",
    "timezone": "Australia/Sydney"
  }
}

Successful response - 200 OK

{
  "PaymentScheduler": {
    "paymentAgreementId": "aa340b79a04571f989bed2f8d0f771b4",
    "status": "INACTIVE",
    "frequency": "MONTHLY",
    "amount": "99.95",
    "startDate": "2026-08-01",
    "endDate": "2029-06-01",
    "timezone": "Australia/Sydney"
  },
  "PaymentSchedulerStatus": {
    "version": 4,
    "lastRunDatetime": "2026-06-01T04:33:12.045Z",
    "createdDatetime": "2026-05-18T04:33:12.045Z",
    "updatedDatetime": "2026-05-28T01:12:44.901Z"
  }
}		

Schedule Status & Agreement Status

The Payment Agreement status will be synced with the Payment Schedule status automatically.

Allowed transitions

A ONCE schedule that has already run has no next scheduled run, so reactivating it also requires a new startDate.

Validation Errors - 4xx

See down below for a full list of 4xx errors and their corresponding messages.

{
  "message": "version does not match the current scheduler version",
  "details": {
    "failureCode": "AZP3.8",
    "failureReason": "version does not match the current scheduler version"
  }
}

Schedule lifecycle

The schedule has two states: ACTIVE & INACTIVE

Merchant-driven transitions

Merchants can change the status of the schedule via POST /paymentAgreement/{paymentAgreementId}/scheduler

Agreement-driven transitions (automatic - no API call needed)

The schedule status is only affected when the underlying agreement is cancelled - regardless of how or by whom. Payments are attempted as normal while the agreement is paused or suspended by the payer or bank. When a cancellation is received, the schedule moves to INACTIVE only after the latest payment initiation attempt has completed.

Completion

When endDate is reached, the schedule moves to INACTIVE. A ONCE schedule moves to INACTIVE as soon as its single payment has been initiated, and can be amended back to ACTIVE with a new startDate to collect again.

Webhook behaviour

The schedule does not introduce a new webhook channel. The two existing webhooks carry everything you need:

Things to keep in mind

• No automatic retries. The schedule initiates each run once. To chase a failed collection, drive it from your own systems - for example by creating a fresh ad-hoc payment under the same agreement.
• Schedule run time: The schedule would run in the morning of the day that is programmed to run according to the provided timezone.
• No schedule-specific webhooks. Use the Payment Initiation and Payment Agreement webhooks you already consume.
• Missed runs during a pause are not back-filled. Runs that fall during a paused window are skipped; the schedule picks up at the next scheduled date when resumed.
• End-of-month handling. A monthly schedule starting on the 29th, 30th, or 31st runs on the last day of every month thereafter - by design, so shorter months like February are never silently skipped.
• One-off collections use ONCE. ONCE is only accepted on an ADHOC agreement, though an ADHOC agreement will equally take a recurring frequency. A ONCE schedule runs a single payment on startDate, then goes INACTIVE; amend it with a new startDate to collect again. Dating it today initiates the payment within 10 minutes.