# GET `/merchant/v1/payers`

[Documentation page](/api-reference/payers/payments.payers.list)

## Summary

List payers

## Description

Returns the payers that used this Recuut account in test or live data. The `as_of` time keeps the list unchanged while you read later pages.

## Security requirements

```json
[
  {
    "OrganizationApiKeyAuth": []
  }
]
```

## Operation parameters

### query `as_of`

```json
{
  "description": "Stable snapshot timestamp for this page sequence. Include a timezone; future timestamps are rejected.",
  "in": "query",
  "name": "as_of",
  "required": false,
  "schema": {
    "$ref": "#/components/schemas/SnapshotTimestamp"
  }
}
```

### query `order`

```json
{
  "description": "Show the newest or oldest records first.",
  "in": "query",
  "name": "order",
  "required": false,
  "schema": {
    "$ref": "#/components/schemas/ListOrder",
    "default": "newest"
  }
}
```

### query `page`

```json
{
  "description": "Page number to return. The first page is 1.",
  "in": "query",
  "name": "page",
  "required": false,
  "schema": {
    "$ref": "#/components/schemas/PageNumber",
    "default": 1
  }
}
```

### query `page_size`

```json
{
  "description": "Number of items to return on each page. Use 1 through 100.",
  "in": "query",
  "name": "page_size",
  "required": false,
  "schema": {
    "$ref": "#/components/schemas/PageSize",
    "default": 50
  }
}
```

## Responses

### 200

```json
{
  "content": {
    "application/json": {
      "examples": {
        "payer_page": {
          "summary": "Payer page",
          "value": {
            "as_of": "2026-08-12T09:30:00Z",
            "count": 1,
            "items": [
              {
                "created_at": "2026-08-01T08:00:00Z",
                "id": "pyr_00000000000070008000000000000000",
                "identifier": "0x1111111111111111111111111111111111111111",
                "last_transaction_at": "2026-08-12T09:30:00Z"
              }
            ],
            "next": null
          }
        }
      },
      "schema": {
        "$ref": "#/components/schemas/PagedPayerSchema"
      }
    }
  },
  "description": "OK"
}
```

### 401

```json
{
  "content": {
    "application/json": {
      "examples": {
        "unauthenticated": {
          "summary": "API key required",
          "value": {
            "code": "unauthenticated",
            "message": "A valid Recuut API key is required."
          }
        }
      },
      "schema": {
        "additionalProperties": false,
        "description": "Error returned for this endpoint and HTTP status.",
        "properties": {
          "code": {
            "const": "unauthenticated",
            "description": "Stable error code your app can check.",
            "type": "string"
          },
          "message": {
            "description": "Short explanation of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      }
    }
  },
  "description": "Unauthorized"
}
```

### 403

```json
{
  "content": {
    "application/json": {
      "examples": {
        "forbidden": {
          "summary": "Capability denied",
          "value": {
            "code": "forbidden",
            "message": "This API key does not allow this operation."
          }
        }
      },
      "schema": {
        "additionalProperties": false,
        "description": "Error returned for this endpoint and HTTP status.",
        "properties": {
          "code": {
            "const": "forbidden",
            "description": "Stable error code your app can check.",
            "type": "string"
          },
          "message": {
            "description": "Short explanation of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      }
    }
  },
  "description": "Forbidden"
}
```

### 422

```json
{
  "content": {
    "application/json": {
      "examples": {
        "invalid_request": {
          "summary": "Invalid request",
          "value": {
            "code": "invalid_request",
            "message": "The request is invalid."
          }
        }
      },
      "schema": {
        "additionalProperties": false,
        "description": "Error returned for this endpoint and HTTP status.",
        "properties": {
          "code": {
            "const": "invalid_request",
            "description": "Stable error code your app can check.",
            "type": "string"
          },
          "message": {
            "description": "Short explanation of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      }
    }
  },
  "description": "Unprocessable Content"
}
```

## First-party examples

### cURL

```json
{
  "label": "cURL",
  "lang": "shell",
  "source": "curl --request GET \\\n  --url \"$RECUUT_API_URL/merchant/v1/payers\" \\\n  --header \"Authorization: Bearer $RECUUT_API_KEY\"\n"
}
```

```shell
curl --request GET \
  --url "$RECUUT_API_URL/merchant/v1/payers" \
  --header "Authorization: Bearer $RECUUT_API_KEY"

```

