# List payments

> Returns the payments of your store in the environment of the key, newest first, 20 at a time by default.

Source: https://rais.app/docs/api/list-payments

`GET /v1/payments`

Required scope: `payments:read`.

Filter by `status`, by your own `reference`, or by creation time (Unix seconds); page with `starting_after`.

## Request

### Query parameters

- `status` (string, optional): Only payments with this status. One of `pending`, `paid`, `failed`, `cancelled`, `expired`, `refunded`, `partially_refunded`, `reversed`.
- `reference` (string, optional): Only payments with exactly this `reference`. At most 64 characters.
- `created_gte` (integer, optional): Only payments created at or after this Unix time (seconds). Between 0 and 253402300799.
- `created_lte` (integer, optional): Only payments created at or before this Unix time (seconds). Between 0 and 253402300799.
- `limit` (integer, optional): How many objects to return: 1 to 100 (default 20). Between 1 and 100. Default `20`.
- `starting_after` (string, optional): The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object). At most 100 characters.

### Example request

```bash
curl 'https://api.rais.app/v1/payments?status=paid&limit=3' \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: A page of payments.

- `object` (string): Always `list`. Always `list`.
- `data` (array of Payment): The payments of this page, newest first.
- `has_more` (boolean): True when there are older payments: pass `next_cursor` as `starting_after`.
- `next_cursor` (string, nullable): The value to pass as `starting_after` to get the next page; null on the last page.

```json
{
  "object": "list",
  "data": [
    {
      "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "object": "payment",
      "status": "pending",
      "amount": 500000,
      "currency": "DZD",
      "description": "Order #1042",
      "reference": "order-1042",
      "customer": {
        "id": null,
        "name": "Amina Benali",
        "email": "amina@example.dz",
        "phone": "+213550000000"
      },
      "items": [
        {
          "name": "Running shoes",
          "description": null,
          "quantity": 2,
          "unit_amount": 250000
        }
      ],
      "metadata": {
        "cart_id": "c_8812"
      },
      "livemode": false,
      "payment_page": "rais",
      "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "success_url": "https://shop.example/thanks",
      "cancel_url": "https://shop.example/cart",
      "expires_at": 1793003600,
      "created": 1793000000,
      "paid_at": null,
      "amount_refunded": 0,
      "refunded": false,
      "fees": null,
      "net": null,
      "receipt_url": null,
      "failure": null,
      "payment_method": null,
      "processor": {
        "name": "satim",
        "order_id": "V721uPPfNNofVQAAABL3",
        "approval_code": null,
        "response_code": null
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_parameter` | Invalid value. |
| 400 | `invalid_cursor` | No such payment: the starting_after cursor is unknown. |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Pagination](https://rais.app/docs/pagination.md)