Whats New

ListPayments endpoint for payment data retrieval

If you use the DDCMS API to manage contracts and payments, you can now retrieve payment data with advanced filtering and pagination, without needing to log in to the DDCMS interface or rely on batch reports. This new endpoint provides flexible, self-service access to payment history and status via your own systems.

Overview

A new POST endpoint has been introduced:

ListPayments — retrieves a paginated list of payments with optional filters for contract, customer, status, payment type, credit/debit, scheduled/ad-hoc, and multiple date dimensions. Results are sorted by date added (most recent first) by default.

Prerequisites

Before using the API endpoint, please ensure the following:

You have a valid API key.
You know your client prefix.

Authentication

All requests must be authenticated using an API key, passed as a header in your request:

apiKey: {apiKey}

List payments

Send a POST request with a JSON body to retrieve payments matching your filter criteria. Results are returned in paginated batches with metadata to help you navigate through large datasets.

Endpoint: POST {ddcms url}/api/v3/client/{clientPrefix}/payments

Input params: all filters in the JSON request body (see table below)

Request body fields

Field	Type	Description
pageNumber	integer	Optional. Page number to retrieve. Default: 1.
pageSize	integer	Optional. Records per page. Default: 100. Upper limit: 10,000 (configurable) — exceeding it returns a 400 error.
contractId	GUID	Optional. Returns only payments for the specified contract.
customerId	GUID	Optional. Returns only payments for the specified customer.
isCredit	boolean	Optional. Returns only credit (true) or debit (false) payments.
isScheduled	boolean	Optional. Returns only scheduled/system-generated (true) or ad-hoc (false) payments.
status	enum	Optional. Accepted values: "Indemnity Claimed", "Paid", "Pending", "Represented", "Unpaid", "Withdrawn".
type	enum	Optional. Accepted values: "Credit", "Final", "First Time", "Regular", "Retry".
collectionDateFrom	date	Optional. Start of the due date range filter.
collectionDateTo	date	Optional. End of the due date range filter.
createdAfter	date	Optional. Returns payments created after this date (Date Added).
createdBefore	date	Optional. Returns payments created before this date (Date Added).

All filters are optional. When multiple filters are provided, the endpoint returns payments matching all specified criteria.

Note: If both contractId and customerId are provided, only contractId is used. The customerId filter is ignored when a contractId is present.

Date field clarification

In the response, CollectionDate represents the Due Date (the scheduled/requested date). DateOfCollection represents the actual Date of Collection, which is only populated once the payment has been processed.

Pagination metadata

The response wraps results in a Pagination object containing:

Field	Description
Page	The current page number.
PageSize	The number of records returned per page.
TotalPages	The total number of pages available.
TotalRecords	The total number of records matching your filter criteria.

On success, the endpoint returns a 200 OK response with a JSON body containing the Pagination metadata and a Data array of payment records.

Response field reference

Each payment record in the Data array contains the following fields:

Field	Type	Notes
Id	uuid	System-generated. Always returned.
ContractId	uuid	Always returned.
CustomerId	uuid	Convenience field. Always returned.
DirectDebitReference	string	Convenience field. Always returned.
PaymentReference	string	Conditional: client’s own reference for reconciliation.
Amount	integer	In pence. Always returned.
CollectionDate	date	Scheduled/requested date (Due Date). Always returned.
DateOfCollection	date	Conditional: actual collection date, only present once processed.
Status	enum	Indemnity Claimed, Paid, Pending, Represented, Unpaid, Withdrawn. Always returned.
Type	enum	Credit, Final, First Time, Regular, Retry. Always returned.
Method	enum	bacs, receipt, faster_payment. Always returned.
ReceiptType	enum	Conditional: only when method is receipt. Values: bank_transfer, cash, pdq, postal_order, cheque, sage_pay, write_off, ddica_manual_refund, ddica_manual_cancellation, ddica_auto_cancellation.
IsCredit	boolean	Default false. Always returned.
IsScheduled	boolean	True if system-generated. Always returned.
Comment	string	Conditional: max 255 characters.
DisbursalId	uuid	Conditional: only when payment has been disbursed.
SubmissionFiIeId	uuid	Conditional: only when included in a BACS submission.
Rejection	object	Conditional: only present when a rejection reason exists. Contains Reason (string) and Date (date).
CreatedAt	datetime	ISO 8601 UTC. Always returned.

Example response

{

"Pagination": {

"Page": 1,

"PageSize": 100,

"TotalPages": 1,

"TotalRecords": 1

"Data": [

{

"Id": "6d7d791a-1fb7-4035-bc53-45ff4166654c",

"ContractId": "8ffa5dff-d53a-428e-9427-510d04002f6a",

"CustomerId": "be8305fd-8671-4f67-9c4c-e25b1182fca0",

"DirectDebitReference": "AAA-DEF442ZJ0M",

"PaymentReference": null,

"Amount": 833,

"CollectionDate": "2026-04-14T00:00:00",

"DateOfCollection": "2026-04-14T00:00:00",

"Status": "Paid",

"Type": "First Time",

"Method": "BACS",

"ReceiptType": null,

"IsCredit": false,

"IsScheduled": true,

"Comment": "",

"DisbursalId": null,

"SubmissionFileId": "929f2e06-a6aa-40c4-8beb-76aa11f29c43",

"Rejection": {

"Reason": "Invalid Details",

"Date": "2026-04-14T00:00:00"

"CreatedAt": "2026-04-10T00:00:00"

}

]

}

HTTP response codes

The endpoint returns standard HTTP status codes. The table below summarises the possible responses:

HTTP Status	Scenario
200 OK	Payments retrieved successfully. Returns an empty Data array if no payments match the filter criteria.
400 Bad Request	{specific error message} — e.g. invalid filter value, invalid status or type, pageSize exceeds 10,000 limit.
403 Forbidden	This contract cannot be used in API. When contract is protected.
500 Internal Server Error	An unexpected error occurred while processing the request.

API documentation

Full API specification for this endpoint, including request/response schemas and samples, will be available in the DDCMS API documentation upon deployment:

https://api-docs-ddcms-v3.accesspaysuite.com/