Viewing Settlements

API Documentation for Viewing Settlements with Filters and Paging

This document provides detailed instructions for developers to view the settlement details for a specific merchant using the provided API, with added functionality for filtering and paging.

Endpoint

• URL: /api/merchants/{merchantId}/settlements
• Method: GET
• Content-Type: application/json

Description

This API endpoint allows you to retrieve settlement details for a specific merchant, with options to filter results and paginate the response.

Request URL

Replace {merchantId} with the actual merchant ID.

https://api.paylink.sa/api/merchants/{merchantId}/settlements

HTTP Method

• GET

Request Headers

• Content-Type: application/json
• X-API-KEY: your_api_key

Query Parameters

• status (optional, string): Filter settlements by status. Example: ?status=completed
• startDate (optional, string): Filter settlements created after this date (inclusive), in YYYY-MM-DD format. Example: ?startDate=2024-01-01
• endDate (optional, string): Filter settlements created before this date (inclusive), in YYYY-MM-DD format. Example: ?endDate=2024-12-31
• page (optional, integer): The page number for pagination. Example: ?page=1
• pageSize (optional, integer): The number of settlements per page. Example: ?pageSize=10

Example curl Command

curl -X GET 'https://api.paylink.sa/api/merchants/{merchantId}/settlements?status=completed&startDate=2024-01-01&endDate=2024-12-31&page=1&pageSize=10' \
-H "Content-Type: application/json" \
-H "X-API-KEY: your_api_key"

Replace {merchantId} with the actual merchant ID and your_api_key with your actual API key in the headers.

Success Response

If the request is successful, you will receive a 200 OK status code with the following response body:

{
  "settlements": [
    {
      "settlementId": "settlement123",
      "amount": 10000,
      "status": "completed",
      "date": "2024-06-30",
      "invoiceIds": ["unique_invoice_id_1", "unique_invoice_id_2"],
      "iban": "SA1234567890123456789012"
    }
    // Additional settlements
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 5,
    "totalItems": 50
  }
}

Error Response

If there is an error in the request, you will receive a 400 Bad Request status code with an error message:

{
  "message": "Invalid request data"
}

By following these steps and using the provided documentation, you should be able to successfully view settlement details for a specific merchant with filtering and paging options using the API.