Collections API - Alerts, Messages and Reconciliation

Base URL

This tutorial uses the test URL:

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

Alerts

Alerts are raised against Payers, for example when a bank rejects an instruction or a collection fails. Monitoring them allows your application to act promptly.

Getting alerts

Call type: GET

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

To restrict to a single Group:

Url: https://api.paygateservicedemo.com/collections_public/api/Alerts/{groupId}

Optional query parameters:

Response:

[
  {
    "alertMessageId": "9a2c7e41-3b5d-4f08-8e6a-1c4d7b0f2e93",
    "payerHistoryId": "5d8f1a3c-7e2b-4c90-b6a4-0f3e9d2c8b15",
    "ukPayerId": "c4e8a1d2-9b3f-4e6a-a7d5-2f1b8c0e9a34",
    "generationDate": "2026-12-04T09:30:00Z",
    "title": "Collection failed",
    "alertLevel": "Warning",
    "payerHistoryMessageType": "CollectionFailed",
    "body": "The collection of 10.00 failed: Instruction cancelled by payer.",
    "groupName": "My Collections Group",
    "metaData": null,
    "total": 1,
    "payerReference": "SMITH0001"
  }
]

Clearing an alert

Once an alert has been dealt with it can be cleared.

Call type: DELETE

Url: https://api.paygateservicedemo.com/collections_public/api/Alerts/{alertId}

Response:

{
  "success": true
}

A 404 ProblemDetails is returned if the alert does not exist.

Messages

A message (for example a notification or reminder) can be sent to a Payer using one of the message types configured for the Group.

Call type: POST

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

Optional header: X-Idempotency-Key

Request:

{
  "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  "payerReference": "SMITH0001",
  "planReference": "PLAN0001",
  "messageType": "PaymentReminder",
  "channelType": "Email"
}

• “planReference” must be a Plan owned by the Payer.
• “channelType” is optional. By default the channel registered on the Payer is used. Overriding it returns a 400 if no email address is held for “Email”, or no mobile number for “SMS”.

A successful call returns HTTP 200. A 404 ProblemDetails is returned if the Payer or Plan cannot be found.

Reconciliation

Reconciliation retrieves the reports from the bank for a Group and applies them to your Payers and collections.

Call type: POST

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

Optional header: X-Idempotency-Key

Request:

{
  "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  "reportTypes": [
    "ARUDD",
    "AUDDIS",
    "ADDACS"
  ]
}

Response:

{
  "messages": [
    "ARUDD: 2 report(s) reconciled"
  ],
  "error": false
}

If “error” is true, the “messages” list gives the details. Any resulting alerts can be found using the Alerts endpoint above, and failed collections can be re-presented as described in Collections API - Resubmission.