Collections

Very often when using the SlimPay API, you’ll want to retrieve sets of related resources (when following a search- relation, for example). These resources are returned by the server as paginated lists of elements, called collections.

Below is an example of a collection of mandate resources:

{
    "_embedded" : {
        "mandates" : [ {
            "_links" : {
                ...
            },
            "reference" : "SLMP001",
            ...
        }, 
        {
            "_links" : {
                ...
            },
            "reference" : "SLMP002",
            ...
        },
        {
            "_links" : {
                ...
            },
            "reference" : "SLMP003",
            ...
            }
        ] 
    },
    "_links" : {
        "first" : {
            "href" : "https://api.preprod.slimpay.com/mandates?creditorReference=democreditor&dateSignedBefore=2024-02-07T22%3A59%3A59.999Z&dateSignedAfter=2023-05-31T22%3A00%3A00.000Z&withPageMetadata=false&size=10"
        },
        "self" : {
            "href" : "https://api.preprod.slimpay.com/mandates?creditorReference=democreditor&dateSignedBefore=2024-02-07T22%3A59%3A59.999Z&dateSignedAfter=2023-05-31T22%3A00%3A00.000Z&withPageMetadata=false&size=10"
        },
        "next" : {
            "href" : "https://api.preprod.slimpay.com/mandates?creditorReference=democreditor&dateSignedBefore=2024-02-07T22%3A59%3A59.999Z&dateSignedAfter=2023-05-31T22%3A00%3A00.000Z&withPageMetadata=false&size=10"
        },
        "search" : {
            "href" : "https://api.preprod.slimpay.com/mandates{?creditorReference,entityReference,subscriberReference,mandateReference,paymentScheme,creationChannel,dateSignedBefore,dateSignedAfter,state,iban,signatoryLastName,signatoryEmail,companyName,embed,withPageMetadata,page,size}",
            "templated" : true
        }
    },
    "page": {
        "size": 10,
        "totalElements": 13,
        "totalPages": 2,
        "number": 0
    }
}

The page property is common to any paginated system of data transfer. This allows for large sets of information to be divided into discrete subsets. From the example above, we can see that:

  • We are currently at page number 5 (starting from 0)
  • Each page has a size of 3 elements
  • The total number of pages is 15
  • There are 43 elements in total

The first _links special property is the list of links related to the collection of subscribers. It contains the following keys:

  • self: the current page
  • first: the first page
  • last: the last page
  • prev: the previous page (if number > 0)
  • next: the next page (if number + 1 < totalPages)
  • search: the URL template of the initial search

The mandate elements themselves can be found in the _embedded special property. Each element is the representation of a mandate resource, with its own state and links.

Performance enhancement:

We introduced a new query parameter to ignore page metadata in the response.

The impact on the response is that there will be neither page property nor last link in _links property.

So you should add withPageMetadata=false in the API request.

Below is an example of a collection of mandates resources without page property: 

{
    "_embedded" : {
        "mandates" : [ {
            "_links" : {
                ...
            },
            "reference" : "SLMP001",
            ...
        }, 
        {
            "_links" : {
                ...
            },
            "reference" : "SLMP002",
            ...
        },
        {
            "_links" : {
                ...
            },
            "reference" : "SLMP003",
            ...
        } ]
    },
    "_links" : {
        "first" : {
            "href" : "https://api.preprod.slimpay.com/mandates?creditorReference=democreditor&dateSignedBefore=2024-02-07T22%3A59%3A59.999Z&dateSignedAfter=2023-05-31T22%3A00%3A00.000Z&withPageMetadata=false&size=10"
        },
        "self" : {
            "href" : "https://api.preprod.slimpay.com/mandates?creditorReference=democreditor&dateSignedBefore=2024-02-07T22%3A59%3A59.999Z&dateSignedAfter=2023-05-31T22%3A00%3A00.000Z&withPageMetadata=false&size=10"
        },
        "next" : {
            "href" : "https://api.preprod.slimpay.com/mandates?creditorReference=democreditor&dateSignedBefore=2024-02-07T22%3A59%3A59.999Z&dateSignedAfter=2023-05-31T22%3A00%3A00.000Z&withPageMetadata=false&size=10"
        },
        "search" : {
            "href" : "https://api.preprod.slimpay.com/mandates{?creditorReference,entityReference,subscriberReference,mandateReference,paymentScheme,creationChannel,dateSignedBefore,dateSignedAfter,state,iban,signatoryLastName,signatoryEmail,companyName,embed,withPageMetadata,page,size}",
            "templated" : true
        }
    }
}

So, you have to navigate between pages using the next and previous links.

Besides, to improve the response time you should add a filter on the date. We recommend a 2-week date range (or less).

Below is an example of a request for a collection of mandates ignoring the page metadata and filtering on the date: 

https://api.preprod.slimpay.com/mandates?creditorReference=democreditor&dateSignedBefore=2024-02-07T22%3A59%3A59.999Z
&dateSignedAfter=2023-05-31T22%3A00%3A00.000Z&withPageMetadata=false

Finally, only resources on this list support the withPageMetadata parameter:

  • payments
  • payment-issues
  • files
  • recurrent-direct-debits
  • mandates
  • orders
  • documents
  • subscribers