List Payment Links

Retrieves a paginated list of payment links with optional filtering and sorting capabilities.

Endpoint

GET /api/v1/paymentLinks

Header Parameters

Parameter	Type	Required	Description
x-api-key	string	required	PaySuite provided API key
merchantId	string	required	Customer identifier as provided during customer onboarding

Query Parameters

Parameter	Type	Required	Description
page	integer	optional	Page number (default: 1, minimum: 1)
pageSize	integer	optional	Number of items per page (default: 25)
search	string	optional	Search term to filter payment links
status	string[]	optional	Filter by status. Accepted values: created, in_progress, paid, partially_paid, expired, cancelled. Multiple values can be provided
sortField	string	optional	Field to sort by: CreatedAt, DueDate (default: CreatedAt)
sortDirection	string	optional	Sort direction: Ascending, Descending (default: Descending)

Response Parameters

Status Code: 200 OK

Parameter	Type	Description
paymentLinks	array	Array of PaymentLinkSummary objects
pagination	object	Pagination information (see PaginationInfo below)
stats	object	Summary statistics (see PaymentLinkSummaryStats below)

PaymentLinkSummary Object

Field	Type	Description
id	uuid	Unique identifier for the payment link
externalReference	string	External reference identifier
externalUrl	string	URL to the external provider's invoice
customerName	string	Customer's full name
email	string	Customer's email address
amount	long	Total payment link amount in minor units
currency	string	ISO 4217 currency code (e.g., GBP)
status	string	Payment link status
dueDate	dateTime	Payment due date (nullable)
createdAt	dateTime	Creation timestamp (ISO 8601)
daysOverdue	integer	Days past due date (null if not overdue)
paymentLink	string	Link to the payment detail page

PaginationInfo Object

Field	Type	Description
currentPage	integer	Current page number
totalPages	integer	Total number of pages
totalItems	integer	Total number of items
itemsPerPage	integer	Items displayed per page
hasNextPage	boolean	Whether there is a next page
hasPreviousPage	boolean	Whether there is a previous page

PaymentLinkSummaryStats Object

Field	Type	Description
totalOutstanding	long	Total unpaid amount in minor units
totalPaid	long	Total paid amount in minor units
overdueCount	integer	Number of overdue payment links
pendingCount	integer	Number of pending payment links

Example Request

GET /api/v1/paymentLinks?page=1&pageSize=10&status=created&sortField=CreatedAt&sortDirection=Descending

Example Response

{
  "paymentLinks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalReference": "INV-001",
      "externalUrl": "https://external-provider/inv-001",
      "customerName": "John Smith",
      "email": "[email protected]",
      "amount": 250000,
      "currency": "GBP",
      "status": "created",
      "dueDate": "2024-12-01T00:00:00Z",
      "createdAt": "2024-11-01T10:30:00Z",
      "daysOverdue": null,
      "paymentLink": "#payments/550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "id": "660f9511-f3ac-52e5-b827-557766551111",
      "externalReference": "INV-002",
      "externalUrl": "https://external-provider/inv-002",
      "customerName": "Jane Wilson",
      "email": "[email protected]",
      "amount": 180000,
      "currency": "GBP",
      "status": "created",
      "dueDate": "2024-11-25T00:00:00Z",
      "createdAt": "2024-10-25T14:20:00Z",
      "daysOverdue": null,
      "paymentLink": "#payments/660f9511-f3ac-52e5-b827-557766551111"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 47,
    "itemsPerPage": 25,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "stats": {
    "totalOutstanding": 1575000,
    "totalPaid": 825000,
    "overdueCount": 3,
    "pendingCount": 12
  }
}

Status Code: 400 Bad Request

Returned when query parameters are invalid.

Status Code: 401 Unauthorized

Returned when the API key is missing or invalid.