FlintflintDocs

Accept Your First Payment

In this guide you create an order, collect a card payment for it on a Flint-hosted checkout page, and verify the payment from your backend. All you need is curl and a browser. If you want to embed payment collection in your own UI instead of redirecting to a hosted page, follow Embedded Payments with Stripe Elements after this.

What You Need#

  • A test API key (flint_test_...). Create one on the dashboard's API keys page, or, to set up a merchant entirely over the API, use the API setup flow.
  • Every request goes to https://api.withflintpay.com with your key in the Authorization header. Run this to confirm your key works and that you can take card payments:
Bash
curl "https://api.withflintpay.com/v1/capabilities?capability=accept_card_payments" \
  -H "Authorization: Bearer YOUR_API_KEY"

A 200 with "status": "ready" means you're set to take the payment below.

Test keys are bound to a sandbox, an isolated environment with its own test data. Keys from the dashboard and the API setup flow come sandbox-bound automatically.

The POST examples below also send an Idempotency-Key header. It's optional, but worth the habit: retry a request with the same key and you get the original result back instead of a duplicate. See Idempotency.

Step 1: Create an Order#

The order is the commerce record everything else attaches to: totals, payments, and later refunds. Amounts are integers in the currency's minor unit, so 2500 is $25.00.

Bash
curl -X POST https://api.withflintpay.com/v1/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-tote-001" \
  -d '{
    "line_items": [{
      "name": "Canvas tote bag",
      "quantity": 1,
      "unit_price_money": {"amount": 2500, "currency": "USD"}
    }]
  }'
JSON
{
  "data": {
    "order_id": "ord_1kmn0aExample",
    "status": "open",
    "pricing_amounts": {
      "subtotal_money": {"amount": 2500, "currency": "USD"},
      "total_money": {"amount": 2500, "currency": "USD"}
    },
    "line_items": [...]
  }
}

Save data.order_id and substitute it wherever the examples below use ord_1kmn0aExample. (If you run these requests from this page while signed in, your real order id is captured and filled into the later steps for you.) The order is open, meaning it still has a balance to collect. Line items here are ad hoc (a name and a price); to sell from your catalog, reference a product instead, and pass customer_id if you want the order tied to a customer record.

Step 2: Create a Checkout Session#

A checkout session gives you a Flint-hosted payment page for the order.

Bash
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: checkout-tote-001" \
  -d '{
    "order_id": "ord_1kmn0aExample",
    "redirects": {
      "success_redirect_url": "https://example.com/thanks",
      "cancel_redirect_url": "https://example.com/cart"
    }
  }'
JSON
{
  "data": {
    "checkout_session_id": "cs_1kmn0aExample",
    "status": "open",
    "order_id": "ord_1kmn0aExample",
    "url": "https://checkout.withflintpay.com/checkout/cs_1kmn0aExample#checkout_token=..."
  }
}

Save data.url and use it exactly as returned. The #checkout_token fragment is what authenticates the buyer, so don't strip or rebuild the URL. In production your backend sends the buyer there, either an HTTP redirect from a server-rendered app or a browser navigation from a web app.

Step 3: Pay with a Test Card#

If your sandbox can't take card payments yet, the hosted page shows "no payment methods available" instead of a card form. Check your card-payments capability with GET /v1/capabilities?capability=accept_card_payments; once it reports ready, reload the page.

Open data.url in your browser. The page shows a test-mode banner because the session was created with a test key; no money moves.

Fill in the buyer details with any test values, and pay with a test card. Flint processes card payments on Stripe, so Stripe's standard test cards work in test mode (you don't need a Stripe account):

  • Card number: 4242 4242 4242 4242
  • Expiration: any future date
  • CVC: any 3 digits

After the payment succeeds, the page redirects to your success_redirect_url with csId and orderId appended as query parameters.

Step 4: Verify the Payment#

The redirect tells the buyer their payment worked; your backend should confirm it independently before doing anything irreversible. The orderId query parameter from the redirect tells you which order to fetch:

Bash
curl https://api.withflintpay.com/v1/orders/ord_1kmn0aExample \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "order_id": "ord_1kmn0aExample",
    "status": "paid",
    "settlement_amounts": {
      "paid_money": {"amount": 2500, "currency": "USD"},
      "amount_due_money": {"amount": 0, "currency": "USD"}
    }
  }
}

The order is paid and nothing is outstanding, so the payment is complete. If the buyer abandoned checkout or their card was declined, the order instead stays open with paid_money at 0.

For this test, the fetch above is all the confirmation you need. In production, don't fulfill based on the browser redirect alone. A buyer can close the tab before redirecting, or hit the URL directly. Subscribe to webhooks and treat the webhook (or a backend fetch like the one above) as the signal to fulfill.

Next Steps#

Rate this doc