---
title: "List payables for the entity"
method: GET
path: "/payables"
tags: ["Payables"]
---

# List payables for the entity

`GET /payables`

Returns a paginated list of payables scoped to the entity named by `shinkansen_fin_id` (authorized against the authenticated customer). This is the only read on the Integrator API and needs no signature (there is no body to sign).

Every endpoint under `/payables` requires an API key whose scopes include `payables:all` (or the catch-all `all`).

Filtering, sorting and pagination follow the standard Flop conventions used across the Treasury API:
- **Pagination:** `page` and `page_size` (max 100, defaults to 50).
- **Sorting:** `order_by` (one or more of `id`, `bank_account_id`, `amount`, `due_date`, `inserted_at`, `updated_at`) and `order_directions` (`asc` / `desc`).
- **Filtering:** `filters[N][field]`, `filters[N][op]`, `filters[N][value]`. Filterable fields: `id`, `external_id`, `state`, `payable_type`, `currency`, `amount`, `due_date`, `description`, `bank_account_id`, `payment_rail`, `dispatch_policy`, `execution_hint`, `inserted_at`, `updated_at`, and `search` — a free-text `ilike` over `external_id` and `description`, its only supported operator. Example: `filters[0][field]=state&filters[0][op]=%3D%3D&filters[0][value]=waiting_order`.

A field that is filterable but not sortable (`external_id`, `state`, …) is rejected with a `422` when passed in `order_by`.

## Query parameters

- `shinkansen_fin_id` string, required
- `page` integer
- `page_size` integer
- `order_by` string[]
- `order_directions` string[]

## Response `200`

A paginated list of payables for the entity, plus pagination metadata.

- object
  - `payables` PayableResult[], required — The payables on this page.
    - `id` integer, required — System-assigned identifier of the payable.
    - `external_id` string, required — Identifier of the commitment in the source system.
    - `local_entity_id` integer, required — Entity that owns the payable (resolved from the signed sender).
    - `payable_type` string, nullable — Type of the payable, configured per entity.
    - `amount` string, required — Amount owed, as a decimal string. Values read back from storage carry the column's scale (5 decimals, e.g. `150000.00000`); the creation response echoes the amount as it was sent.
    - `currency` string, required — ISO 4217 currency code.
    - `state` 'waiting_order' | 'ordered' | 'taken' | 'paid' | 'wont_pay', required — Current state of the payable.
    - `due_date` string, date, nullable — Due date of the commitment.
    - `description` string, nullable — Human-readable description.
    - `metadata` object — Free-form metadata.
    - `debtor` object, nullable — Paying account, rebuilt from the resolved bank account (reflects the account the payable will actually charge). `null` when no paying account is set yet.
      - `financial_institution` object
        - `fin_id_schema` string — Always `SHINKANSEN`.
        - `fin_id` string — Shinkansen id of the paying bank.
      - `account` string — Account number of the paying account.
      - `account_type` string, nullable — Account type.
    - `creditor` object, nullable — Payee, in ISO 20022 vocabulary. `null` when no payee is set yet.
      - `name` string, nullable
      - `email` string, nullable
      - `account` string, nullable
      - `account_type` string, nullable
      - `identification` object, nullable — Present only when an id was supplied.
        - `id` string
        - `id_schema` string
      - `financial_institution` object, nullable — Present only when a destination bank was supplied.
        - `fin_id` string
        - `fin_id_schema` string
    - `payment_rail` string, nullable — Routing hint carried by the payable. Same values as the `payment_rail` request field.
    - `execution_mode` 'default' | 'immediate' | 'deferred' | 'null', nullable — Routing hint carried by the payable.
    - `dispatch_policy` 'automatic' | 'manual' | 'null', nullable — Declared PayoutOrder generation policy.
    - `execution_hint` 'internal' | 'external' | 'null', nullable — Who executes the payment.
    - `inserted_at` string, date-time — Creation timestamp.
    - `updated_at` string, date-time — Last update timestamp.
  - `meta` object, required — Pagination metadata.
    - `current_page` integer — Current page number.
    - `current_offset` integer — Offset of the first element on this page.
    - `total_count` integer — Total number of payables matching the query.
    - `total_pages` integer — Total number of pages.
    - `start_cursor` string, nullable — Cursor of the first element on this page.
    - `end_cursor` string, nullable — Cursor of the last element on this page.
    - `has_next_page?` boolean — Whether a next page exists.
    - `has_previous_page?` boolean — Whether a previous page exists.

## Other responses

- `401` — The `Shinkansen-Treasury-Api-Key` header is missing or does not match a Treasury customer. The body is the plain text `Unauthorized`.
- `403` — The API key is valid but lacks the `payables:all` scope. The body is the plain text `Forbidden`.
- `404` — Not found. The sender `fin_id` is unknown or not owned by the caller, or (on `PATCH`) the payable does not exist. A foreign `fin_id` is deliberately a 404 (no existence leak). On `POST /payables/validate_signature` an invalid signature is also reported as 404, with an `{ "error": "Invalid signature" }` body.
- `422` — Validation error. The `errors` object holds the failing fields. On create, per-item errors are keyed by the item's `external_id`; on update, by field name; on list, by the invalid query parameter.

---

[API](https://skmtc.net/shinkansen/apis/payouts-shinkansen-endpoints.md) · [All operations](https://skmtc.net/shinkansen/apis/payouts-shinkansen-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shinkansen/payouts-shinkansen-endpoints/versions/1e4a6760b7e8/schema)