WIwithflex
Checkout Sessions

Confirm Checkout Session

Changed on

Charges the HSA/FSA-eligible portion of a Checkout Session against a single saved payment method, using the eligibility split computed and persisted when the session was created. The amount charged is the sum of the eligible portions of the session's items — never the session total — so amount_received is expected to be less than amount_total. Collect the remaining ineligible balance through your own payment flow.

Returns the Checkout Session with its payment_intent expanded. When the eligible portion sums to $0, or to less than Stripe's $0.50 minimum, nothing is charged and the response is still a 200 with payment_intent: null — a normal outcome for a partly-eligible order, not an error. Branch on payment_intent == null to decide whether there is anything to settle with Flex.

capture_method must be automatic. manual is rejected with manual_capture_not_supported (422): it would authorize the card successfully and then be uncapturable, so it is refused before any money moves rather than leaving a hold to expire.

An Idempotency-Key header is required. Retry a timeout or a 5xx with the same key; a new key is a new request and can charge the card a second time. A 4xx and a card decline are both terminal.

Error codes: idempotency_key_required (400), checkout_session_already_processed / checkout_session_expired / checkout_session_canceled (400), checkout_session_not_found / payment_method_not_found / customer_not_found / eligibility_record_not_found / food_eligibility_not_enabled (404), eligibility_record_already_charged / idempotency_key_reused (409), manual_capture_not_supported / payment_method_not_off_session (422), idempotency_key_in_use / lock_timeout (503 — transient contention: a request with this key is still in flight, or another request holds the customer or payment method. Retry unchanged with the same key; a new key may charge the card twice), and a 402 carrying code and decline_code for a card decline — including authentication_required, which is terminal: a card demanding 3DS cannot be charged off-session, so fall back to another tender rather than retrying.

post/v1/checkout/sessions/{id}/confirm

Request

  • Base URL
    https://api.withflex.com
  • URL
    https://api.withflex.com/v1/checkout/sessions/{id}/confirm
  • Auth
    HTTP bearer

Path parameters

idstring required
Example:fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA

Query parameters

expandstring

Comma-separated list of related objects to expand in the response.

Headers

Idempotency-Keystring required

A unique key identifying this attempt. Retry a timed-out or 5xx request with the SAME key — a new key is a new request and can charge the card a second time.

Request body

Example request

{
  "checkout_session": {
    "payment_method": "fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "capture_method": "automatic"
  }
}

Response

An envelope wrapping a single checkout session object.

Example response

{
  "checkout_session": {
    "allow_promotion_codes": false,
    "amount_total": 2500,
    "amount_subtotal": 2500,
    "amount_received": 2500,
    "amount_refunded": 2500,
    "amount_disputed": 2500,
    "cancel_url": "https://example.com",
    "captures": [
      "fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
    ],
    "disputes": [
      "fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
    ],
    "capture_method": "automatic",
    "checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "client_reference_id": "example_value",
    "created_at": 2500,
    "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "defaults": {
      "customer_id": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+14155550142"
    },
    "expires_at": 2500,
    "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "hsa_fsa_eligible": false,
    "letter_of_medical_necessity_required": false,
    "metadata": {
      "order_id": "8842",
      "channel": "shopify"
    },
    "mode": "payment",
    "origin": "shopify",
    "payment_intent": "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "payment_intents": [
      "fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
    ],
    "redirect_url": "https://example.com",
    "refunds": [
      "fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA"
    ],
    "setup_intent": "fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "shipping_options": {
      "shipping_rate_id": "fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "shipping_amount": 2500,
      "display_name": "Example"
    },
    "shipping_address_collection": false,
    "shipping_details": {
      "shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
      "line1": "123 Main St",
      "line2": "Suite 100",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94107",
      "country": "US"
    },
    "split_cart": "fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "status": "open",
    "success_url": "https://example.com",
    "fees": [
      {
        "fee_id": "ffee_1234567890",
        "amount": 2500,
        "name": "Example",
        "description": "Premium SPF 50 mineral sunscreen",
        "fee_type": "lmn_consultation",
        "applied": true,
        "waived_reason": "existing_letter"
      }
    ],
    "custom_text": {
      "after_submit": {
        "message": "Premium SPF 50 mineral sunscreen"
      },
      "shipping_address": {
        "message": "Premium SPF 50 mineral sunscreen"
      },
      "submit": {
        "message": "Premium SPF 50 mineral sunscreen"
      },
      "terms_of_service_acceptance": {
        "message": "Premium SPF 50 mineral sunscreen"
      },
      "terms_of_service_checkbox_required": true,
      "payment": {
        "message": "Premium SPF 50 mineral sunscreen"
      }
    },
    "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "subscription_data": {
      "cancel_at": "2026-06-15T14:30:00Z",
      "trial_end": "string",
      "cancel_at_period_end": false,
      "trial_period_days": 0,
      "trial_settings": {
        "end_behavior": {
          "missing_payment_method": "cancel"
        }
      }
    },
    "tax_rate": {
      "amount": 2500
    },
    "tax_calculation_mode": "exclusive",
    "test_mode": false,
    "total_details": {
      "amount_discount": 2500,
      "amount_tax": 2500,
      "amount_shipping": 2500,
      "amount_iias": 2500,
      "amount_vision": 2500,
      "amount_prescription": 2500,
      "amount_service": 2500,
      "amount_fee": 2500,
      "breakdown": {
        "discounts": [
          {
            "discount": {
              "discount_id": "fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
              "checkout_session": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
              "customer": "fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
              "subscription": "fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
              "invoice": "fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
              "source": {
                "coupon": "fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
                "type": "coupon"
              },
              "promo_code": "fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
              "test_mode": false,
              "end": "string",
              "start": "string"
            }
          }
        ]
      }
    },
    "visit_type": "cbtSleep",
    "setup_future_use": "on_session",
    "payment_method_options": {
      "card": {
        "request_three_d_secure": "automatic"
      }
    },
    "next_action": {
      "type": "collect_letter_of_medical_necessity",
      "collect_letter_of_medical_necessity": {
        "url": "https://example.com"
      },
      "payment_failed": {
        "message": "Premium SPF 50 mineral sunscreen",
        "url": "https://example.com",
        "decline_code": "string",
        "error_code": "string"
      },
      "provide_second_payment_method": {
        "message": "Premium SPF 50 mineral sunscreen",
        "url": "https://example.com",
        "eligible_amount": 0,
        "ineligible_amount": 0
      },
      "provide_alternative_payment_method": {
        "message": "Premium SPF 50 mineral sunscreen",
        "url": "https://example.com"
      }
    },
    "selling_plans": [
      {
        "id": "string",
        "name": "string",
        "billing_interval": {
          "interval": "day",
          "interval_count": 0
        }
      }
    ],
    "shopify_payment_details": {
      "gateway": "string",
      "wallet": "string",
      "card": {
        "brand": "american_express",
        "last4": "4242"
      }
    },
    "renewal_as_of": 1781533800,
    "partner": "facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
    "platform_fees": {
      "letter_fee": {
        "amount": 2500,
        "type": "string",
        "status": "pending"
      }
    }
  }
}

Changes