FlintflintDocs

Payments

Payment intents represent a customer's intent to pay and track the payment lifecycle from creation through confirmation to completion. Create them in one of two modes: order-linked, where Flint derives the amount and commerce context from an order_id, or standalone, where you provide amount_money directly. For most checkout flows, order-linked payment intents are the right default: Flint keeps the amount in sync with the order's balance, including tip and tax changes after the intent is created.

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 API; order-linked intents are completed through the order payment flow or confirmed on the frontend in embedded checkout. An order can carry multiple payment intents (split payments); the order's pay flow confirms the attached intents against the outstanding balance.

If you are building browser checkout, start with the Embedded payments guide. For how payments relate to orders, see the Orders-first guide.

Endpoints

List payment intents#

GET/v1/payment-intents

Returns a paginated list of payment intents for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

order_idstring

Filter by order ID.

customer_idstring

Filter by customer ID.

invoice_idstring

Filter by invoice ID.

statusenum

Filter by payment intent status.

requires_payment_methodrequires_confirmationrequires_actionprocessingrequires_capturecanceledsucceededexpired
sourceenum

Filter by payment source.

virtual_terminalpayment_linkcheckoutapiin_personsubscription
external_reference_idstring

Exact-match filter on the merchant reference ID.

querystring

Search across payment_intent_id, external_reference_id, and receipt_email.

min_amountinteger

Inclusive lower bound in minor units. Requires currency.

max_amountinteger

Inclusive upper bound in minor units. Requires currency.

currencystring

ISO 4217 currency for min_amount and max_amount.

stateenum

Filter by aggregate payment-intent state preset.

with_refundsfully_refundeddisputedneeds_action
sort_byenum

Sort field.

created_atupdated_atamount
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/payment-intents \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "payment_intent_id": "pi_123",
      "amount_money": {
        "amount": 5000,
        "currency": "USD"
      },
      "status": "requires_confirmation",
      "capture_method": "automatic",
      "metadata": {
        "channel": "web"
      },
      "merchant_id": "mer_123",
      "settlement_status": "none",
      "refund_status": "none",
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "external_reference_id": "cart_123",
      "customer_id": "cus_123",
      "receipt_email": "buyer@example.com",
      "source": "api"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create payment intent#

POST/v1/payment-intentsIdempotent

Creates a payment intent for the authenticated merchant. Direct confirmation is allowed for standalone payment intents; order-linked payment intents should be paid through the orders flow.

Request body
option 1object
option 2object
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/payment-intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "amount_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "external_reference_id": "cart_123",
    "customer_id": "cus_123",
    "metadata": {
      "channel": "web"
    },
    "capture_method": "automatic",
    "payment_method_types": [
      "card"
    ],
    "digital_wallets": [
      "apple_pay"
    ],
    "receipt_email": "buyer@example.com"
  }'

Get payment intent#

GET/v1/payment-intents/{payment_intent_id}

Returns a single payment intent by ID.

Path parameters
payment_intent_idstringrequired

Flint payment intent ID.

Query parameters
expandarray of enum

Supported expansions: customer, invoice, order. Expansion requires payments.payment_intents.read plus the read scope for each expanded resource. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=customer&expand=invoice. Comma-separated values, expand[]=customer, and numeric expand[0]=customer are accepted for common client compatibility.

customerinvoiceorder
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/payment-intents/pi_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update payment intent#

PATCH/v1/payment-intents/{payment_intent_id}Idempotent

Applies a sparse update to a payment intent before it reaches a terminal state.

Path parameters
payment_intent_idstringrequired

Flint payment intent ID.

Request body
amount_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

customer_idstring
external_reference_idstring
metadatamap of string
payment_method_idstring
payment_source_tokenstring
receipt_emailstring
tip_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/payment-intents/pi_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {
      "channel": "in_person"
    },
    "receipt_email": "updated@example.com"
  }'
JSON
{
  "data": {
    "payment_intent_id": "pi_123",
    "amount_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "status": "requires_confirmation",
    "capture_method": "automatic",
    "metadata": {
      "channel": "web"
    },
    "merchant_id": "mer_123",
    "settlement_status": "none",
    "refund_status": "none",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "external_reference_id": "cart_123",
    "customer_id": "cus_123",
    "receipt_email": "buyer@example.com",
    "source": "api"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Cancel payment intent#

POST/v1/payment-intents/{payment_intent_id}/cancelIdempotent

Cancels a payment intent before it reaches a terminal settled state.

Path parameters
payment_intent_idstringrequired

Flint payment intent ID.

Request body
cancellation_reasonenum

Optional merchant-supplied cancellation reason. Use metadata for unrelated caller-owned context.

requested_by_customerduplicatefraudulentabandoned
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/payment-intents/pi_123/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "cancellation_reason": "requested_by_customer"
  }'
JSON
{
  "data": {
    "payment_intent_id": "pi_123",
    "amount_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "status": "requires_confirmation",
    "capture_method": "automatic",
    "metadata": {
      "channel": "web"
    },
    "merchant_id": "mer_123",
    "settlement_status": "none",
    "refund_status": "none",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "external_reference_id": "cart_123",
    "customer_id": "cus_123",
    "receipt_email": "buyer@example.com",
    "source": "api"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Capture payment intent#

POST/v1/payment-intents/{payment_intent_id}/captureIdempotent

Captures an authorized payment intent, including partial captures when supported.

Path parameters
payment_intent_idstringrequired

Flint payment intent ID.

Request body
amount_moneyobject

Monetary amount represented as integer minor units plus an ISO 4217 currency code.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/payment-intents/pi_123/capture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "amount_money": {
      "amount": 3000,
      "currency": "USD"
    }
  }'
JSON
{
  "data": {
    "payment_intent_id": "pi_123",
    "amount_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "status": "requires_confirmation",
    "capture_method": "automatic",
    "metadata": {
      "channel": "web"
    },
    "merchant_id": "mer_123",
    "settlement_status": "none",
    "refund_status": "none",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "external_reference_id": "cart_123",
    "customer_id": "cus_123",
    "receipt_email": "buyer@example.com",
    "source": "api"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Confirm payment intent#

POST/v1/payment-intents/{payment_intent_id}/confirmIdempotent

Confirms a standalone payment intent. Order-linked payment intents must be confirmed through the orders payment flow.

Path parameters
payment_intent_idstringrequired

Flint payment intent ID.

Request body
payment_method_idstring
payment_source_tokenstring
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/payment-intents/pi_123/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "payment_source_token": "pm_tok_123"
  }'
JSON
{
  "data": {
    "payment_intent_id": "pi_123",
    "amount_money": {
      "amount": 5000,
      "currency": "USD"
    },
    "status": "requires_confirmation",
    "capture_method": "automatic",
    "metadata": {
      "channel": "web"
    },
    "merchant_id": "mer_123",
    "settlement_status": "none",
    "refund_status": "none",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "external_reference_id": "cart_123",
    "customer_id": "cus_123",
    "receipt_email": "buyer@example.com",
    "source": "api"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc