--- title: "Get a payment link" method: GET path: "/v1/payment-links/{paymentLinkId}" tags: ["Payment links"] --- # Get a payment link `GET /v1/payment-links/{paymentLinkId}` ## Request - Base URL: `https://api.getfinero.com/functions/v1/api` - URL: `https://api.getfinero.com/functions/v1/api/v1/payment-links/{paymentLinkId}` - Auth: HTTP bearer Returns one payment link, including its hosted checkout URL and settlement state. Available to **admin and readonly** API keys (no side effects). ## Path parameters - `paymentLinkId` string, uuid, required ## Response `200` Success - object - `id` string, uuid, required: Payment link id. - `invoice_id` string, uuid, required: Invoice the link collects. - `installment_id` string, uuid, nullable, required: Installment the link collects. An installment may carry SEVERAL live links (0280) — their amounts together may not exceed the installment's `collection_outstanding`, which the database enforces under a row lock. What Finero already collected is ALREADY netted off that figure; subtracting it a second time under-states the room. - `status` 'active' | 'processing' | 'paid' | 'inactive' | 'needs_replacement' | 'action_required', required: Lifecycle status. active = payable now; processing = a payment is being confirmed; paid = settled; inactive = deactivated or superseded; needs_replacement = the provider-side link stopped being usable (expired or removed at the provider), so a new link must be created; action_required = frozen pending a human decision — Finero will not act on it automatically. A payment whose provider report does not match the request is frozen in processing, not here. - `provider` 'stripe' | 'wix', required: Payment provider hosting the checkout. - `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. - `amount_minor` integer, required: Amount the link collects. 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: Link currency. ISO 4217 alphabetic code, e.g. "USD". - `payment_due_date` string, date, nullable, required: Business due date owned by this payment link (YYYY-MM-DD). It is snapshotted at creation and does not change when the source installment changes. Null only for legacy links whose source had no date. - `url` string, nullable, required: Hosted customer-facing pay-page URL; null once the link is withdrawn (`inactive`). Treat as a capability: anyone with the URL can open the checkout. - `paid_at` string, date-time, nullable, required: When the link was paid (ISO 8601 UTC). - `paid_amount_minor` integer, nullable, 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. - `paid_currency` string, nullable, required: Settled currency. ISO 4217 alphabetic code, e.g. "USD". - `deactivated_at` string, date-time, nullable, required: When the link was deactivated (ISO 8601 UTC). - `created_at` string, date-time, required: Creation time (ISO 8601 UTC). - `updated_at` string, date-time, required: Last update time (ISO 8601 UTC). - `incident` object, nullable, required: A payment the provider reported on this link that Finero refused to record — null almost always. While it is open the link stays as it is (a frozen link reads `processing`), so the same money cannot be asked for twice. Read-only here: a workspace admin checks it at the provider and resolves it in the app's Payments view, which closes the link so a new one can be created. - `reason` 'amount_mismatch' | 'currency_mismatch' | 'mode_mismatch' | 'attempt_request_mismatch' | 'attempt_tenant_mismatch' | 'attempt_not_found' | 'duplicate_settlement', required: Why Finero refused to record the payment. duplicate_settlement = the link was already paid and a second payment arrived; the others = what the provider reported does not match what this link asked for. - `provider` 'stripe' | 'wix', required: Provider that reported the payment. - `reported_amount_minor` integer, required: Amount the provider reported. 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. - `reported_currency` string, required: Currency the provider reported. ISO 4217 alphabetic code, e.g. "USD". - `recorded_at` string, date-time, required: When Finero recorded the incident (ISO 8601 UTC). ## Other responses - `400`: `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. --- [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/3d456e222775?raw)