## Canonical operation

```json
{
  "description": "Returns the payers that used this Recuut account in test or live data. The `as_of` time keeps the list unchanged while you read later pages.",
  "operationId": "payments.payers.list",
  "parameters": [
    {
      "description": "Stable snapshot timestamp for this page sequence. Include a timezone; future timestamps are rejected.",
      "in": "query",
      "name": "as_of",
      "required": false,
      "schema": {
        "$ref": "#/components/schemas/SnapshotTimestamp"
      }
    },
    {
      "description": "Show the newest or oldest records first.",
      "in": "query",
      "name": "order",
      "required": false,
      "schema": {
        "$ref": "#/components/schemas/ListOrder",
        "default": "newest"
      }
    },
    {
      "description": "Page number to return. The first page is 1.",
      "in": "query",
      "name": "page",
      "required": false,
      "schema": {
        "$ref": "#/components/schemas/PageNumber",
        "default": 1
      }
    },
    {
      "description": "Number of items to return on each page. Use 1 through 100.",
      "in": "query",
      "name": "page_size",
      "required": false,
      "schema": {
        "$ref": "#/components/schemas/PageSize",
        "default": 50
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "examples": {
            "payer_page": {
              "summary": "Payer page",
              "value": {
                "as_of": "2026-08-12T09:30:00Z",
                "count": 1,
                "items": [
                  {
                    "created_at": "2026-08-01T08:00:00Z",
                    "id": "pyr_00000000000070008000000000000000",
                    "identifier": "0x1111111111111111111111111111111111111111",
                    "last_transaction_at": "2026-08-12T09:30:00Z"
                  }
                ],
                "next": null
              }
            }
          },
          "schema": {
            "$ref": "#/components/schemas/PagedPayerSchema"
          }
        }
      },
      "description": "OK"
    },
    "401": {
      "content": {
        "application/json": {
          "examples": {
            "unauthenticated": {
              "summary": "API key required",
              "value": {
                "code": "unauthenticated",
                "message": "A valid Recuut API key is required."
              }
            }
          },
          "schema": {
            "additionalProperties": false,
            "description": "Error returned for this endpoint and HTTP status.",
            "properties": {
              "code": {
                "const": "unauthenticated",
                "description": "Stable error code your app can check.",
                "type": "string"
              },
              "message": {
                "description": "Short explanation of what went wrong.",
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          }
        }
      },
      "description": "Unauthorized"
    },
    "403": {
      "content": {
        "application/json": {
          "examples": {
            "forbidden": {
              "summary": "Capability denied",
              "value": {
                "code": "forbidden",
                "message": "This API key does not allow this operation."
              }
            }
          },
          "schema": {
            "additionalProperties": false,
            "description": "Error returned for this endpoint and HTTP status.",
            "properties": {
              "code": {
                "const": "forbidden",
                "description": "Stable error code your app can check.",
                "type": "string"
              },
              "message": {
                "description": "Short explanation of what went wrong.",
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          }
        }
      },
      "description": "Forbidden"
    },
    "422": {
      "content": {
        "application/json": {
          "examples": {
            "invalid_request": {
              "summary": "Invalid request",
              "value": {
                "code": "invalid_request",
                "message": "The request is invalid."
              }
            }
          },
          "schema": {
            "additionalProperties": false,
            "description": "Error returned for this endpoint and HTTP status.",
            "properties": {
              "code": {
                "const": "invalid_request",
                "description": "Stable error code your app can check.",
                "type": "string"
              },
              "message": {
                "description": "Short explanation of what went wrong.",
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          }
        }
      },
      "description": "Unprocessable Content"
    }
  },
  "security": [
    {
      "OrganizationApiKeyAuth": []
    }
  ],
  "summary": "List payers",
  "tags": [
    "payers"
  ],
  "x-codeSamples": [
    {
      "label": "cURL",
      "lang": "shell",
      "source": "curl --request GET \\\n  --url \"$RECUUT_API_URL/merchant/v1/payers\" \\\n  --header \"Authorization: Bearer $RECUUT_API_KEY\"\n"
    }
  ],
  "x-recuut-pagination": {
    "requestPage": "page",
    "requestSnapshot": "as_of",
    "responseCount": "count",
    "responseItems": "items",
    "responseNext": "next",
    "responseSnapshot": "as_of"
  }
}
```