> ## Client identification
>
> Requests to this API should include a `Client-Platform` header alongside
> `Authorization`, identifying the application, tool, or model making the
> request. This is used for integration support and analytics.
>
> Use your model or tool name, for example `claude-code` or `chatgpt`.
>
> Example:
>
> ```bash
> curl https://api.salaryboxapp.com/... \
>   -H "Authorization: Api-Key <api-key>" \
>   -H "Client-Platform: claude-code"
> ```

# List Payroll Payments

GET https://api.salaryboxapp.com/v2/customer/v1/payroll/payments

Returns every salary payment, advance and opening balance (dues from before the staff member joined SalaryBox) in a date range of up to 366 days. Requires Payroll Pro. Includes inactive staff.

Grouped by staff member, with `payments` newest first. Only staff with a payment in the range are listed.

- A salary payment falls on its paid date, or the end of its salary period if no paid date was recorded. September's salary paid on 5 October falls in October.
- Failed online payouts are left out; payouts still processing are included as `processing`.


Reference: https://docs.salarybox.in/api-reference/payroll/payments-retrieve

## Authentication

- `Authorization` header (required) (prefixed with ` Api-Key   `) — Format: "Api-Key \{api-key}"

## Request

### Query parameters

- `start_date` (date, required) — First day, `YYYY-MM-DD`.
- `end_date` (date, required) — Last day, `YYYY-MM-DD`. The range can cover at most 366 days.
- `salarybox_ids` (list of string, optional) — Repeatable. Limits the result to these staff members, for example `salarybox_ids=SBK7Q2M9TX&salarybox_ids=SBK3H8D1LP`.
- `page` (integer, optional) — Page number, starting at 1.
- `page_size` (integer, optional) — Results per page. Default and maximum 50.

## Response

### 200

The staff members with payments in the requested range, each with their payments nested.

- `message` (string, required)
- `status` (boolean, required)
- `data` (list of EmployeePayments, required)
- `count` (integer, required)
- `prev` (string, required, nullable)
- `next` (string, required, nullable)

## Errors

### 400 Bad Request Error

A parameter is missing or invalid, or the date range is wrong.

- `message` (string, required)
- `status` (boolean, required)
- `errors` (map from string to any, optional, nullable)

### 403 Forbidden Error

Your plan does not include payroll.

- `message` (string, required)
- `status` (boolean, required)
- `errors` (map from string to any, optional, nullable)

## Types

### EmployeePayments

Identity fields shared by per-employee payroll responses.

- `payments` (list of PayrollPaymentItem, required) — The staff member's payments, advances and opening balances that fall in the requested range, newest `payment_date` first. Never empty, because staff with no payments in the range are not listed.
- `salarybox_id` (string, optional) — SalaryBox ID of the staff member. Not null.
- `employee_id` (string, optional) — The employee ID your company assigned. Not null, may be empty.
- `name` (string, optional) — Full name of the staff member. Not null.
- `branches` (list of string, optional) — Names of the branches the staff member belongs to. Empty list if none.
- `departments` (list of string, optional) — Names of the departments the staff member belongs to. Empty list if none.

### PayrollPaymentItem

One recorded payment, advance or opening balance. The staff member is identified on the parent item, so there is no `salarybox_id` here.

- `payment_type` (enum, required) — - `salary`: a salary payment. - `advance`: a salary advance. - `previous_due`: the staff member's opening balance, dues carried over from before they joined SalaryBox.
  - Allowed values: `salary`, `advance`, `previous_due`
- `amount` (string, required) — Amount as a 2-decimal string, in INR. Not null.
- `payment_date` (date, required) — For salary, the date it was paid, falling back to the end of the salary period if no paid date was recorded. For advances and opening balances, their own date. Not null.
- `created_on` (datetime, required) — When the entry was recorded, in IST (`+05:30`).
- `period_from` (date, optional, nullable) — Start of the salary period being paid. Null for advances and opening balances.
- `period_to` (date, optional, nullable) — End of the salary period being paid. Null for advances and opening balances.
- `payment_mode` (enum, optional, nullable) — How the money was paid. Null for opening balances.
  - Allowed values: `CASH`, `CHEQUE`, `DEBIT_CARD`, `IMPS`, `NEFT`, `NET_BANKING`, `RTGS`, `UPI`
