Documentation
Knowledge baseContact
Start typing to search…

Settlement & clearing data

A settlement is a payment from PAY. to a merchant. To execute a settlement, it is checked whether there are clearings available for the merchant that can be paid. These clearings are generated in the morning, depending on the clearing frequency set in the Admin Panel.

A settlement usually contains one clearing, but it can also include multiple clearings, if for example transactions from different accounting periods are being paid out

PAY offers the following API's that allows you to automatically retrieve settlements, clearings, and transactions for a merchant.


📘

Would you like to use these APIs?

Contact PAY if you wish to use the above APIs. We need to activate an additional permissions group for this purpose.


Clearings:Settlements API

ℹ️ API Reference: Clearings:Settlements

Through the API Clearings:Settlements you can retrieve the settlements and their corresponding clearings for a merchant account. The response from this API looks as follows:

{
  "total": 1,
  "count": 1,
  "pages": 1,
  "settlements": [
    {
      "code": "SK6Y-7PBP",
      "description": "Clearing: CLEARING-20242977767/ Funds: 250.00",
      "settlementDate": "2024-10-02",
      "confirmationDate": "2024-10-02",
      "amount": {
        "value": 250,
        "currency": "EUR"
      },
      "baseAccountIban": "NL35RABO0117713678",
      "clearingAccount": {
        "method": "iban",
        "iban": {
          "iban": "NL64BANK1782371249",
          "bic": "BANKNL2A",
          "owner": "John Doe"
        }
      },
      "clearings": [
        {
          "clearingId": "CLEARING-20242977767",
          "clearingLines": [
            {
              "code": "FT-1234-1234-1234",
              "clearingDate": "2024-10-02",
              "settlementDate": "2024-10-02",
              "valueDate": "2024-10-02",
              "state": "PROCESSED",
              "turnoverGroup": {
                "code": "CT-1234-4321",
                "name": "Ecommerce"
              },
              "clearingLineType": {
                "id": 10,
                "name": "iDEAL",
                "direction": "CREDIT",
                "collecting": true
              },
              "amount": {
                "value": 250,
                "currency": "EUR"
              },
              "merchant": {
                "code": "M-1234-4321",
                "name": "CompanyName",
                "contractPackage": "Business"
              },
              "transactions": 1,
              "uniquePayers": 1
            }
          ]
        }
      ]
    }
  ],
  "_links": {
    "first": {
      "href": "/?page=1&limit=10"
    },
    "previous": {
      "href": "/?page=1&limit=10"
    },
    "next": {
      "href": "/?page=1&limit=10"
    },
    "last": {
      "href": "/?page=1&limit=10"
    },
    "self": {
      "href": "",
      "rel": "self",
      "type": "GET"
    }
  }
}

In the above API response:

  • One settlement was executed with the settlement code: SK6Y-7PBP (object settlements.code, line 7).
  • This settlement contained one clearing with ID: CLEARING-20242977767 (object clearings.clearingId, line 26).
  • This clearing included iDEAL transactions with a value of 250,00 EUR (object clearings.clearingLines).

If you do not provide any query parameters, you will receive all settlements and the corresponding clearings. This is often not desirable, so we recommend using pagination, possibly in combination with filtering.


Pagination

The API Clearings:Settlements supports pagination. When calling the API, you can use the page and limit fields to retrieve subsequent results.

In the API response, lines 2 (total), 3 (count), and 4 (pages) show how many results and pages are available. The __links _object (line 61) contains the API URLs for the first, previous, next, and last pages.


Filtering

In addition to pagination, it is also possible to add filters to obtain the results for a specific settlement, clearing, or merchant. The following filter fields are available when calling the API:



Clearing:Records API

ℹ️ API Reference: Clearing: Records

Through the API Clearing:Records, you can retrieve the transactions that have been paid out to the merchant in a settled payment. The response from this API looks as follows:

{
  "total": 1,
  "count": 1,
  "pages": 1,
  "clearingRecords": [
    {
      "reportingId": "RT-1234-4321-1234",
      "settlementCode": "SK6Y-7PBP",
      "clearingId": "CLEARING-20242977767",
      "orderId": "1234567891X33ce1",
      "description": "Example description",
      "reference": "12345678",
      "currencyAmount": {
        "value": 250,
        "currency": "EUR"
      },
      "amount": {
        "value": 250,
        "currency": "EUR"
      },
      "paymentMethod": {
        "id": 1,
        "name": "iDEAL"
      },
      "paymentProfile": {
        "id": 10,
        "name": "iDEAL",
        "direction": "CREDIT",
        "collecting": true
      },
      "turnoverGroup": {
        "code": "CT-1234-4321",
        "name": "Ecommerce"
      },
      "merchant": {
        "code": "M-1234-4321",
        "name": "CompanyName"
      },
      "transactionDate": "2024-10-01T10:54:21+01:00"
    }
  ],
  "_links": {
    "first": {
      "href": "/?page=1&limit=10"
    },
    "previous": {
      "href": "/?page=1&limit=10"
    },
    "next": {
      "href": "/?page=1&limit=10"
    },
    "last": {
      "href": "/?page=1&limit=10"
    },
    "self": {
      "href": "",
      "rel": "self",
      "type": "GET"
    }
  }
}

Pagination

The API Clearing:Records supports pagination. When calling the API, you can use the page and limit fields to retrieve subsequent results.

In the API response, lines 2 (total), 3 (count), and 4 (pages) show how many results and pages are available. The _links object (line 42) contains the API URLs for the first, previous, next, and last pages.


How do I obtain the settlement code?

The settlement code or clearing ID is a mandatory qeury parameter (Identifier) for the API Clearing:Records and can also be used as a filter in the API: Clearings:Settlements. You can obtain the settlement code as follows:

  1. in the response of the API Clearings:Settlements:
  "settlements": [
    {
      "code": "SK6Y-7PBP",

  1. Through the PAY Admin panel. Select the tab Merchant -> Invoices (Clearing) and scroll to the 'Settlement History' table. In the first column, you will find the settlement code.

How do I obtain the clearing ID?

The clearing ID or settlement code is a mandatory qeury parameter (Identifier) for the API Clearing:Records and can also be used as a filter in the API: Clearings:Settlements. You can obtain the clearing ID as follows:

  1. in the response of the API Clearings:Settlements:
 "clearings": [
        {
          "clearingId": "CLEARING-20242977767",

  1. Through the PAY Admin panel. Select the tab Merchant -> Invoices (Clearing) and scroll to the 'Settlement History' table. In the fourth column, you will find the clearing ID.
  1. You can also find the clearing ID on the bank statement of the IBAN number where the settlement was made. Please note that we can include a maximum of 2 clearing IDs on the bank statement due to the limited number of characters available.

Updated 3 months ago