A headless checkout for the storefront you built on Shopify.

1. checkoutCreateCart API: cartCreatePOST /v1/orders
2. checkoutLineItemsReplaceCart API: cartLinesUpdatePOST /v1/orders/{order_id}/line-items
3. checkoutDiscountCodeApplyV2Cart API: cartDiscountCodesUpdatediscounts[].promotion.promotion_code
4. checkoutShippingAddressUpdateV2Cart API: cartDeliveryAddressesAdddelivery_destination.address
5. checkoutCustomerAssociateV2Cart API: cartBuyerIdentityUpdatecustomer_id
6. checkoutCompleteWithTokenizedPaymentV3No replacementPOST /v1/orders/{order_id}/pay

{
  "data": {
    "cartCreate": {
      "cart": {
        "id": "gid://shopify/Cart/c1-a1b2",
        "totalQuantity": 3,
        "cost": {
          "subtotalAmount": {
            "amount": "164.00",
            "currencyCode": "USD"
          }
        },
        "checkoutUrl": "https://shop.myshopify.com/cart/c/c1-a1b2"
      },
      "userErrors": []
    }
  }
}

{
  "data": {
    "order_id": "ord_1kmn0aExample",
    "payment_collection": {
      "stripe": {
        "account_id": "acct_1kmn0aExample",
        "publishable_key": "pk_test_1kmn0aExample",
        "elements": {
          "next_step": "collect_payment_source",
          "submit_to": "pay_order",
          "mode": "payment",
          "amount_money": { "amount": 17712, "currency": "USD" },
          "payment_method_types": ["card"],
          "digital_wallets": ["apple_pay", "google_pay"],
          "payment_method_creation": "manual"
        }
      }
    }
  }
}

1. 01

   The cart is an open order

   POST /v1/orders

   Send variants and quantities, plus the shipping address. Flint prices each line from your catalog, computes the tax for that address, and holds the balance every payment settles against. Add a line or a discount code later and every figure is recomputed on the same order.

   curlCopy

   curl -X POST https://api.withflintpay.com/v1/orders \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Idempotency-Key: order-cart-7f3a" \
     -d '{
       "line_items": [
         { "variant_id": "var_1kmn0aRunner", "quantity": 1 },
         { "variant_id": "var_1kmn0aSock", "quantity": 2 }
       ],
       "delivery_destination": {
         "address": {
           "line1": "540 Broad Street",
           "city": "Augusta",
           "state": "GA",
           "postal_code": "30901",
           "country": "US"
         }
       },
       "tax": {
         "enabled": true,
         "calculation": { "mode": "automatic", "price_mode": "additive" }
       }
     }'

   what Flint computed
   	Trail Runner 2, quantity 1line_items[0]	$128.00
   +	Merino sock, quantity 2line_items[1]	$36.00
   =	Subtotalpricing_amounts.subtotal_money	$164.00
   +	Tax, Augusta GApricing_amounts.tax_money	$13.12
   =	Totalpricing_amounts.total_money	$177.12
   	Still owedsettlement_amounts.outstanding_money	$177.12

2. 02

   Mount Stripe Elements on your page

   GET /v1/orders/{order_id}

   Read the order and pass its payment collection block to the browser as returned. Apple Pay and Google Pay appear in the same element once your hostname is registered. Everything around the card fields is your markup.

   your checkout pageCopy

   const stripe = Stripe(collection.stripe.publishable_key, {
     stripeAccount: collection.stripe.account_id,
   });
   
   const guidance = collection.stripe.elements;
   const elements = stripe.elements({
     mode: guidance.mode,
     amount: guidance.amount_money.amount,
     currency: guidance.amount_money.currency.toLowerCase(),
     paymentMethodCreation: guidance.payment_method_creation,
     paymentMethodTypes: guidance.payment_method_types,
   });
   elements.create("payment").mount("#payment-element");
   
   // on submit: a single-use credential, posted to your backend
   await elements.submit();
   const { paymentMethod } = await stripe.createPaymentMethod({ elements });
   await fetch("/checkout/pay", {
     method: "POST",
     body: JSON.stringify({ token: paymentMethod.id }),
   });

   Card details go from the buyer's browser to Stripe. They never reach your server or Flint's.

   shop.example.com/checkout

   Total due

   $177.12

   Trail Runner 21 × $128.00$128.00

   Merino sock2 × $18.00$36.00

   Subtotal$164.00

   Tax$13.12

   Total due$177.12

   PayPay

   or pay with card

   #payment-element

   Stripe renders the card fields here

   Pay$177.12

