Skip to content

Payment links vs checkout sessions vs invoices

Flint has three hosted ways to collect a payment. Each one pays an order, so refunds, receipts, disputes, payouts, and reporting work the same whichever you use. What differs is who opens the URL and when the money is due.

UseWhenWhat you get
Payment linkAnyone with the URL can buy the same offer.One URL that never changes. Each buyer who opens it gets their own checkout and order.
Checkout sessionYour app knows what one buyer is paying for, and they pay now.A checkout for one order that expires within 24 hours.
InvoiceA customer owes an amount they'll pay later, in parts, or offline.A numbered bill with a due date, a payment page, reminders, and a PDF.

Choose in two questions#

1. Will more than one buyer open the same URL? Use a payment link. A checkout session pays one order and ends when it's paid, and an invoice bills one customer.

2. Is the money due now? If the buyer is paying now, in your app or a flow you control, use a checkout session. If you're sending a bill that's due on a date, may arrive in parts or by check or wire, and needs a record of what's still owed, use an invoice.

You're buildingUse
A buy button on your website, or a QR code on packaging or a flyerPayment link
A pricing page where each plan starts a subscriptionPayment link, one per plan
A donation page, or an event selling tickets in tiersPayment link
The checkout button in your own app or storefrontCheckout session
An upgrade for a signed-in customerCheckout session
A charge for a quote the buyer just acceptedCheckout session
Net 30 billing for consulting or wholesaleInvoice
A bill that the customer's accounts payable team pays by ACH, check, or wireInvoice
A deposit when work is booked and the balance when it's doneInvoice with a payment schedule

Compare them#

Payment linkCheckout sessionInvoice
What it isA reusable offerOne checkout for one orderA bill a customer owes
Create it fromLine items, a donation, ticket tiers, or a planAn order, a quick pay item, or a planAn order, or quick pay line items
The URLurl, shared by every buyerurl, for this session onlypublic_url, once issued
LastsUntil you deactivate itUp to 24 hoursUntil it's paid, voided, written off, or credited
OrdersA new one per buyerOneOne
SubscriptionsYesYesNo
Due dateNoNoYes, with is_overdue
Paying in partsNoNoYes, including deposits and installments
Offline paymentsNoNoYes
Emails and remindersNoNoYes
Flint feesProcessing feeProcessing feeProcessing fee, plus a 0.40% invoice collection fee on each payment Flint collects
PDFNoNoYes
Stop itDeactivate itClose it while openVoid it while draft or open
Fulfill fromorder.paidorder.paidorder.paid

Fees are at published rates. A payment that starts or renews a subscription carries a 0.40% subscription collection fee instead, on any of the three. An order with automatic tax adds 0.50% on any of them. A payment you record as paid outside Flint carries no fee. See Add-on fees.

Their statuses:

Objectstatus values
Payment linkactive, inactive
Checkout sessionopen, paid, partially_paid, expired, closed, invalidated
Invoicedraft, open, partially_paid, paid, void, uncollectible, credited

Where the payment lands#

Every surface collects through checkout sessions and settles an order:

SurfaceCollects throughSettles
Payment linkA new checkout session for each buyer, with type: "payment_link" and the link's payment_link_idA new order for each buyer, with origin: "payment_link" and the link's metadata
Checkout sessionThe session you create, with type order, quick_pay, or subscription_planThe order you pass, or one Flint creates for quick pay or a plan
InvoiceA checkout session for each online payment, with type: "invoice" and the invoice_id, or a manual payment you recordThe invoice's order

Because the order is the shared record, using more than one surface doesn't split your books:

  • One place to reconcile. GET /v1/orders lists orders from all three. Add origin=payment_link for link sales, use GET /v1/checkout-sessions?payment_link_id=... to see what one link sold, and GET /v1/invoices?order_id=... finds the invoice for an order.
  • Mix them. A payment link on your pricing page, checkout sessions in your app, and invoices for larger accounts can all run at once.
  • Add one later. Orders from the surface you start with sit beside the orders from the one you add, so nothing needs migrating.

Sell workshop seats three ways#

The same $120 workshop seat, sold through each surface. Amounts are integers in the currency's minor unit, so 12000 is $120.00.

One call creates the offer:

cURL
curl -X POST https://api.withflintpay.com/v1/payment-links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: workshop-link-001" \
  -d '{
    "name": "Letterpress Workshop",
    "line_items": [{
      "type": "custom_fixed",
      "key": "seat",
      "name": "Workshop seat",
      "unit_price_money": {"amount": 12000, "currency": "USD"}
    }],
    "buyer_fields": {"require_email": true}
  }'

Abridged response:

Response
{
  "data": {
    "payment_link_id": "pl_01K4WORKSHOP",
    "url": "https://checkout.withflintpay.com/pay/pl_01K4WORKSHOP",
    "status": "active",
    "completed_count": 0
  }
}

Share data.url on your website, in an email, or behind a QR code. Each buyer who opens it gets their own checkout, and each completed checkout creates an order with origin: "payment_link". The link keeps selling until you deactivate it or it reaches max_completions.

Choose it when seats go on sale to the public.

Harder choices#

Payment links and checkout sessions both take subscription_plan_id, and the choice follows the same first question. A public pricing page wants a subscription signup link per plan. An upgrade for a signed-in customer wants a session with type: "subscription_plan", which can name them with customer_id and fill in their details with prefill. A link can't, because anyone can open it.

Invoices don't bill on a schedule. Each one is a single bill, and recurring charges belong to a subscription plan, which charges each renewal without new API calls from you.

Paying later: an invoice, not a session#

