--- title: "List confirmed payments" method: GET path: "/v1/payments" tags: ["Payments"] --- # List confirmed payments `GET /v1/payments` ## Request - Base URL: `https://api.getfinero.com/functions/v1/api` - URL: `https://api.getfinero.com/functions/v1/api/v1/payments` - Auth: HTTP bearer Lists confirmed payments, newest first by creation time. A payment appears here only after the payment provider verifies settlement; payments cannot be created through the API. Each payment also reports whether it has reached the ERP as a receipt (`erp_push_status` and the other `erp_*` fields), so money Finero holds but the ERP has not recorded is visible without a second call. There is no `erp_push_status` query filter — read the field on each returned payment. Cursor-paginated: pass `limit` (1–100) and send pagination.next_cursor back as `cursor` until has_more is false. To learn HOW MANY rows match without walking every page, pass `include_total=true` once and read pagination.total_count. Available to **admin and readonly** API keys (no side effects). ## Query parameters - `limit` integer - `cursor` string - `order` 'asc' | 'desc' - `include_total` boolean - `invoice_id` string, uuid - `customer_id` string, uuid - `payment_link_id` string, uuid - `provider` 'stripe' | 'wix' - `confirmed_since` string, date-time - `confirmed_before` string, date-time ## Response `200` Success - object - `data` object[], required: Confirmed payments, newest first by creation time. - `id` string, uuid, required: Payment id. - `invoice_id` string, uuid, required: Invoice the payment settles. - `installment_id` string, uuid, nullable, required: Installment the payment settles, or null for an invoice-level payment. - `payment_link_id` string, uuid, required: The payment link the payer used. - `provider` 'stripe' | 'wix', required: Payment provider. - `provider_payment_id` string, required: The provider's payment/transaction identifier. - `amount_minor` integer, required: Settled amount. Integer amount in the currency's MINOR unit (e.g. cents), as defined by the PAYMENT PROVIDER's own table, which is not always ISO 4217 — the two disagree on ISK and MGA among others, so converting with an ISO exponent misprices those. Invoice and installment amounts are exact decimal strings and are the safe basis for arithmetic and display. - `currency` string, required: Settled currency. ISO 4217 alphabetic code, e.g. "USD". - `mode` 'test' | 'live', required: Provider environment. `test` means a TEST processor handled this money: it is not revenue and must never be reported as cash collected, however real the amount looks. `live` is real money. - `status` 'confirmed', required: Payments appear here only once verified/confirmed by the provider. - `provider_paid_at` string, date-time, nullable, required: Provider-reported payment time (ISO 8601 UTC). - `confirmed_at` string, date-time, required: When Finero confirmed the settlement (ISO 8601 UTC). - `erp_push_status` 'held' | 'pending' | 'processing' | 'posted' | 'failed', nullable, required: Whether this payment has reached the ERP as a receipt. `held` = the connection's payment_push_mode is manual and no admin has released this receipt yet — nothing is wrong, and POST /v1/payments/erp-push releases it. `posted` = the ERP accepted it, and Finero's part ends there: what the ERP does with the receipt afterwards (allocating it, or reversing it) is the ERP's business. `failed` means it did not reach the ERP — retried automatically only while the cause is the ERP being unreachable. `null` when there is no push at all: a payment on a Finero-created invoice (there is no ERP to report to), a tenant not syncing payments to an ERP, or a payment that settled before ERP payment sync was switched on — enabling it never posts history backwards. NOT TO BE CONFUSED WITH an invoice's `erp_push_state`: that one rolls up every push on the invoice and reports the worst, while this is THIS payment's own. - `erp_receipt_number` string, nullable, required: The receipt identifier Finero sends to the ERP (`FIN-…`), derived deterministically from the payment id. This is the value that identifies the receipt inside the ERP. - `erp_external_receipt_id` string, nullable, required: The ERP's own identifier for the receipt, once it has created one. - `erp_pushed_at` string, date-time, nullable, required: When the ERP first accepted the receipt (ISO 8601 UTC). - `erp_push_error_category` string, nullable, required: Coarse reason the push has not gone through, when it has not. Cleared by the database the moment a push succeeds, so it is never a stale error beside a `posted` status. Provider error text is deliberately not exposed. - `pagination` object, required - `next_cursor` string, nullable, required: Opaque cursor for the next page — pass as ?cursor=. Null when there are no further results. - `has_more` boolean, required: Whether another page exists. - `limit` integer, required: The page size that was applied. - `total_count` integer: Total rows matching the filters, ignoring paging. Present ONLY when the request passed ?include_total=true. ## Other responses - `400`: `invalid_cursor` — The cursor is malformed, was issued for a different query, or (aging) the report changed. Restart without cursor, keeping the filters identical. `validation_failed` — The request failed schema validation. See error.details for field messages. - `401`: `invalid_credentials` — The credential is malformed or does not match an active key. The response never reveals whether a key identifier exists. `missing_credentials` — No Authorization: Bearer header was sent. `revoked_credentials` — The presented key was revoked. Create a new key in Settings → API. - `403`: `feature_unavailable` — The tenant's tier does not currently include API access. Feature rollout flags cannot grant this entitlement. `permission_denied` — The key's permission does not allow this operation (readonly keys cannot call admin-only operations). - `404`: `not_found` — No such resource in YOUR tenant. Ids belonging to another tenant are indistinguishable from missing ones. - `429`: `rate_limit_exceeded` — Too many requests. Honor the Retry-After header (seconds) before retrying — waiting that long is enough. The RateLimit-* fields on every response say how much headroom is left before this happens; pace against them instead of retrying into a refusal. - `500`: `internal_error` — Unexpected server error. Safe to retry with the same Idempotency-Key. ## Changes - **2026-10-20** `d17186951474`: 12 warning - added the new `link_already_covered` enum value to the `error/code` response property for the response status `400` - added the new `link_already_covered` enum value to the `error/code` response property for the response status `401` - added the new `link_already_covered` enum value to the `error/code` response property for the response status `403` - added the new `link_already_covered` enum value to the `error/code` response property for the response status `404` - …8 more [Operation history](https://skmtc.dev/getfinero/apis/finero-public-api/changes/v1/payments/get.md) --- [API](https://skmtc.dev/getfinero/apis/finero-public-api.md) · [All operations](https://skmtc.dev/getfinero/apis/finero-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getfinero/apis/finero-public-api/revisions/d17186951474?raw)