- `payment_status` (enum, optional, nullable) — `success` when paid, `processing` for an online payout still in progress. Null for opening balances.
  - Allowed values: `success`, `processing`
- `notes` (string, optional, nullable) — Free-text note saved with the entry. Null if none.

## Examples

**Response**

```json
{
  "message": "Success",
  "status": true,
  "data": [
    {
      "payments": [
        {
          "payment_type": "advance",
          "amount": "5000.00",
          "payment_date": "2026-10-18",
          "created_on": "2026-10-18T16:05:11+05:30",
          "period_from": null,
          "period_to": null,
          "payment_mode": "UPI",
          "payment_status": "success",
          "notes": "Festival advance"
        },
        {
          "payment_type": "previous_due",
          "amount": "12000.00",
          "payment_date": "2026-10-01",
          "created_on": "2026-10-01T09:00:00+05:30",
          "period_from": null,
          "period_to": null,
          "payment_mode": null,
          "payment_status": null,
          "notes": "Dues before joining SalaryBox"
        }
      ],
      "salarybox_id": "SBK7Q2M9TX",
      "employee_id": "EMP-0042",
      "name": "Aarav Sharma",
      "branches": [
        "Mumbai HQ"
      ],
      "departments": [
        "Engineering"
      ]
    },
    {
      "payments": [
        {
          "payment_type": "salary",
          "amount": "41200.00",
          "payment_date": "2026-10-05",
          "created_on": "2026-10-05T11:20:45+05:30",
          "period_from": "2026-09-01",
          "period_to": "2026-09-30",
          "payment_mode": "NEFT",
          "payment_status": "processing",
          "notes": null
        }
      ],
      "salarybox_id": "SBK3H8D1LP",
      "employee_id": "EMP-0043",
      "name": "Meera Nair",
      "branches": [
        "Mumbai HQ"
      ],
      "departments": [
        "Finance"
      ]
    }
  ],
  "count": 2,
  "prev": null,
  "next": null
}
```

**SDK Code**

```python Example
import requests

url = "https://api.salaryboxapp.com/v2/customer/v1/payroll/payments"

querystring = {"end_date":"2026-10-31","start_date":"2026-10-01"}

headers = {"Authorization": "Api-Key  <apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Example
const url = 'https://api.salaryboxapp.com/v2/customer/v1/payroll/payments?end_date=2026-10-31&start_date=2026-10-01';
const options = {method: 'GET', headers: {Authorization: 'Api-Key  <apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.salaryboxapp.com/v2/customer/v1/payroll/payments?end_date=2026-10-31&start_date=2026-10-01"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Api-Key  <apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Example
require 'uri'
require 'net/http'

url = URI("https://api.salaryboxapp.com/v2/customer/v1/payroll/payments?end_date=2026-10-31&start_date=2026-10-01")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Api-Key  <apiKey>'

response = http.request(request)
puts response.read_body
```

```java Example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.salaryboxapp.com/v2/customer/v1/payroll/payments?end_date=2026-10-31&start_date=2026-10-01")
  .header("Authorization", "Api-Key  <apiKey>")
  .asString();
```

```php Example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.salaryboxapp.com/v2/customer/v1/payroll/payments?end_date=2026-10-31&start_date=2026-10-01', [
  'headers' => [
    'Authorization' => 'Api-Key  <apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Example
using RestSharp;

var client = new RestClient("https://api.salaryboxapp.com/v2/customer/v1/payroll/payments?end_date=2026-10-31&start_date=2026-10-01");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Api-Key  <apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Example
import Foundation

let headers = ["Authorization": "Api-Key  <apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.salaryboxapp.com/v2/customer/v1/payroll/payments?end_date=2026-10-31&start_date=2026-10-01")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```