Headless WooCommerce checkout on your own domain.

1. 01

   Create the order from the cart

   POST /v1/orders

   Send the names, quantities, and prices from the Store API cart, plus the shipping address. Flint computes the subtotal, the tax for that address, and the total, and holds the balance every payment settles against. Your cart key rides along, so you can look the order up by an id WooCommerce already gave you.

   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-a1b2c3" \
     -d '{
       "external_reference_id": "wc-cart-a1b2c3",
       "line_items": [
         {
           "name": "Merino crew",
           "quantity": 1,
           "unit_price_money": { "amount": 11800, "currency": "USD" },
           "tax": { "taxable": true }
         },
         {
           "name": "Wool socks",
           "quantity": 2,
           "unit_price_money": { "amount": 1800, "currency": "USD" },
           "tax": { "taxable": true }
         }
       ],
       "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
   	Merino crew, quantity 1line_items[0]	$118.00
   +	Wool socks, quantity 2line_items[1]	$36.00
   =	Subtotalpricing_amounts.subtotal_money	$154.00
   +	Tax, Augusta GApricing_amounts.tax_money	$12.32
   =	Totalpricing_amounts.total_money	$166.32
   	Still owedsettlement_amounts.outstanding_money	$166.32

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. It names the Stripe account, the publishable key, the amount, and the wallets to offer, and it holds no secrets. Apple Pay and Google Pay appear in the same element once your hostname is registered.

   200 OKCopy

   {
     "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": 16632, "currency": "USD" },
             "payment_method_types": ["card"],
             "digital_wallets": ["apple_pay", "google_pay"],
             "payment_method_creation": "manual"
           }
         }
       }
     }
   }

   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.

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-a1b2c3-1" \
     -d '{
       "action": "pay",
       "payment_source": { "token": "pm_1kmn0aExample" },
       "expected_outstanding_money": {
         "amount": 16632,
         "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": 16632, "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 instead of a URL. 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

   Write the paid order into WooCommerce

   order.paid

   Fulfill from the webhook, never from the browser redirect, which a buyer can skip by closing the tab. Your handler creates the WooCommerce order through its REST API already marked paid, so your team keeps working in the admin they know. Retries reuse the same event id, which makes it your deduplication key.

   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-19T14:00:00Z",
     "data": {
       "order_id": "ord_1kmn0aExample",
       "status": "closed",
       "payment_status": "paid",
       "total_money": { "amount": 16632, "currency": "USD" },
       "paid_money": { "amount": 16632, "currency": "USD" },
       "outstanding_money": { "amount": 0, "currency": "USD" }
     }
   }

   Into WooCommerceCopy

   POST /wp-json/wc/v3/orders
   Authorization: Basic <consumer key : consumer secret>
   
   {
     "payment_method": "flint",
     "payment_method_title": "Card via Flint",
     "set_paid": true,
     "transaction_id": "ord_1kmn0aExample",
     "billing":  { "first_name": "Ada", "email": "ada@example.com" },
     "line_items": [
       { "product_id": 482, "quantity": 1 },
       { "product_id": 517, "quantity": 2 }
     ]
   }

   The Flint order id goes in transaction_id, so support gets from a WooCommerce order to the payment that settled it in one step.

Build your own checkout, step by step →