Sell with hosted checkout

Sell a catalog product once through Flint's hosted checkout or a payment link, grant what the buyer paid for from a webhook, and take it back after a refund or chargeback. It suits a course, a template pack, a download, a booked service, or goods, sold once rather than on a plan.

What you build#

Steps#

1. Create the product once#

Create a catalog product with product_type: "digital" for a download or course, or "service" for work you do, and give it one priced variant. Its default_variant_id is what you sell. Use quick_pay only for a one-off amount with no product behind it: its item holds only a name, an amount, and tax, so the order doesn't record what was bought. Create a product with one price covers the fields.

curl -X POST https://api.withflintpay.com/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: product-course-intro" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_mode": "simple",
    "name": "Intro to ceramics course",
    "product_type": "digital",
    "default_variant": {
      "sku": "COURSE-CERAMICS-101",
      "unit_price_money": { "amount": 4900, "currency": "USD" }
    }
  }'

2. Choose how buyers reach checkout#

Use a checkout session when your app knows which of its users is buying: your server creates the order, puts your user ID in its metadata, and sends that buyer to the session. Use a payment link when one URL serves everyone, such as a buy button on a public page. A link's metadata is copied to every order it creates, so it can't carry a buyer's ID: require the buyer's email with buyer_fields.require_email and match each paid order to an account by its buyer_contact.email. Payment links vs checkout sessions vs invoices compares the options.

3. Create the order and send the buyer to checkout#

Create an order with a variant line. A catalog line takes its name, price, and tax from the catalog.

curl -X POST https://api.withflintpay.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-user-4821-course-intro" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "type": "variant", "variant_id": "var_1kmn0aExample", "quantity": 1 }
    ],
    "metadata": { "user_id": "user_4821" }
  }'

Then create a checkout session for it and redirect the buyer to its url exactly as returned. Send the buyer to checkout explains why the #checkout_token fragment must stay.

curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: checkout-user-4821-course-intro" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order",
    "order_id": "ord_1kmn0aExample",
    "redirects": {
      "success_url": "https://example.com/thanks",
      "cancel_url": "https://example.com/courses"
    }
  }'

4. Grant access on order.paid#

Verify the delivery, skip a webhook_event_id you already processed, read the order, check that payment_status is paid, and grant each line to the user in metadata. Accept a payment with Next.js has the handler code, and Deduplicate and process asynchronously shows the job that does the work.

For orders also paid through manual capture, a final capture can settle the order below its original price. settlement_amounts.released_money records the discharged debt; use paid_money and net_collected_money for actual collections. Hosted checkout itself uses automatic capture.

If the buyer closes checkout while a payment is processing, Flint continues recording its outcome. Keep waiting for order.paid before granting access. Closing checkout does not prove that the payment failed.

5. Deliver what was bought#

Flint doesn't host downloads or issue license keys: your server serves the file, generates the key, or opens the course after order.paid. A digital or service catalog line needs no fulfillment, so the order's fulfillment_status is not_applicable. For goods you ship or hand over, follow Add shipping to a checkout and Fulfillment.

6. Revoke after a refund or dispute#

Refunds and chargebacks don't remove anything you granted. Take access back yourself, by the rules in Revoke access after a refund or dispute.

Events to handle#

Subscribe your endpoint to these events. Choosing the right event explains why order.paid, and not a session or payment event, means the sale is paid.

Never act on refund.created. A pending refund can still fail.

Revoke access after a refund or dispute#

Events repeat and arrive in any order. Each rule below reads current state and recomputes from it, so the order they arrive in doesn't matter.

• Refunds. On any refund or order refund event, list the order's refunds with GET /v1/refunds?order_id=...&status=succeeded,partially_succeeded. Refunds carry order_id. For each line, subtract the quantity in those refunds' line_item_allocations from the line's quantity, and grant what is left. Don't use the order line's refunded_quantity for this: it moves when the card network accepts a refund, before the refund succeeds, and moves back if it fails. An amount refund counts a unit only once the line's refunded money reaches a whole unit's price, so a small goodwill refund revokes nothing. If your policy differs, decide from the refund's amount_money instead.
• Disputes. On any dispute event, read the dispute with GET /v1/disputes/{dispute_id} and act on its status. Disputes carry order_id.

Restore means returning to what the refund rule leaves, not the full quantity: compute access from the refund-adjusted quantity, then apply any dispute hold on top. Statuses describes each value, and Refund events the refund outcomes.

What to store#

Deadlines#

What you must handle#

Before launch#

1. Keep the secret key on your server, and give each key only the scopes it needs. Flint has no publishable key, so a key in browser or app code is a leaked key. See Keep keys on the server.
2. Register a live webhook endpoint with your live key. The endpoint you tested with receives sandbox events only. See Register your production webhook endpoint.
3. Verify every delivery against the raw request body before acting on it. Anyone who finds your URL can send it requests. See Verify the signature.
4. Sell catalog variants, not quick_pay. A quick pay line holds only a name and an amount, so the order can't tell you what was bought. See Quick pay.

Each sale#

5. Send an Idempotency-Key on every create, and reuse it when you retry. A retry without one can create a second order. See Send a key.
6. Redirect to url exactly as returned, #checkout_token included, and keep it out of logs and analytics. The fragment is what opens the session for that buyer. See Send the buyer to checkout.
7. Grant on order.paid, never on the redirect to success_url. A buyer can close the tab first, and anyone can open the URL. See Choosing the right event.
8. Process each webhook_event_id once. The same event can arrive more than once. See How delivery works.
9. Read the order before an irreversible step, and skip snapshots older than the version you applied. Deliveries arrive out of order. See Read statuses from webhooks.
10. Read totals from pricing_amounts instead of computing them. Your own math can be off by a cent. See Computed order amounts.
11. Create a new session for a buyer who comes back later. A session expires 24 hours after creation by default. See Expiration.

After the sale#

12. Watch refund_status, not payment_status. A fully refunded order still reads payment_status: paid. See Orders.
13. Revoke access yourself. A refund never cancels a fulfillment or restocks anything on its own. See When a payment stops shipping.
14. Act on a refund's current status. A succeeded refund can still fail when the buyer's bank rejects the credit. See Track the refund to completion.
15. Don't refund a chargeback. While it is open or lost, the refund fails with 409 ACTION_NOT_ALLOWED. See Decide what to do.
16. Answer a chargeback before evidence_due_at, with your own earlier cutoff. No event fires when it passes. See Build the response queue.

Test it#

Run the whole sale in your sandbox. No account yet? Sign up and you get one.

1. Create the product, an order, and a session with your test key, and pay with a test card. Check that order.paid reached your endpoint and the user got access. Test webhook deliveries covers receiving events on your machine.
2. Refund the order in full and check that access is gone once the refund succeeds.
3. Pay a new order with the dispute test card in Simulate a dispute outcome. Check that access is suspended, then simulate a won ruling and check that it comes back.

Going further#

Ready to sell? Create a Flint account and take your first test payment.