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.

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_nR2duCGXlqWSuYJF
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:

• 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.

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

Amending an existing 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

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.

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.
• 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.