☰
Navigation :

Collections API - Plans and Schedules

Base URL

This tutorial uses the test URL:

https://api.paygateservicedemo.com/collections_public/api/

A Plan defines when and how much is collected from a Payer. Plans belong to a Payer, so a Payer must exist first - see Collections API - Payers.

Step 1 - Plan Templates

Plans can be created from a Plan Template, which pre-populates the schedule settings.

Getting all templates

Call type: GET

Url: https://api.paygateservicedemo.com/collections_public/api/plans/templates

Response:

{
  "planTemplates": [
    {
      "self": { "url": "/api/plans/templates/MONTHLY10" },
      "templateReference": "MONTHLY10",
      "firstAmount": null,
      "regularAmount": 10.00,
      "lastAmount": null,
      "variableAmounts": false,
      "recurrenceType": 1,
      "recurrenceEndType": 3,
      "giftAid": false,
      "totalPayments": 0,
      "ordinal": 1,
      "step": 1,
      "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c"
    }
  ]
}

Getting a named template

Call type: GET

Url: https://api.paygateservicedemo.com/collections_public/api/plans/templates/{templateReference}

Returns a single template as above, or a 404 ProblemDetails if it is not found.

Step 2 - Creating a Plan

Call type: POST

Url: https://api.paygateservicedemo.com/collections_public/api/payers/{groupId}/{payerReference}/plans

Request:

{
  "firstPaymentDate": "22/10/2026",
  "untilDate": null,
  "firstAmount": 10,
  "giftAid": true,
  "lastAmount": 10,
  "ordinal": 1,
  "recurrenceEndType": 0,
  "recurrenceType": 0,
  "regularAmount": 5,
  "step": 1,
  "totalPayments": 0,
  "variableAmounts": false,
  "planTemplateReference": "PlanTemplateName"
}

“planTemplateReference” and “giftAid” are the only consistently mandatory field. Other values default from the template, when one is supplied.

If the “recurrenceEndType” is set to 4 (Ad Hoc Plan), then “ordinal”, “recurrenceEndType”, “recurrenceType”, “step”, “regularAmount” and “firstPaymentDate” are required fields.

Plan fields

Field Description
recurrenceType 0 = Weekly, 1 = Monthly, 2 = Yearly
recurrenceEndType 0 = OneOff, 1 = UntilDate, 2 = UntilNumberOfPayments, 3 = Ongoing, 4 = AdHoc
ordinal Weekly: weekday (1 Monday … 7 Sunday). Monthly: day of the month (1 to 31). Yearly: day of the year (1 to 365). Weekends and bank holidays are taken into account
step How often the plan runs. A monthly plan with step 1 collects every month, with step 3 every 3 months
firstPaymentDate Optional override of the first collection date, format dd/MM/yyyy. By default this is the first date possible given the AUDDIS advance notice period
untilDate Required when recurrenceEndType is UntilDate, format dd/MM/yyyy
totalPayments Required when recurrenceEndType is UntilNumberOfPayments
firstAmount / lastAmount Optional amounts for the first and last collections. If blank the regularAmount is used
variableAmounts When true the Plan accepts variable amounts, which override the first, regular and last amounts

Response:

{
  "self": {
    "url": "/api/payers/3d8ac4aa-4610-48a7-8d74-a5a3e192a42c/SMITH0001/plans/PLAN0002"
  },
  "payer": "/api/payers/3d8ac4aa-4610-48a7-8d74-a5a3e192a42c/SMITH0001",
  "firstAmount": 15.00,
  "regularAmount": 10.00,
  "variableAmounts": false,
  "recurrenceType": 1,
  "recurrenceEndType": 3,
  "giftAid": true,
  "reference": "PLAN0002",
  "firstPaymentDate": "01/12/2026",
  "totalPayments": 0,
  "ordinal": 1,
  "step": 1
}

Step 3 - Getting Plans

All Plans for a Payer

Call type: GET

Url: https://api.paygateservicedemo.com/collections_public/api/payers/{groupId}/{payerReference}/plans

Response:

{
  "plans": [
    {
      "self": { "url": "/api/payers/3d8ac4aa-4610-48a7-8d74-a5a3e192a42c/SMITH0001/plans/PLAN0001" },
      "reference": "PLAN0001",
      "firstPaymentDate": "22/10/2026",
      "untilDate": null,
      "firstAmount": 10,
      "giftAid": true,
      "lastAmount": 10,
      "ordinal": 1,
      "recurrenceEndType": 0,
      "recurrenceType": 0,
      "regularAmount": 5,
      "step": 1,
      "totalPayments": 0,
      "variableAmounts": false
    }
  ]
}

A specific Plan

Call type: GET

Url: https://api.paygateservicedemo.com/collections_public/api/payers/{groupId}/{payerReference}/plans/{planReference}

Returns a Plan response as shown in Step 2, or a 404 ProblemDetails.

Step 4 - Updating a Plan

Call type: PUT

Url: https://api.paygateservicedemo.com/collections_public/api/payers/{groupId}/{payerReference}/plans/{planReference}

Request:

{
  "firstPaymentDate": "22/10/2026",
  "untilDate": null,
  "firstAmount": 10,
  "giftAid": true,
  "lastAmount": 10,
  "ordinal": 1,
  "recurrenceEndType": 0,
  "recurrenceType": 0,
  "regularAmount": 5,
  "step": 1,
  "totalPayments": 0,
  "variableAmounts": false,
  "planTemplateReference": "PlanTemplateName"
}

A successful update returns HTTP 204. A failure returns HTTP 400 with an “ApiResponseBase” body:

{
  "success": false,
  "messages": [
    "Ordinal must be between 1 and 365."
  ]
}

Step 5 - Getting the schedule for a Plan

The schedule lists the collections that are due, or have already been made, for a Plan. An optional date range can be supplied.

Call type: GET

Url: https://api.paygateservicedemo.com/collections_public/api/payers/{groupId}/{payerReference}/plans/{planReference}/schedule?startDate=2026-12-01T00:00:00Z&endDate=2027-03-01T00:00:00Z

Response:

{
  "data": [
    {
      "payerReference": "SMITH0001",
      "planReference": "PLAN0001",
      "originalDate": "01/12/2026",
      "amount": 10.00,
      "submissionDate": "27/11/2026",
      "processingDate": "30/11/2026",
      "collectionDate": "01/12/2026",
      "transactionCode": "01",
      "status": "Pending",
      "suppressed": false,
      "pendingVariableAmount": false,
      "collectionFailed": false,
      "refundRequested": false,
      "canRepresent": false,
      "isRepresented": false
    }
  ],
  "count": 1
}

Items with “collectionFailed” set to true and “canRepresent” set to true can be resubmitted - see Collections API - Resubmission.