Payment links

Create a payment link

Creates a hosted payment link for one collectible invoice or installment through the tenant's connected payment provider — the same validation and creation path the Finero app uses. An invoice target or installment may carry SEVERAL links at once, each collecting part of it: an installment of 100.00 can be offered as four links of 25.00. Their amounts may not exceed what is still outstanding. When live links already cover the installment the request is refused as a conflict, exactly as a duplicate link always was; when there is room but less than was asked for, it is refused as an invalid amount and names what was available. If the tenant's email-notification workflow is enabled, the customer payment-link email is sent as a consequence.

Requires an admin API key (has side effects).

post/v1/payment-links

Request

Base URL: https://api.getfinero.com/functions/v1/api
URL: https://api.getfinero.com/functions/v1/api/v1/payment-links
Auth: HTTP bearer

Headers

Idempotency-Keystring required

Unique key (1–255 printable ASCII chars) scoping safe retries. Same key + same body replays the original result; same key + different body returns 409 idempotency_conflict.

Request body

invoice_idstring uuid required

Invoice to collect.

installment_idstring uuid nullable required

Real installment id in installment mode; null in invoice-only mode. Read the invoice collection_mode first.

integration_idstring uuid

Optional: a specific connected payments integration. Defaults to the tenant's connected provider.

amount_minorinteger

Optional: how much this link collects, in integer minor units (100 = USD 1.00; 100 = JPY 100). Fractional minor units are rejected, never rounded. Omit to collect everything still available on the current collection target, which is the usual case. Supply it to split an installment across several links — the amounts of all live links may not exceed the installment's collection_outstanding. That figure already has what Finero collected netted off it, so do not subtract amount_collected as well. For a three-decimal currency (BHD, JOD, KWD, OMR, TND) the amount must be a multiple of 10: the payment provider drops the last digit, so 1005 fils would be refused as validation_failed rather than minted as a link the checkout cannot honour.

payment_due_datestring date

Optional link-owned due date (YYYY-MM-DD). Omit it to snapshot the invoice or installment target's current due date when the link is committed. Past dates are accepted for already-overdue receivables.

email_delivery_mode'workflow' | 'send_now' | 'schedule' | 'suppress'

Optional link-specific email decision. Omit or use workflow to preserve tenant workflow behaviour. Explicit modes override it for this link.

email_scheduled_localstring

Tenant-local YYYY-MM-DDTHH:mm wall clock. Required only when email_delivery_mode is schedule; the backend resolves it through the tenant timezone.

Response

Success

idstring uuid required

Payment link id.

invoice_idstring uuid required

Invoice the link collects.

installment_idstring 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.

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_minorinteger 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.

currencystring required

Link currency. ISO 4217 alphabetic code, e.g. "USD".

payment_due_datestring 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.

urlstring 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_atstring date-time nullable required

When the link was paid (ISO 8601 UTC).

paid_amount_minorinteger 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_currencystring nullable required

Settled currency. ISO 4217 alphabetic code, e.g. "USD".

deactivated_atstring date-time nullable required

When the link was deactivated (ISO 8601 UTC).

created_atstring date-time required

Creation time (ISO 8601 UTC).

updated_atstring date-time required

Last update time (ISO 8601 UTC).

Changes

No recorded changes to this operation across all 1 revision of this API.