FlintflintDocs

Overview

Flint is a commerce-first payments API. You can take one-time payments, run hosted or embedded checkout, send invoices, and bill subscriptions, all through one HTTP API. If you want to move fast, Accept Your First Payment gets you to a live test payment in four calls. This page is the concept map: the one idea that shapes the whole API, and the conventions that hold everywhere.

That idea is: the order is the center, and everything else attaches to it.

If you are coming from Stripe or Square, this is the main shift. Those APIs start from the charge or payment as the primary object; Flint starts from the order, the record of what is being bought, and payments attach to it. See Migrating from Stripe or Migrating from Square for a field-by-field map.

Orders are the center#

An order is the durable record of a sale: its line items, discounts, tax, tips, what is still owed, and what happened after payment. Most other resources do not replace the order, they read from it and write back to it.

  • Payments collect money against an order. Point a payment intent at an order_id and Flint keeps the amount in sync with the order's balance, including tip and tax changes.
  • Checkout sessions give you a Flint-hosted payment page for an order.
  • Payment links are a reusable URL that creates an order when a buyer pays.
  • Invoices are an order billed to a customer, with a due date and reminders you can send.
  • Refunds return money against an order, and Flint recalculates its balance and status automatically.
  • Subscriptions generate an order for each billing cycle.

Because the order holds the pricing and settlement state, order status stays the source of truth for what has been paid, refunded, and is still outstanding. You rarely have to reconcile totals across several objects yourself.

For the reasoning behind this design, read Why Flint Is Orders-First.

Conventions worth knowing up front#

A few things are consistent across every endpoint:

  • Base URL. Every request goes to https://api.withflintpay.com with your key in the Authorization: Bearer header.
  • Money is integer minor units. {"amount": 2500, "currency": "USD"} is $25.00, not $2500.
  • Test vs live is decided by your key. A flint_test_... key runs in test mode against an isolated sandbox; a flint_live_... key charges real money. Same hostname for both.
  • IDs are prefixed. ord_, pi_, cs_, and so on tell you what an ID refers to at a glance.
  • Responses wrap data. Successful responses return your object (or array) under a data field, alongside a request_id and a meta object. List responses also include a next_page_token for pagination.

Where to go next#

Rate this doc