Navigation :

Collections API - Payers

Base URL

This tutorial uses the test URL:

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

See Collections API - Getting Started for background, enumeration values and error formats.

Get API Groups

You will need a group ID to create a new Payer. This call will return the groups that can be used by the API to create a Payer. This step is optional if you already know the group ID to use for the Payer.

Collections groups have a Group Type of 2.

Call type: GET

URL: https://api.paygateservicedemo.com/bacs_publicapi/api/bacs/group

Example JSON Response:

[
  {
    "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
    "groupName": "Collections Group",
    "networkType": "BACS",
    "groupType": 2,
    "groupTypeDesc": "UKDDMS"
  }
]

Step 1 - Creating a Payer

A Payer is created with a POST to the payers endpoint. The request contains the Payer’s bank details, contact details and (optionally) one or more Plans.

Call type: POST

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

Optional header: X-Idempotency-Key

Required fields: “groupId”, “sortcode”, “accountNumber”, “accountHoldersName”, “firstname”, “surname”, “address1” and “postcode”.

“sortcode” accepts either a string six characters long comprised of numeric characters, or an eight characters long string comprising of thre sets of two numeric characters separated by hyphens.
“accountNumber” must be a string 8 characters long comprised of numeric characters..
“payerReference” is optional if the group the payer is being added to uses auto generated payer references. If supplied it must be 6 to 14 characters from A-Z, 0-9, space and & . / -.
“payerMessageType” is 0 (Email) or 1 (Letter).
“plans” is an array of Plan requests (see Plans).
“groupId” is the GUID identifier for the Collections Group that the payer will be created into, explained above.

Request:

{
  "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  "sortcode": "10-10-10",
  "accountNumber": "10101010",
  "accountHoldersName": "Mr John Smith",
  "payerMessageType": 0,
  "title": 0,
  "firstname": "John",
  "surname": "Smith",
  "payerReference": "SMITH0001",
  "address1": "15 High Street",
  "address2": "Fictional Business Park",
  "address3": "Fictional Area",
  "address4": "Fake Town",
  "postcode": "AA1 1AA",
  "email": "johnsmith@example.com",
  "tel1": "01234 567890",
  "mobile": "07123 456789",
  "customField1": "Membership 1234",
  "plans": [
    {
      "planTemplateReference": "MONTHLY10",
      "giftAid": false,
      "ordinal": 1,
      "recurrenceType": 1,
      "recurrenceEndType": 3,
      "regularAmount": 10.00,
      "step": 1
    }
  ]
}

Response:

{
  "self": {
    "url": "/api/payers/3d8ac4aa-4610-48a7-8d74-a5a3e192a42c/SMITH0001"
  },
  "status": 5,
  "paymentPlans": [
    "/api/payers/3d8ac4aa-4610-48a7-8d74-a5a3e192a42c/SMITH0001/plans/PLAN0001"
  ],
  "sortcode": "****10",
  "accountNumber": "******10",
  "accountHoldersName": "Mr John Smith",
  "payerMessageType": 0,
  "title": 0,
  "firstname": "John",
  "surname": "Smith",
  "payerReference": "SMITH0001",
  "address1": "15 High Street",
  "postcode": "AA1 1AA",
  "email": "johnsmith@example.com"
}

Bank details are masked in responses for security reasons.

Step 2 - Getting Payers

All Payers

Returns the Payers for the Group(s) available to the caller.

Call type: GET

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

All Payers in a Group

Call type: GET

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

Response:

{
  "payers": [
    {
      "self": { "url": "/api/payers/3d8ac4aa-4610-48a7-8d74-a5a3e192a42c/SMITH0001" },
      "status": 0,
      "payerReference": "SMITH0001",
      "firstname": "John",
      "surname": "Smith"
    }
  ]
}

A single Payer

Call type: GET

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

Returns a Payer response as shown in Step 1, or a 404 ProblemDetails if the Payer does not exist.

Step 3 - Updating a Payer

Call type: PUT

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

The request has the same fields as creating a Payer, but without “payerReference” and “plans”. The required fields must be supplied on every update.

Request:

{
  "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  "sortcode": "101010",
  "accountNumber": "10101010",
  "accountHoldersName": "Mr John Smith",
  "payerMessageType": 2,
  "title": 0,
  "firstname": "John",
  "surname": "Smith",
  "address1": "20 Low Street",
  "postcode": "AA1 2BB",
  "mobile": "07123 456789"
}

Response:

{
  "success": true,
  "messages": []
}

A 400 or 404 returns the same structure with “success” set to false and the reason in “messages”.

Step 4 - Updating the status of a Payer

Call type: POST

Url: https://api.paygateservicedemo.com/collections_public/api/payers/status

Request:

{
  "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  "payerReference": "SMITH0001",
  "status": 1
}

The “status” is a PayerStatus value (for example 1 = Suspended, 3 = Closed).

Response:

{
  "success": true,
  "messages": []
}

Step 5 - Updating multiple Payers

Plan details can be changed for many Payers in a single call.

Call type: PUT

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

Optional header: X-Idempotency-Key

Request:

{
  "groupId": "3d8ac4aa-4610-48a7-8d74-a5a3e192a42c",
  "updateRequests": [
    {
      "payerReference": "SMITH0001",
      "planReference": "PLAN0001",
      "newRecurrenceType": "Monthly",
      "newRecurrenceEndType": "Ongoing",
      "newOrdinal": 15,
      "newRegularAmount": 12.50
    },
    {
      "payerReference": "JONES0002",
      "planReference": "PLAN0001",
      "newRegularAmount": 20.00
    }
  ]
}

A successful call returns HTTP 200 with no body.

Step 6 - Deleting a Payer

Call type: DELETE

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

Response:

{
  "success": true,
  "messages": []
}

A 404 ProblemDetails is returned if the Payer cannot be found.