Refunds return funds to a buyer for an order, a succeeded payment intent, or a captured gift card redemption. Target an order_id, a payment_intent_id, explicit tender_allocations, or a standalone gift_card_load_id, and refund the full remaining value or a partial amount. For an order funded by gift cards and processor payments, Flint defaults to the original gift cards first. Explicit allocations are exhaustive and cannot exceed each original tender's remaining refundable value.
tender_allocations reports each original tender's amount, refunded tip, status, and failure. Gift card entries also identify the original card and redemption, the original or replacement destination, and the cards credited. payment_refunds contains only processor payment outcomes, so a gift card-only refund has no payment_intent_id and no payment_refunds entries.
An Idempotency-Key is required with tender_allocations or gift_card_load_id, and for an order_id-only refund of an order funded by gift cards. Flint keeps a refund's key for as long as the refund exists. Replacement codes appear only in the create response's top-level gift_card_codes, outside data, and can be recovered by replaying the original request for 24 hours. Ordinary refund reads and events omit them.
Refunds fit the orders-first model: when you refund against an order, Flint updates the order's refunded amounts and refund_status, while its workflow status and payment_status stay as they were. You can refund specific line items and charges, and Flint works out the tax that goes back. reason is optional. A refund's status starts pending or is already succeeded, and ends succeeded, partially_succeeded, or failed; follow it with the refund.updated webhook.
The Refunds guide covers line-item refunds, the status lifecycle, and failures. For how refunds fit the order lifecycle, see the Orders-first guide.
To refund a standalone gift card purchase funded by a Flint payment, supply its original gift_card_load_id. Omit order, line item, charge, tax, and tender targets. If supplied, payment_intent_id must match the load's original payment. amount_money refunds paid consideration, which can differ from face value. Omit it to refund the load's remaining consideration. An Idempotency-Key is required.
If the same standalone payment also contains cash that never funded a gift card, you can refund that cash through payment_intent_id without a load target. This refund cannot consume consideration assigned to a card or cash reserved by another pending refund.
Flint reserves the corresponding unspent value before the cash refund starts. A pending or unknown processor outcome retains that hold. Confirmed success removes the reserved value; confirmed failure releases it. Refunding spent or otherwise reserved purchase value returns GIFT_CARD_PURCHASE_REFUND_CONFLICT. Read the load's purchase_refunds for each allocation, paid consideration, face value, and outcome. If returned value moved to a replacement card, a new cash refund still targets the original funding load, and Flint reserves the unspent value on whichever cards now hold it. purchase_refunds[].value_allocations lists the loads the value came from, and a replacement card's load reports pending cash refund holds in purchase_refund_value_holds. For cards sold on a Flint order, refund their original order line items.
If a succeeded purchase refund later fails, Flint restores the removed value to the original card when all reversed value belonged to that load. If value was reversed from descendant loads, or the original card is closed or cannot accept the value within its balance cap, Flint creates replacement cards that retain the original funding history and restrictions. The load's purchase_refunds[].recovery identifies the destinations. Replaying the original refund creation request recovers replacement codes for 24 hours after recovery. Ordinary reads and events contain destination identities only.
For gift cards sold on a Flint order line item, if the refunded cash had not issued a whole gift card, a late failure returns cash instead of creating another card. Read unissued_gift_card_recoveries on the refund. To return that cash, create a new refund with its payment_intent_id, order_id, and a line_items entry containing its order_line_item_id and the amount to return. Use a new Idempotency-Key. Flint returns recovered cash before removing value from cards funded by that payment. source_remaining_amount_money includes cash reserved by pending refunds; subtract source_pending_amount_money to find the amount currently available. These source amounts describe the entire settlement_allocation_id, so entries sharing that identity are not additive.