Payments for SaaS platforms, end to end
Let the businesses that run on your software take payments inside it. Each business becomes its own Flint merchant from your signup form, verifies in your pages, and is paid out to its own bank account. Your backend sells for it with one partner app token, and can add a platform fee to each payment it creates. Your platform registers as nothing, holds no merchant funds, and Flint bills it no per-merchant, monthly, or payout fee. It suits scheduling, booking, restaurant, and other vertical SaaS.
The examples follow Classboard, scheduling software for studios, and one studio, Tidewater Yoga. Build payments into your platform has every detail behind these steps.
What you build#
- Your backend sends once: POST /v1/partner-apps, then platform review to Flint
- Studio owner sends signs up in your form to Your backend
- Your backend sends POST /v1/merchant-signups, then verify with the emailed code to Flint
- Your backend sends POST /v1/oauth/token for each mode to Flint
- Studio owner sends verifies the business in Flint's component in your page to Flint
- Flint sends merchant.readiness_updated: payments ready to Your backend
- Your backend sends POST /v1/orders and a checkout session, with a platform fee to Flint
- Flint sends order.paid for the studio to Your backend
- Flint sends payout to the studio's bank to Studio owner
- Flint sends platform fee payout to your own balance to Your backend
Steps#
1. Register your app and get approved#
Register one partner app for all your merchants with your own live API key and developer.partner_apps.write. Its permission manifest lists what you ask each business for, in your words: setting up payments, selling, reading readiness, balances, and payouts, and answering disputes. Register a public key, JWKS URL, or workload identity, so your backend signs a client assertion instead of storing a client secret. Set merchant_action_url, the page where Flint's verification emails send the owner, and a platform_fee_cap, the most one payment can carry as a platform fee. Flint allows up to 25% of a payment and never more than $10,000.00, and the example app in Build a platform sets 2.5% and $5.00. Create the app covers the request.
curl -X POST https://api.withflintpay.com/v1/partner-apps/$CLASSBOARD_PARTNER_APP_ID/accept-platform-terms \
-H "Authorization: Bearer $CLASSBOARD_LIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform_terms_version": "2026-11-16", "expected_version": 7}'
Live signups, live onboarding with your token, and live platform fees need Flint's one-time review. Finish your own account's live onboarding, describe your product and merchants in platform_profile, and accept the Flint Platform Agreement with the version your app's platform.current_terms names, as above. Flint then reviews the app and sends partner_app.platform_approved, partner_app.platform_limited, or partner_app.platform_rejected. Test mode never waits for it, so build everything below in sandboxes first.
2. Create each merchant from your signup form#
The owner enters a name, email, and business name in your form. Your backend calls POST /v1/merchant-signups with a signup key that holds developer.merchant_signups.write, and Flint emails the owner a code that names your app, the permissions, and your fee cap. The owner types it into your form and ticks Flint's merchant terms, and your backend sends both to verify. Flint creates the merchant and installs your app in test and live mode, and returns one authorization code per mode. Exchange each within 5 minutes.
curl -X POST https://api.withflintpay.com/v1/merchant-signups \
-H "Authorization: Bearer $CLASSBOARD_SIGNUP_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: signup-studio-8812" \
-d '{
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"owner": {"email": "maya@tidewateryoga.example", "first_name": "Maya", "last_name": "Okafor"},
"business_name": "Tidewater Yoga",
"modes": ["test", "live"],
"code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
"code_challenge_method": "S256",
"external_reference_id": "studio_8812"
}'
The owner gives you no key and needs no Flint sign-in. A business that already has a Flint account installs your app on Flint's consent screen instead. Create merchants and run KYC from your product covers both paths and every failure.
3. Verify the business in your pages#
Read GET /v1/onboarding/state with the partner app token, naming the merchant in Flint-Merchant-Id, and do what next_step says until status is complete. When the owner has to act, next_step carries the exact body for POST /v1/merchant-account-sessions. Authenticate the owner in your product, create the session, and mount Flint's Account Onboarding component in your settings page. Identity, business details, documents, and the payout bank account go straight from the component to Flint. Without Connect.js, redirect the owner to an onboarding access link instead.
curl -X POST https://api.withflintpay.com/v1/merchant-account-sessions \
-H "Authorization: Bearer $CLASSBOARD_LIVE_PARTNER_TOKEN" \
-H "Flint-Merchant-Id: $TIDEWATER_MERCHANT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tidewater-onboarding-session-1" \
-d '{"components": ["account_onboarding", "notification_banner"]}'
Turn on checkout for the studio when readiness.payments.status on GET /v1/merchant is ready, and read it again each time merchant.readiness_updated arrives. Payouts become ready separately, once the processor confirms the bank account.
4. Sell under the install#
With the live partner app token and the studio's Flint-Merchant-Id, create orders and send buyers to hosted checkout, or collect the card on your own page with Embedded payments. The payment belongs to the studio: it pays Flint's processing fee, and the net reaches its balance. Hosted checkout carries the studio's theme, and Apple Pay and Google Pay work there with no setup.
One webhook endpoint, created with your live key and event_sources ["partner_app", "installed_merchants"], receives every studio's events. Each envelope names the studio in source.merchant_id.
5. Take a platform fee#
Send platform_fee.amount_money on the checkout session, order payment, or payment intent you create with the partner app token. The studio approved your cap at signup. On a $164.00 order, a $3.28 fee is 2% of the total. The studio pays the fee beside Flint's processing fee, Flint takes no share of it, and Flint pays it to your own merchant balance daily, holding 20% in a reserve for 120 days by default.
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
-H "Authorization: Bearer $CLASSBOARD_LIVE_PARTNER_TOKEN" \
-H "Flint-Merchant-Id: $TIDEWATER_MERCHANT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: classboard-checkout-88213" \
-d '{
"type": "order",
"order_id": "ord_01KF2M8W5C9T3B7Q1H4N6R2D0V",
"platform_fee": {"amount_money": {"amount": 328, "currency": "USD"}},
"redirects": {
"success_url": "https://classboard.example/thanks",
"cancel_url": "https://classboard.example/cart"
}
}'
Your platform adds its fee on top of Flint's published rate; it doesn't set the studio's card rate. Subscriptions, invoices, and payment links take no platform fee. A marketplace that collects one payment as the merchant of record and divides it between sellers uses seller splits instead; test mode works now, and live splits need Flint's approval of your platform.
6. Pay out and reconcile#
The studio's sales pay out from its own Flint balance to the bank account the owner added in step 3. A new account is paid out weekly for its first 60 days in live mode, so don't promise next-day money in your product. Read balances, balance transactions, and payouts with the partner app token to show them in your product. Each balance transaction's fee_details separates Flint's fees from yours. Sending a payout or changing the schedule or bank account stays with the owner. Your own fees, balances, and fee payouts read with your own key and money_movement.platform_fees.read.
Events to handle#
Subscribe your partner endpoint to the installed-merchant events, and your own merchant's endpoint to the platform and fee events. Choosing the right event explains why order.paid means a sale is paid.
What to store#
| Value | From | Why |
|---|---|---|
merchant_signup_id and your external_reference_id | The signup | Finds the signup again if the owner retries |
PKCE code_verifier | You generate it per signup | Exchanges the authorization codes |
merchant_id, partner_app_install_id, environment_grant_id | Each code exchange | Names the studio on every request and matches its events |
Partner app token per mode, with expires_at | POST /v1/oauth/token with client credentials | One token serves every studio; mint again before it expires |
readiness.payments.status and observed_at | GET /v1/merchant | Gates checkout, and orders two reads |
order_id and platform_fee_id | The order and its payment | Reconciles each sale and your fee |
webhook_event_id of each processed event | Each delivery | Skips repeats |
Deadlines#
| What runs out | How long | Field | When it passes | What to do |
|---|---|---|---|---|
| Dispute evidence | Until evidence_due_at. There is none when the dispute has no response window, such as a bank return. | Dispute.evidence_due_at | Act by: Once evidence_due_at has passed, reads show is_evidence_deadline_passed: true, is_action_required: false, and no accept in supported_actions. Webhook payloads keep the values from when Flint recorded the change. Flint sends no event. | Respond or accept before evidence_due_at. Subscribe to dispute.needs_response to learn when action is required. |
| Pending merchant signup | 24 hours after creation, until expires_at. A signup Flint is completing never expires. | MerchantSignup.expires_atMerchantSignupWithAuthorizationCodes.expires_at | Computed at read: A pending signup reads expired without changing its version. Flint sends no event. | Create a new merchant signup. |
| Merchant signup email code | 15 minutes after it is issued, until code_expires_at. | MerchantSignup.code_expires_atMerchantSignupWithAuthorizationCodes.code_expires_at | Computed at read: The code stops verifying the signup. Flint sends no event. | Resend the code while the signup is pending and has sends remaining, or create a new signup. |
| Partner app access token | 900 seconds after it is issued, until expires_at. | PartnerAppAuthContext.expires_at | Request: The token stops authenticating. Flint sends no event. | Mint another token with client credentials before it expires. Partner apps have no refresh tokens. |
| Merchant account session launch token | Until launch_token_expires_at. | MerchantAccountSession.launch_token_expires_at | Computed at read: The launch token stops working. Flint sends no event. | Create a new merchant account session. |
| Onboarding requirements deadline | Until due_at on the merchant's readiness requirements. | ReadinessRequirements.due_atResponseWarning.due_at | Act by: Information still due moves to past_due, and payments readiness reads blocked with status_reason requirements_past_due. Readiness changes send merchant.readiness_updated. | When merchant.readiness_updated arrives, read GET /v1/merchant and follow the next actions it lists. |
| Requirements the payment processor schedules | Until upcoming_due_at on the merchant's readiness requirements. The requirements in upcoming_due don't affect payments or payouts before then. | ReadinessRequirements.upcoming_due_at | Act by: The requirements in upcoming_due move to currently_due or past_due, and the requirements deadline applies to them. Readiness changes send merchant.readiness_updated. | Send the recommended create_merchant_account_session body, which sets future_requirements to include, so the account owner can submit them before upcoming_due_at. |
| Accepting a newly announced platform terms version | Until platform.current_terms.acceptance_due_at. It's absent once the current version is already required. | PartnerAppPlatformCurrentTerms.acceptance_due_at | Act by: Accepting the current version becomes required. An app that accepted only an earlier version has the platform_terms requirement outstanding again, and its platform capabilities turn inactive with inactive_reason requirements_due. Flint sends no event when the date passes. | Send the platform_terms_version that current_terms names to POST /v1/partner-apps/{partner_app_id}/accept-platform-terms before the date. You can accept early, and your earlier acceptance keeps platform_terms met until then. |
| Answering a webhook delivery | 10 seconds per attempt. | None | Request: The attempt fails as webhook_timeout, and Flint retries on its schedule. | Return a 2xx within 10 seconds and do the real work in a background job. |
What you must handle#
Before launch#
- Get approved before you promise live signups. Live signups, live onboarding with your token, and live fees all wait on Flint's review. See Become an approved platform.
- Give the signup service its own key. A key with only the signup scopes can't change your app. See Scope keys to the job.
- Sign a new client assertion for each token request. Your backend never stores a client secret. See Sign a client assertion.
- Verify every delivery to your partner endpoint. Anyone who finds the URL can send it requests. See Verify the signature.
Each merchant and sale#
- Take
Flint-Merchant-Idfrom your own records. A value a customer controls could reach another studio. See Name the merchant. - Authenticate the owner before you return a session's client secret. The token proves the business approved you, not who is at the browser. See Verify the business in your page.
- Read onboarding state after the owner exits. Leaving the component isn't completion. See After the owner exits.
- Turn checkout on from readiness, not from onboarding. A complete onboarding can still wait on review. See KYC status and requirements.
- Send an
Idempotency-Keyon every create. A retry without one can create a second signup or order. See Send a key. - Keep each fee within the cap the studio approved. Flint refuses a fee above it. See Before you charge a fee.
After the sale#
- Decide whether a refund returns your fee. Your fee stays unless the refund sends
refund_platform_fee: true, and disputes never return it. See Refunds and disputes. - Answer disputes before
evidence_due_at. No event fires when it passes. See Build the response queue. - Collect later requirements. The processor can ask for more after onboarding, and a requirement left past due can stop payments. See Handle later requirements.
- Set payout expectations for new studios. New accounts pay out weekly for 60 days. See New accounts.
- Stop on disconnect. The owner can remove your app at any time. See When a merchant disconnects.
Test it#
Build the whole flow in test mode before Flint reviews your platform. No account yet? Sign up and you get a sandbox.
- Create a test-only signup for a plus-address of your own verified email with
"sandbox_initial_onboarding": "not_started", verify it, and exchange the test code. - Mount Account Onboarding with the test partner app token and enter the sandbox verification values. Check that
merchant.readiness_updatedarrives andreadiness.payments.statusbecomesready. - Create an order and a checkout session with a platform fee, pay with a test card, and check
order.paidat your partner endpoint and the fee inGET /v1/platform-fees. - Refund part of the order with
refund_platform_fee: true, and check that a share of your fee comes back to the studio.
Going further#
Build payments into your platformCreate merchants and run KYC from your productPartner app installsPlatform feesMarketplaces and seller splitsPayoutsReady to build? Create a Flint account and create your first test merchant.