A checkout session lasts at most 24 hours, and your checkout settings can shorten it. That's a window for paying now. When payment might arrive next week, in pieces, or as a check, create an invoice: it has a due date, reminders, and an outstanding_money balance that answers "how much is still owed?"

Quick pay on sessions and invoices#

quick_pay_item on a session and quick_pay on an invoice both create the order for you, so whether you already have an order doesn't decide anything. Decide by when the money is due: now is a session, and a bill is an invoice.

A deposit now and the balance later#

An invoice can split its total into a payment schedule. This one asks for 25% when you issue it and the rest on the due date:

JSON
{
  "payment_due": {"type": "date", "due_date": "2026-12-15"},
  "schedule_entries": [
    {
      "kind": "deposit",
      "amount_specification": {"type": "percentage", "percent": 25},
      "due": {"type": "at_issue"}
    },
    {
      "kind": "balance",
      "amount_specification": {"type": "remaining_balance"},
      "due": {"type": "invoice_due_date"}
    }
  ]
}

The entries split the invoice total, tip included. Each installment collects the unpaid tip first, up to its amount, then items and charges, so the tip is usually collected with the deposit.

An invoice that calculates tax automatically can't be split this way; see Tax on an invoice. Stripe deposits and remaining balances compares this schedule with Stripe's payment plans and saved-card charges.

You can also take the deposit through a payment link or checkout session and bill the balance with a separate quick pay invoice. That makes two orders. You can't invoice the deposit's order: an invoice needs an unpaid order, and one with a payment returns 409 ACTION_NOT_ALLOWED with reason payment_collected.

An invoice owns its order#

From the moment you create an invoice, even as a draft, only the invoice can collect its order. A checkout session for that order returns 409 RESOURCE_IN_USE, with the invoice in details[0].blocking_resources. Collect through the invoice instead:

  • The hosted page at public_url, or POST /v1/invoices/{invoice_id}/checkout-sessions to start the invoice's checkout yourself.
  • POST /v1/invoices/{invoice_id}/collect to charge a saved card, for invoices with collection.mode set to automatic.
  • POST /v1/invoices/{invoice_id}/manual-payments to record a check, wire, or cash.

To move an unpaid checkout to an invoice, close the order's open session before you create the invoice. Voiding the invoice releases the order, but only a draft or open invoice can be voided. Marking an invoice uncollectible writes off its balance and closes the order with closed_reason: "written_off".

Fulfill from webhooks#

The buyer's redirect is for the buyer: they can close the tab before it loads, and anyone can open your success URL. Fulfill from webhooks or a read from your backend. One webhook endpoint covers all three surfaces:

  • order.paid
    The order is paid in full, once per order. Fulfill from this event.
    Links, sessions, and invoices
  • invoice_manual_payment.created
    You recorded an offline payment. The event carries the manual payment. Flint also sends invoice.partially_paid or invoice.paid, and order.paid once the order is paid in full.
    Invoices paid offline
  • invoice.paid
    A payment cleared the invoice's balance, online or offline. Its order also sends order.paid.
    Invoices paid any way
  • checkout_session.paid
    A checkout session collected its full amount due, once per session. Carries checkout_session_id and order_id.
    Links, sessions, and online invoice payments
  • subscription.created
    A subscription started from a signup.
    Signup links and plan sessions

Pick one trigger per sale. order.paid covers every surface without fulfilling twice:

cURL
curl -X POST https://api.withflintpay.com/v1/webhook-endpoints \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: webhook-fulfillment-001" \
  -d '{
    "url": "https://example.com/webhooks/flint",
    "enabled_events": ["order.paid"],
    "description": "Fulfillment for links, sessions, and invoices"
  }'

To tell surfaces apart, read the order: origin is payment_link for link sales, GET /v1/checkout-sessions?order_id=... returns the session with its type and its payment_link_id or invoice_id, and GET /v1/invoices?order_id=... finds the invoice. Webhooks covers signature checks and retries.

Errors#

  • HTTP 409
    You created a checkout session for an order that an invoice owns. Collect through the invoice, or void it first.
  • HTTP 409
    You tried to invoice an order that has an open checkout session. Close the session listed in details[0].blocking_resources, then create the invoice.
  • HTTP 409
    You tried to invoice an order that already has a payment. Invoice the balance with quick_pay instead.
  • HTTP 409
    Only draft and open invoices can be voided. Mark a partially_paid invoice uncollectible to write off what's left.
  • HTTP 409
    CONCURRENT_MODIFICATIONRetry the same request
    The invoice changed before void completed. Retry the void with the same idempotency key.
  • HTTP 400
    An order or quick pay line item without a variant_id or bundle_id left out fulfillment, which param names. Send {"requirement": "none"} for anything that doesn't ship.
  • HTTP 400
    NOT_ALLOWED when a checkout session request sent more than one of order_id, quick_pay_item, and subscription_plan_id, with conflicting_fields naming them, or when a payment used an option or saved payment method that this payment doesn't allow. The message names the rule that blocked it.

Common mistakes#

  • Sending one checkout session URL to many buyers. A session pays one order. The first buyer to pay ends it, and everyone after them finds a checkout that's no longer open. A shared URL is a payment link.
  • Creating a payment link per customer to collect a balance. A link doesn't know who owes what. Nothing tracks the balance, sends reminders, or records the check when it arrives. Use an invoice.
  • Using invoices for recurring billing. An invoice bills once. Put recurring revenue on a subscription plan and sign customers up through a link or session.
  • Collecting an invoiced order with a generic checkout session. It returns RESOURCE_IN_USE. Use the invoice's public_url or POST /v1/invoices/{invoice_id}/checkout-sessions.
  • Fulfilling from the redirect. Buyers close tabs, and anyone can open a success URL. Fulfill from webhooks.

Was this helpful?