Payment intents represent a customer's intent to pay and track the payment lifecycle from creation through confirmation to completion. Create standalone payment intents through /v1/payment-intents with an explicit amount_money. Order-owned payment legs use /v1/orders/{order_id}/payment-intents, where Flint validates the leg against the order's live outstanding balance. Most checkout flows do not create a leg before buyer submit. Instead, render collection fields from the order or checkout session's payment_collection guidance, create a payment method in the browser, and submit it to /v1/orders/{order_id}/pay with action: "pay" and payment_source. Flint creates and pays the full-balance leg in that one request.
A payment intent moves through statuses like requires_payment_method, requires_confirmation, requires_action, processing, and requires_capture before reaching a terminal state of succeeded, canceled, or expired. Standalone intents are confirmed through the payment-intent API. Order-owned legs are created, confirmed, captured, and canceled only through order routes. Their amounts are immutable: if tax, tip, discounts, or line items change after an explicit leg is staged, cancel and recreate that leg. An order can carry multiple payment intents for split payment, and /v1/orders/{order_id}/pay validates the selected legs against the current outstanding balance before starting an attempt.
Each /v1/orders/{order_id}/pay call runs inside a payment attempt, the resource you inspect and resume when a payment does not complete in one call. The attempt carries a per-leg summary (including last_payment_error for a failed leg) and an is_resumable flag: true means finish the pending action and resume with action: "resume" and payment_attempt_id; false means the attempt is terminal and you start new work. The in-flight attempt is exposed as active_payment_attempt on order and checkout-session detail so a lost response can be recovered without double-charging, and past attempts are readable through GET /v1/orders/{order_id}/payment-attempts. See Handling declines & payment attempts.
A succeeded payment carries processing_fee_money, Flint's all-in fee to process it. It is the complete processing price rather than a provider cost passed through, so your net is captured_money minus that fee. The fee is final at card capture or ACH success, and payments that are canceled or fail before success have none. Refunds do not return or revise it. See Processing fees.
If you are building browser checkout, start with the Embedded payments guide. For how payments relate to orders, see the Orders-first guide.
POST /v1/orders/{order_id}/pay requires an action. Each action accepts only its own fields:
| Action | Required fields | Optional fields |
|---|---|---|
pay | None beyond action | payment_source |
confirm_payment_intents | Non-empty payment_intents | completion_behavior: complete_order or partial_payment |
setup | setup_payment_source containing a newly collected token | None |
resume | payment_attempt_id | None |
All four actions also accept expected_outstanding_money, buyer_email, and buyer_phone. pay collects the full outstanding balance; omit payment_source only when that balance is zero. setup saves a credential on a zero-balance order. To continue an open attempt after a pending client action, send action: "resume", or replay the exact original request with the same Idempotency-Key.
{
"action": "pay",
"payment_source": {"confirmation_token": "ctoken_1kmn0aExample"},
"expected_outstanding_money": {"amount": 2500, "currency": "USD"}
}