3. 03

   Pay the order from your backend

   POST /v1/orders/{order_id}/pay

   Send the credential the browser created and the balance the buyer approved. Flint confirms the payment and settles the order in the same request. If the order changed after the buyer saw the total, Flint refuses before charging.

   curlCopy

   curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/pay \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Idempotency-Key: pay-cart-7f3a-1" \
     -d '{
       "action": "pay",
       "payment_source": { "token": "pm_1kmn0aExample" },
       "expected_outstanding_money": {
         "amount": 17712,
         "currency": "USD"
       },
       "buyer_contact": { "email": "ada@example.com" }
     }'

   200 OKCopy

   {
     "data": {
       "order": {
         "order_id": "ord_1kmn0aExample",
         "status": "closed",
         "payment_status": "paid",
         "settlement_amounts": {
           "paid_money": { "amount": 17712, "currency": "USD" },
           "outstanding_money": { "amount": 0, "currency": "USD" }
         }
       },
       "payment_attempt": {
         "order_payment_attempt_id": "opat_1kmn0aExample",
         "status": "succeeded",
         "is_resumable": false
       }
     }
   }

   A decline arrives in this same response as one of 18 codes, and the order stays open for another card.

4. 04

   Run 3D Secure on your own page

   POST /v1/orders/{order_id}/pay · action "resume"

   When the issuer asks for authentication, the pay call returns a typed action. Your page hands it to Stripe.js, the buyer authenticates there, and your backend resumes the same attempt with no new credential.

   200 OK, authentication requiredCopy

   {
     "data": {
       "payment_attempt": {
         "order_payment_attempt_id": "opat_1kmn0aExample",
         "status": "requires_action",
         "is_resumable": true,
         "pending_actions": [
           {
             "action_type": "payment_authentication",
             "client_action": {
               "stripe": {
                 "account_id": "acct_1kmn0aExample",
                 "publishable_key": "pk_test_1kmn0aExample",
                 "payment_intent": {
                   "stripe_js_call": "handle_next_action",
                   "client_secret": "pi_1kmn0aExample_secret_1kmn0aExample"
                 }
               }
             }
           }
         ]
       }
     }
   }

   browser, then backendCopy

   // in the browser, on your checkout page
   const action = attempt.pending_actions[0].client_action.stripe;
   await stripe.handleNextAction({
     clientSecret: action.payment_intent.client_secret,
   });
   
   // then your backend resumes the same attempt. No new credential.
   await flint.orders.pay({
     order_id: orderId,
     body: { action: "resume", order_payment_attempt_id: attemptId },
   });

   One attempt, start to finish

   Pay request received, payment created14:00:02

   requires_action, the issuer asked for 3D Secure14:00:04

   Resumed from your backend, processing14:00:19

   succeeded, order.paid emitted14:00:21

5. 05

   Fulfill from the webhook

   order.paid

   Fulfill from the event, never from the browser returning, which a buyer can skip by closing the tab. Retries reuse the same event id, which makes it your deduplication key. The paid order is already in the dashboard your team works from.

   POST /webhooks/flintCopy

   {
     "webhook_event_id": "whev_1kmn0aExample",
     "event_type": "order.paid",
     "payload_version": 1,
     "mode": "live",
     "merchant_id": "mer_1kmn0aExample",
     "created_at": "2026-09-20T14:00:21Z",
     "data": {
       "order_id": "ord_1kmn0aExample",
       "status": "closed",
       "payment_status": "paid",
       "total_money": { "amount": 17712, "currency": "USD" },
       "paid_money": { "amount": 17712, "currency": "USD" },
       "outstanding_money": { "amount": 0, "currency": "USD" }
     }
   }

   app.withflintpay.com

   Order ord_1kmn0aExample

   Trail Runner 2Qty 1$128.00

   Merino sockQty 2$36.00

   PaidUnfulfilled

curl -X POST https://api.withflintpay.com/v1/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: refund-ord-1042-001" \
  -d '{
    "order_id": "ord_1kmn0aExample",
    "line_items": [
      { "order_line_item_id": "li_1kmn0aExample", "quantity": 1 }
    ]
  }'

Manual capture guide → · Refunds guide →