List payments

Overview

Retrieve a paginated list of all payments across the business. Payments are associated with invoices and include details like amount, channel, and payment date.

This endpoint supports pagination via query parameters. By default, it returns 25 records per page.

Path

GET /api/v1/payments

Path Parameters

None.

Query Parameters

Parameter	Type	Required	Description	Default
`page`	integer	No	Page number for pagination.	1
`per_page`	integer	No	Number of records per page.	25

Request Headers

Content-Type: application/json
Authorization: Bearer <token> (OAuth 2.0 token)

Request Body

None.

Response

Success (200 OK)

Returns a JSON object with a data array of payment objects, pagination metadata in meta, and navigation links in links.

Response Body Schema

{
  "data": [
    {
      "id": integer,
      "reference": string,
      "invoice_id": integer,
      "channel": string (e.g., "cash", "card"),
      "amount": {
        "cents": integer,
        "currency_iso": string (e.g., "USD")
      },
      "paid_at": string (ISO 8601 datetime),
      "emailed_at": string|null (ISO 8601 datetime),
      "created_at": string (ISO 8601 datetime),
      "updated_at": string (ISO 8601 datetime),
      "url": string (full API URL to the payment)
    }
  ],
  "meta": {
    "pagination": {
      "current_page": integer,
      "prev_page": integer|null,
      "next_page": integer|null,
      "total_pages": integer,
      "total_count": integer
    }
  },
  "links": {
    "first": string (URL),
    "last": string (URL),
    "next": string|null (URL),
    "self": string (URL)
  }
}

Example Response

{
  "data": [
    {
      "id": 28,
      "reference": "PYM-7C0F-6335",
      "invoice_id": 59,
      "channel": "card",
      "amount": {
        "cents": 4300,
        "currency_iso": "USD"
      },
      "paid_at": "2025-08-28T18:47:46.394Z",
      "emailed_at": "2025-08-28T18:48:36.154Z",
      "created_at": "2025-08-28T18:47:46.407Z",
      "updated_at": "2025-08-28T18:49:03.796Z",
      "url": "http://localhost:3000/api/v1/payments/28.json"
    },
    {
      "id": 22,
      "reference": "PYM-6563-2775",
      "invoice_id": 63,
      "channel": "cash",
      "amount": {
        "cents": 32300,
        "currency_iso": "USD"
      },
      "paid_at": "2025-08-28T00:00:00.000Z",
      "emailed_at": "2025-08-28T18:29:37.498Z",
      "created_at": "2025-08-28T18:29:07.070Z",
      "updated_at": "2025-08-28T18:30:10.442Z",
      "url": "http://localhost:3000/api/v1/payments/22.json"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "prev_page": null,
      "next_page": 2,
      "total_pages": 2,
      "total_count": 17
    }
  },
  "links": {
    "first": "http://localhost:3000/api/v1/payments.json?page=1",
    "last": "http://localhost:3000/api/v1/payments.json?page=2",
    "next": "http://localhost:3000/api/v1/payments.json?page=2",
    "self": "http://localhost:3000/api/v1/payments.json?page=1"
  }
}

Errors

Status Code	Description	Example Body
401 Unauthorized	Invalid or missing token.	`{"error": "Unauthorized"}`
403 Forbidden	Insufficient permissions.	`{"error": "Forbidden"}`
422 Unprocessable Entity	Invalid query parameters (e.g., negative page).	`{"errors": {"page": ["must be greater than 0"]}}`
500 Internal Server Error	Server error.	`{"error": "Internal Server Error"}`

Usage Notes

Use this endpoint to fetch all payments for reporting or reconciliation.
Paginate through results using the links.next URL for large datasets.
Amounts are stored in cents to avoid floating-point issues.

We are using cookies to improve your experience!