Merchant signups are not available yet. Have the business owner create a Flint account through onboarding or flint signup, then install your app through the consent screen. The signup flow below describes the API for when merchant signups are enabled.
Build payments into your platform
If your product is software that other businesses run on, such as scheduling, booking, restaurant, or vertical SaaS, and you want each business to take payments inside it, start here. The flow touches several features, and each has its own guide. The steps below take them in order, and the sections after them say in one place what your platform can and can't do under a partner app install.
The examples follow one platform. Classboard is scheduling software for studios, and Tidewater Yoga is one of its studios, owned by Maya Okafor. Classboard's backend calls Flint. Maya sees Classboard's pages and Flint's emails, and she only signs in to Flint if she chooses to.
Each studio is its own Flint merchant. Its sales settle to its own bank account, and it pays Flint's processing fee directly. Classboard never holds the studio's money. It can add a platform fee to the payments it creates, which the studio approves in advance, and Flint pays that fee to Classboard's own merchant account.
The credentials involved#
A Flint request runs under one credential, and the credential decides which account and mode it reaches. In this flow a platform uses two:
| Credential | Held by | What it does |
|---|---|---|
| Your live API key | Classboard, for its own Flint merchant account | Registers the partner app, creates the app's webhook endpoints, lists installs, and creates merchant signups. Needs developer.partner_apps.write, webhooks.write, and developer.merchant_signups.write. Give the service that signs up studios a separate key with only the signup scopes, so it can't change the app. |
| Partner app token | Classboard's backend, one per mode for every studio | Minted with the app's own credential. Each request names the studio in Flint-Merchant-Id and acts under its account: it sells, runs onboarding, reads balances and payouts, answers disputes, and brands checkout, limited to what the owner approved. Runs onboarding in test mode. In live mode it runs onboarding once Flint approves Classboard as a platform. |
Maya gives Classboard no credential. A signup issues no API key, CLI login, or onboarding session, so nothing of the studio's stays with Classboard when she disconnects. A studio that already has a Flint account is the exception: see Add a studio that already has a Flint account.
The flow#
- Maya sends enters her name, email, and the studio's name in Classboard's signup form to Classboard
- Classboard sends POST /v1/merchant-signups to Flint
- Flint sends emails a code that names Classboard to Maya
- Maya sends types the code and ticks Flint's terms in Classboard's form to Classboard
- Classboard sends POST /v1/merchant-signups/{id}/verify to Flint
- Flint sends creates the studio and installs Classboard in test and live mode to Classboard
- Classboard sends exchanges each authorization code for a partner app token to Flint
- Maya sends verifies identity and adds a bank account in Classboard's pages to Flint
- Classboard sends sells with a partner app token that names the studio to Flint
- Flint sends pays out to her bank account to Maya
Step 1: register your app once#
Classboard registers one partner app for all its studios. The app's permission manifest lists the access it asks each studio for, in Classboard's words. For Tidewater Yoga that is setting up payments (merchants.onboarding.read, merchants.onboarding.write, and merchants.account_sessions.write), selling classes and memberships (orders, checkout, refunds), reading whether the studio can take payments (merchants.profile.read), showing the studio its balance and payouts (the money_movement.*.read scopes), handling chargebacks (payments.disputes.write), and branding the studio's checkout on its own domain (settings.write and merchants.profile.write).
Register the app with your own live key, then add a credential that lets your backend prove it is the app. Partner app installs covers the manifest, credentials, and client assertions.
Only scopes marked as allowed for partner installs can go in the manifest. What a partner app token can do lists the areas they cover.
Set the app's merchant_action_url too, the page in Classboard where Flint sends Maya when one of its emails asks her to finish verification. Signups need it, and setting it requests the create_merchants platform capability. Its registrable domain must match the website in your platform_profile.
Get approved as a platform#
To create studios in live mode, to run their live onboarding with the partner app token, and to charge platform fees in live mode, Flint reviews Classboard as a platform once. Classboard's own merchant account finishes live onboarding, including a payout bank account. Then, with Classboard's live key, it sets platform_profile on the app, describing its product, the studios it serves, its expected volume, and how it onboards and monitors them, and accepts the Flint Platform Agreement with POST /v1/partner-apps/{partner_app_id}/accept-platform-terms, sending the version the app's platform.current_terms names. The agreement sets out the share of each platform fee Flint withholds, how those withheld fees cover its studios' unrecovered losses first, its starting limits, and when Flint can pause the app. Its permission manifest already asks for merchants.onboarding.write, which requests the merchant_onboarding capability, and merchant_action_url requests create_merchants. Setting a platform_fee_cap requests platform_fees. Set all three before you submit, because Flint's review approves the capabilities the app requests. The app's platform.status becomes pending_review, and Flint sends partner_app.platform_approved, partner_app.platform_limited, or partner_app.platform_rejected to Classboard's own webhook endpoints when it decides.
Test mode doesn't wait for the review. Until Flint approves create_merchants, you can create test-only signups for your own team's addresses, and studios that already have a Flint account can install Classboard in live mode. Live signups wait for it. Become an approved platform covers the requirements, statuses, limits, and events.
Step 2: create the studio with a merchant signup#
Maya enters her name, email, and the studio's name in Classboard's signup form. One emailed code creates the studio's Flint merchant, records her consent and her acceptance of Flint's terms, and installs Classboard in test and live mode. Maya doesn't sign in to Flint, and Classboard receives no key from her.
- Classboard's backend calls
POST /v1/merchant-signupswith its own live key. Keep a PKCE verifier for the signup and send its challenge.
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"],
"requested_permission_ids": ["setup_payments", "sell"],
"code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
"code_challenge_method": "S256",
"external_reference_id": "studio_8812"
}'
- Flint emails Maya a code that names Classboard, the studio, the permissions, and the platform fee cap. It has 8 characters in two groups, such as
K7QM-4TXD, and works for 15 minutes. She types it into Classboard's form and ticks Flint's merchant terms checkbox there, which Classboard links to the signup'smerchant_terms.url. - Classboard's backend calls
POST /v1/merchant-signups/{merchant_signup_id}/verifywith the code and her terms acceptance: the signup'smerchant_terms.version, Maya's browser IP address, and her user agent. Flint creates the studio's merchant and default sandbox, installs Classboard with a test grant and a live grant, and returnstest_authorization_codeandlive_authorization_code. - Classboard exchanges each code at
POST /v1/oauth/tokenwithin 5 minutes, with its client assertion and the PKCE verifier, and withoutredirect_uri. It stores themerchant_id,partner_app_install_id, andenvironment_grant_idthe exchange returns with the studio's record. Flint sendspartner_app_install.createdandenvironment_grant.createdto your app's webhook endpoint after the first exchange. UseGET /v1/partner-apps/{partner_app_id}/installsto reconcile your records.
If Maya already has a Flint login, the signup adds the studio to it and touches none of her other merchants. The responses look the same either way, so Classboard never learns whether she had one. A few things can go differently:
- Verify returns
503 SERVICE_UNAVAILABLE: Flint finishes creating the studio itself. Send verify again with the same code to get the result. - The verify response is lost, or the codes expire before you exchange them:
POST /v1/merchant-signups/{merchant_signup_id}/rotate-authorization-codesmints new ones, within 24 hours of completion, for each grant whose code hasn't been exchanged. - Maya mistypes the code: verify returns
400 INVALID_REQUESTatverification_code. Five wrong codes use up a code, andPOST /v1/merchant-signups/{merchant_signup_id}/resend-codesends a new one, up to 3 per signup. - Maya's email belongs to a Flint login that can't be used for a new studio, such as one whose email was never verified: verify returns
409 ACTION_NOT_ALLOWEDwith reasonowner_identity_conflict. She contacts Flint support.
Merchant signups has every field, limit, and error.
Step 3: build and test in the sandbox#
Everything except live verification and live payments can be built against the studio's sandbox:
- A signup with
testinmodesinstalls Classboard on the studio's default sandbox. Take a test payment with the test partner app token, naming the studio inFlint-Merchant-Idand its sandbox inFlint-Sandbox-Id, usingpm_card_visaor a test card. See Testing. - To rehearse verification against requirements that are due, send
sandbox_initial_onboarding: "not_started"on the signup, then enter the sandbox verification values in the component. Without it, the sandbox is already verified. See Sandboxes. - Before Flint approves
create_merchants, signups work in test mode only and only for your own team's addresses, such asyou+studio3@classboard.example. A signup for another address is refused before any email goes out. - To rehearse onboarding in your product, run the onboarding loop in Step 4 with the test partner app token. In test mode, the install reads and advances onboarding and opens
account_onboardingsessions.
Test and live are separate grants on the same install. Classboard mints one test and one live partner app token and uses them for every studio. Create your partner webhook endpoint with your live key now, with installed_merchant_modes set to ["test", "live"], so the live rollout changes nothing in your code.
Step 4: verify identity and the bank account in your product#
Onboarding is a state machine. Classboard's backend reads GET /v1/onboarding/state with the partner app token and does what next_step says until status is complete, naming the studio in Flint-Merchant-Id. In test mode this works at once. In live mode the token reads onboarding, and runs it once Classboard's merchant_onboarding capability is active.
advance_onboarding: send the country and capabilities withPOST /v1/onboarding/advance. Onboarding supports US businesses.create_merchant_account_session: create a session withPOST /v1/merchant-account-sessions, sendingmerchant_account_sessionas the body, and hand the step to Maya.
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"],
"collection_strategy": "incremental",
"future_requirements": "omit"
}'
Create the session only after Classboard has authenticated Maya and confirmed she manages this studio. A credential proves the studio approved Classboard, not who is at the browser. Return the client secret to her browser and mount Flint's components in Classboard's settings page. Identity details, business details, documents, and the bank account are entered in the component. Classboard's backend never sends them to Flint.
Or send Maya to Flint's hosted page#
If Classboard doesn't embed Connect.js, create an onboarding access link and redirect Maya to its url. Flint's page shows "Verification for Tidewater Yoga", names Classboard as the requester, and opens Account Onboarding and Notification Banner in the token's mode.
curl -X POST https://api.withflintpay.com/v1/onboarding/access-links \
-H "Authorization: Bearer $CLASSBOARD_LIVE_PARTNER_TOKEN" \
-H "Flint-Merchant-Id: $TIDEWATER_MERCHANT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tidewater-onboarding-link-1" \
-d '{"return_url": "https://classboard.example/settings/payments"}'
The return_url is required, and its origin must be the origin of Classboard's merchant_action_url or of one of its redirect URIs. The link opens once, within 5 minutes, and starts a browser session of up to an hour. When Maya exits or finishes, or opens a link that was already used or has expired, the page offers one action: back to return_url. The url is a bearer credential, so create the link only for a person Classboard has just authenticated, redirect them at once, and never email or log it. Use a new Idempotency-Key for each new link. See Onboarding access links.
Finish onboarding#
The same session mechanism mounts payouts, balances, tax_documents, and payments components later. A partner app token opens only account_onboarding and notification_banner. The others also let the person change bank details, the payout schedule, and tax forms, or answer disputes in the browser, so they need the studio's own credential even when the install can read balances and payouts or answer disputes through the API. payments lists the studio's payments and answers disputes, while refunds and capture stay on Flint's API. Merchant Account Sessions has the Connect.js recipes, refresh rules, and the full component list.
When Maya exits the component or the hosted page, read the onboarding state again until status is complete. Live card payments start when readiness.payments.status on GET /v1/merchant is ready, and Flint sends merchant.readiness_updated to Classboard's partner endpoint when readiness changes. Payouts start once the payment processor confirms the bank account, which can take longer, and sales made before then wait in the studio's balance. Going live explains each readiness status.
Maya's Flint login#
Maya has a Flint login from the moment the signup completes, with the email she confirmed, and she can use it any time by signing in to Flint with an emailed code. She doesn't have to. While Classboard's install manages the studio, Flint's emails about finishing verification, and the payment processor's notification link, lead to Classboard's merchant_action_url. Classboard signs Maya in, opens the page that readiness names, and she never sees Flint.
If Maya does sign in to the Flint Dashboard, a dismissible banner tells her Classboard set up the account and that she can manage payments there or in Classboard, and Settings > Connected apps lists Classboard's install as created through its signup.
Some emails still need her Flint login: the processor's links for the account, payouts, balances, documents, payments, and disputes, Flint's dispute and payout notices, and risk and review notices. An install can't open those components or change those settings, so tell Maya where to look, and that she can sign in to Flint with the email she signed up with. You shouldn't rewrite these links. See Emails that lead to your app.
Step 5: sell under the install#
With its live partner app token and Tidewater Yoga's merchant ID in Flint-Merchant-Id, Classboard creates orders and checkouts in the studio's name. The payment belongs to the studio. The studio pays Flint's processing fee, and the net amount reaches its balance.
curl -X POST https://api.withflintpay.com/v1/orders \
-H "Authorization: Bearer $CLASSBOARD_LIVE_PARTNER_TOKEN" \
-H "Flint-Merchant-Id: $TIDEWATER_MERCHANT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: classboard-sale-88213" \
-d '{
"line_items": [
{
"type": "custom",
"name": "10-class pack",
"quantity": 1,
"unit_price_money": {"amount": 15000, "currency": "USD"},
"fulfillment": {"requirement": "none"}
},
{
"type": "custom",
"name": "Grip socks",
"quantity": 1,
"unit_price_money": {"amount": 1400, "currency": "USD"},
"fulfillment": {"requirement": "none"}
}
]
}'
Then choose how the buyer pays:
- Hosted checkout. Create a checkout session for the order, with a theme in the studio's colors. See Sell with hosted checkout.
- Your own page. Collect the card with Stripe Elements and pay the order from your backend. See Embedded payments. Cards work at once. Apple Pay and Google Pay buttons show only on a hostname registered for wallets, and a studio created by signup gives Classboard no credential that can register one. Register wallet domains for a studio says what to do.
Refund through POST /v1/refunds the same way. With the Node or PHP SDK 8.0 prerelease, partnerAppTokens mints and caches the token for you. Pass tokens.app() as the client's token, send the studio's Flint-Merchant-Id on each request, and set ambientCredentials: false, so a missing token fails instead of running under your own key. See Mint and cache tokens with the SDK and Partner app helpers.
Without the SDK, mint each mode's token with grant_type=client_credentials, cache it for all studios, and mint again when it expires after 900 seconds, as Partner app installs describes. Take Flint-Merchant-Id from Classboard's own record of the studio, never from input a customer controls.
Before the studio's first live sale, tell Maya what she sets in Flint, such as the name on her buyers' card statements. See What the studio owner sets or learns in Flint.
Register wallet domains for a studio#
Hosted checkout runs on Flint's domain, so Apple Pay and Google Pay work there with no setup. On Classboard's own page, the buttons show only for a hostname registered with POST /v1/payment-method-domains in the studio's account. Apple Pay and Google Pay setup covers the request and the checks.
No credential that Classboard holds after a signup can make that call. A partner app token can't call the route, and an app can't request payments.payment_method_domains.write. The Dashboard has no screen for wallet domains either. Flint has no install-scoped way to register one. The supported path is a linked API key that Maya creates:
- Send Maya to the Dashboard's linked-key link, as Ask the merchant for a linked API key describes. Tell her to create a restricted live key with only
payments.payment_method_domains.write, which also covers reads, and to send it to Classboard's backend. She signs in to Flint with her emailed code to create it. - Classboard registers each checkout hostname with the key, once the studio's payment onboarding is finished. Before then, registration returns
MERCHANT_NOT_READYwith reasononboarding_required. - Store the key as a secret (API key security). Because Maya created it from the link, it ends when she disconnects Classboard.
If Classboard doesn't want to ask for a key, offer hosted checkout for wallets, and keep card payments on your own page.
Receive every studio's events at one endpoint#
Create one webhook endpoint with event_sources ["partner_app", "installed_merchants"] and your app's live key. It receives your app's install events and the commerce, dispute, and payout events of every studio that installed the app, such as order.paid, refund.succeeded, subscription.past_due, dispute.needs_response, and payout.failed. Every envelope names the studio in source.merchant_id and the install in source.partner_app_install_id.
enabled_events must name each installed-merchant event, and Flint forwards one only while the grant holds the event's read scope or its matching write scope. Merchant profile events, including merchant.readiness_updated, need merchants.profile.read. When readiness changes, read GET /v1/merchant with the partner app token. Dispute, payout, and balance events need the scope that reads their resource, such as payments.disputes.read for dispute.needs_response and money_movement.payouts.read for payout.failed. See Receive webhooks and Webhooks.
Step 6: take a platform fee#
Classboard can earn on the payments it creates for a studio with a platform fee. The studio pays it beside Flint's fees, it comes out of the payment, and Flint takes no share of it. Test mode works without Flint's review. In live mode the app's platform_fees capability must be active, which Flint approves in the review in Get approved as a platform.
Set the cap. With its live key, Classboard sets
platform_fee_capon the app: up to 2.5% of each payment, never more than $5.00. Set it before you submit for review, so the review coversplatform_fees.cURLcurl -X PATCH https://api.withflintpay.com/v1/partner-apps/$CLASSBOARD_PARTNER_APP_ID \ -H "Authorization: Bearer $CLASSBOARD_LIVE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expected_version": 7, "platform_fee_cap": { "percent": 2.5, "maximum_fee_currency_options": {"USD": {"amount": 500, "currency": "USD"}} } }'Maya approves the cap. The code email and Flint's consent screen show it beside the permissions, and her approval is stored on each environment grant as
platform_fee_cap. A studio that installed before Classboard set or raised the cap approves again through the authorize URL. A lower cap applies at once.Charge the fee. Classboard sends
platform_fee.amount_moneywhen it creates the payment. On the $164.00 order from Step 5, a $3.28 fee is 2% of the total, under the cap of $4.10. The buyer pays $164.00. Flint takes its own fees, records Classboard's fee, and Maya nets the rest.cURLcurl -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" } }'Order payment intents,
POST /v1/orders/{order_id}/pay, and standalone payment intents take the same field. Flint refuses a fee above the cap with400 INVALID_REQUEST, a fee in a currency Maya hasn't approved with409 ACTION_NOT_ALLOWEDand reasonplatform_fee_consent_required, and any fee on a subscription with400 INVALID_REQUESTandNOT_ALLOWEDonplatform_fee. Maya's payment shows the fee inplatform_fee, and hermerchant_net_moneyis the capture minus Flint's fees and yours.Refund. Classboard keeps its fee when Maya refunds a payment. To return it, Classboard creates the refund with its partner app token and
refund_platform_fee: true. A refund of the $14.00 grip socks returns $0.28 of the $3.28 fee, the same share of the fee as of the payment. A disputed payment never returns it.cURLcurl -X POST https://api.withflintpay.com/v1/refunds \ -H "Authorization: Bearer $CLASSBOARD_LIVE_PARTNER_TOKEN" \ -H "Flint-Merchant-Id: $TIDEWATER_MERCHANT_ID" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: classboard-refund-88213-socks" \ -d '{ "refund_type": "amount", "payment_intent_id": "pi_01KF2M8W5C9T3B7Q1H4N6R2D0V", "amount_money": {"amount": 1400, "currency": "USD"}, "refund_platform_fee": true }'Read and receive the money. Classboard's own merchant, not a partner app token, reads fees, balances, and payouts with
money_movement.platform_fees.read:GET /v1/platform-fees,GET /v1/platform-fee-balances, andGET /v1/platform-fee-payouts. Flint keeps part of each fee in a reserve for a set time, so the fees cover its studios' unrecovered losses first, as the Flint Platform Agreement sets out. It pays the rest into Classboard's merchant balance daily, and Classboard's normal payouts take it to its bank. Subscribe toplatform_fee.*andplatform_fee_payout.*events on Classboard's own endpoints.
See Platform fees for the checks, how Flint lowers a fee at confirm and capture, the reserve, and reconciliation.
Step 7: pay out to the studio#
Tidewater Yoga's sales settle to its own bank account on its payout schedule. Classboard doesn't hold the money. A payout leaves the studio's Flint balance for the bank account that Maya added in Step 4.
The first payouts are slower than the schedule Maya may expect. A new studio is paid out weekly, on Mondays unless she changes the day, for its first 60 days in live mode. She can pick another day, or monthly with one payout day, but not daily or manual, and not a shorter settlement delay, until the 60 days end. A studio still on weekly payouts then switches to daily. Sales made before the processor confirms her bank account wait in her balance. Don't promise a studio next-day money in Classboard. See New accounts.
To show the studio its balance and payouts in Classboard, read them with the partner app token, naming the studio in Flint-Merchant-Id. With the money_movement.*.read scopes it reads GET /v1/balances, GET /v1/balance-transactions, GET /v1/payouts, GET /v1/payout-settings, and GET /v1/payout-destinations, which shows the bank's name and the account's last four digits. Sending or canceling a payout, changing the schedule or the bank account, and mounting the balances and payouts components need the studio's live credential. See Read money and answer disputes, Payouts, and Reconciliation.
On payments charged a platform fee, each balance transaction includes fee_details. Show flint as Flint’s processing and add-on fees, and platform_fee as Classboard’s fee. The platform entry includes its platform_fee_id and partner_app_id, so Classboard can reconcile its fees without fetching each payment.
With money_movement.payouts.read, Classboard's partner endpoint receives payout.failed when a payout doesn't arrive. With money_movement.balances.read, it receives balance.updated when the balance changes.
When a buyer disputes a payment, dispute.needs_response reaches the same endpoint, and Classboard answers it with the partner app token and payments.disputes.write. It lists the studio's disputes that need a response, opens a response session for Stripe's dispute component in Maya's settings page, or accepts the dispute after she confirms. Authenticate Maya before you return the session's client secret, as for onboarding sessions. See Disputes and chargebacks.
Later, the payment processor can ask the studio for more information. When merchant.readiness_updated arrives, read GET /v1/merchant. A create_merchant_account_session action in readiness carries the exact session body to send, and you create that session with the live partner app token, or with the live credential the owner approved if the app isn't approved yet. The email that told Maya about it leads to Classboard's merchant_action_url, where Classboard signs her in and opens it. See Handle later requirements.
What the studio owner sets or learns in Flint#
Some things stay with the studio owner, because a partner app token can't change them or because they happen in Flint. Tell Maya about each in Classboard, before her first live sale.
- The name on her buyers' card statements.
payments.statement_descriptoris the text a buyer sees for a card or bank payment. It starts as the payment provider's default, Flint doesn't require one before the first sale, and a partner app token can't set it. A buyer who doesn't recognize the name may dispute the charge. Ask Maya to set it in the Flint Dashboard under Settings, Payments, signed in with the email she signed up with. It takes 5 to 22 Latin characters. See Payment settings. - Her first payouts. Weekly, on Mondays unless she picks another day, for the first 60 days in live mode, with no daily option until then. See Step 7 and New accounts.
- Wallet buttons on Classboard's own page. They need a linked API key from her. Hosted checkout needs nothing. See Register wallet domains for a studio.
- Payment and payout changes. Payout schedule and bank account changes, tax settings, reports, and API keys happen under her own credential or in the Dashboard, as the table above lists.
Add a studio that already has a Flint account#
A signup always creates a new merchant. A studio whose owner already has a Flint merchant, or that Classboard onboarded before Flint approved create_merchants, installs Classboard on Flint's consent screen instead. The owner signs in to Flint, picks the merchant, and approves the same permissions.
Create the account by API#
Classboard can also create the merchant without a signup. Maya enters her email in Classboard's form, Classboard's backend starts email verification, and Flint emails her a short code. Three calls take an email address to a merchant and its first key:
POST /v1/onboarding/startemails the code and returns a verification token.POST /v1/onboarding/verify-emailchecks the code, creates the user, the merchant, and the merchant's default sandbox, and returns an onboarding session token. It acts only in the default sandbox.POST /v1/api-keys, with the onboarding session and the default sandbox'ssandbox_id, issues the studio's first sandbox key. Issue it beforefresh_verification_expires_at, 5 minutes after verifying the email.
Signup runs once per studio. API & agent onboarding has the requests, limits, and errors. This merchant has no install yet, so the next two steps connect Classboard to it.
Install the app#
Send Maya to the authorize URL with mode=test to install in test mode, and with mode=live for live. She signs in to Flint with the same email, picks the studio, and approves your app's permissions. A live install doesn't wait for onboarding. Then exchange the code on Classboard's backend and store the merchant_id, partner_app_install_id, and environment_grant_id it returns with the studio's record. The exchange returns no refresh token: from then on, Classboard's partner app tokens reach the studio. The test grant points at one sandbox, and a test token can never act on live data.
Flint sends partner_app_install.created and environment_grant.created to your app's webhook endpoint after the first exchange. Use GET /v1/partner-apps/{partner_app_id}/installs to reconcile your records. With merchants.onboarding.read and merchants.profile.read, Classboard's live partner app token reads the studio's onboarding state and readiness while onboarding runs, naming the studio in Flint-Merchant-Id. The same list shows each grant's merchant_readiness, so Classboard can show which studios still need to finish onboarding without a request per studio. See See which merchants can take payments.
Get a live credential from the owner#
Until Flint approves Classboard as a platform, live onboarding for these studios runs under a live credential that the owner approves. Before then, POST /v1/onboarding/advance and the account session routes return 409 ACTION_NOT_ALLOWED for the live partner app token, with a reason such as platform_onboarding_required and capability merchant_onboarding. Once the app's merchant_onboarding capability is active, the live partner app token runs the same loop and you can skip this step. The onboarding session token and sandbox keys act only in a sandbox. A person who manages the studio's API keys approves a live credential once, in one of two ways:
- A live key. Maya creates a restricted live key on the dashboard's API keys page with
merchants.onboarding.read,merchants.onboarding.write,merchants.account_sessions.write, andmerchants.profile.read, and gives it to Classboard's backend. These scopes cover verification and thebalances,payouts, andtax_documentscomponents. Thepaymentscomponent also needspayments.payment_intents.readandpayments.disputes.write. Work that needs more, such as changing payouts or registering wallet domains, needs the scopes named in What runs under the merchant's own credential. - A live CLI login.
flint login --liveopens the dashboard for approval. The login lasts at most 90 days, can be revoked, and has no key to store. See Sign in.
Neither requires a verified business. This credential is how verification starts. Store it as a secret (API key security). When Maya removes Classboard, a key she created without linking it to the install keeps working until she revokes it on the API keys page. Ask the merchant for a linked API key describes the linked alternative. Verification then runs as in Step 4, with this credential in place of the partner app token.
What a partner app token can do#
A partner app token acts in its own mode for the merchant each request names, on routes whose required scopes that merchant's grant holds. A route outside the grant returns 403 INSUFFICIENT_SCOPE with reason install_scope_not_granted, and a merchant without an active grant returns 403 FORBIDDEN with reason environment_grant_required. These areas have install-scoped routes, each limited to the scopes the owner approved:
| Area | What Classboard can do |
|---|---|
| Orders and payments | Create and edit orders, pay them, read and cancel payment attempts, and create, confirm, capture, and cancel payment intents. Create, read, and delete payment methods. |
| In-person payments | With payments.readers.read or payments.readers.write, list, register, and manage the studio's readers, open Tap to Pay connection sessions, and take payments on them. See In-person payments. |
| Checkout | Create, read, update, and close checkout sessions. Create and manage payment links. |
| Refunds and credit notes | Create, read, and update refunds. Issue and apply credit notes. |
| Customers | Read and write customer records. |
| Catalog | Products, bundles, categories, modifiers, price lists, promotions, inventory, and file uploads for them. |
| Subscriptions and invoices | Plans, offers, and subscriptions. Invoices and their payment attempts. |
| Returns, delivery, and gift cards | Return policies, returns, inspections, and resolutions. Delivery configuration, quotes, and selections. Fulfillments, shipments, and packages. Gift cards. Tickets. |
| Risk and locations | Payment reviews, fraud warnings, risk controls, and locations. |
| Analytics | Overview, payment volume, and subscription analytics. |
| Onboarding | Read onboarding in both modes. In test mode, advance it, including the support contact and website fields it collects, and create and refresh account_onboarding and notification_banner sessions for the owner. In live mode, these need the app's merchant_onboarding platform capability to be active. |
| Merchant profile | Read the Merchant, including its readiness. In live mode, change its business name, logo, and icon. |
| Settings and branding | Read settings, and change checkout branding, legal links, and the checkout, customer account, and invoice presentation defaults, except the fields that stay with the merchant. |
| Custom domains | Create, validate, read, and archive the studio's checkout and customer account hostnames. |
| Balances and payouts | Read balances, balance transactions, payouts, payout settings, and payout destinations. Read only. |
| Disputes | Read disputes, accept them, and open response sessions for evidence. In test mode, simulate their outcomes. |
| Webhook reads | Read webhook events and deliveries, and the endpoints on the merchant's account. |
| Installed-merchant events | Commerce, merchant profile, dispute, payout, and balance events at your partner webhook endpoint, while the grant holds the event's read scope. |
The scope catalog marks which scopes an app can request. The Partner app installs reference and the per-route x-flint-partner-access field in the OpenAPI spec say whether a route accepts a partner app token.
What runs under the merchant's own credential#
Everything else returns 401 INVALID_CREDENTIAL with details[0].reason wrong_credential_type for a partner app token. Use the studio's live key or CLI login, or the studio's dashboard. A studio created by a signup gave Classboard none of these, so Maya does the work in this table in the Flint Dashboard, or Classboard can ask her for a linked API key. Wallet domains are the exception: the Dashboard has no screen for them, so they need a linked key.
| Work | Route examples | Why an install can't do it |
|---|---|---|
The payments account session component | POST /v1/merchant-account-sessions with payments in components | Account sessions an install opens are limited to account_onboarding and notification_banner. Answer disputes with the partner app token through POST /v1/disputes/{dispute_id}/response-sessions instead. |
| Moving money | POST /v1/payouts, POST /v1/payouts/{payout_id}/cancel, PATCH /v1/payout-settings, changing or deleting payout destinations | Where the merchant's money goes is theirs to decide. An app can't request money_movement.payouts.write or money_movement.payout_settings.write. |
| Reports | /v1/reports and report downloads | Report routes accept API keys only. |
| Tax configuration | /v1/tax-connection, tax registrations, /v1/tax-calculation-callbacks | They decide the tax the merchant collects. These routes take the merchant's own credentials, even though they use the settings.* scopes. |
| Wallet domains | /v1/payment-method-domains | An app can't request payments.payment_method_domains.*, and the Dashboard has no screen for them. Use a linked key with payments.payment_method_domains.write: Register wallet domains for a studio. A customer account custom domain also needs a verified domain. |
| Webhook endpoint changes | Creating, updating, and deleting endpoints, rotating secrets, test events, and resends | Your partner endpoints use the app owner's live key. A merchant's own endpoints use the merchant's key. |
| Account administration | API keys, devices, sandboxes, workload identities, merchant billing and the custom domain add-on, customer sessions and access links, customer tax exemptions | No install scope covers these routes. |
Onboarding writes are the exception to that error. In live mode, while the app's merchant_onboarding capability isn't active, a partner app token gets 409 ACTION_NOT_ALLOWED from POST /v1/onboarding/advance and the account session routes, with a reason that follows the app's platform status: platform_onboarding_required, platform_pending_review, platform_rejected, or platform_capability_inactive. Where it can open sessions, only account_onboarding and notification_banner are allowed; others, including balances and payouts, return 400 INVALID_REQUEST with detail NOT_ALLOWED.
Custom domain events go only to the merchant's own webhook endpoints. Classboard can read GET /v1/custom-domains/{custom_domain_id} with the partner app token to follow a domain's status.
Fields an install can't change#
On the routes it can call, a partner app token still can't change the studio's money, when its buyers are charged, risk limits, tax, legal identity, the business details the payment processor verifies, or the account email. In an otherwise well-formed request, sending one of these fields returns 400 INVALID_REQUEST with a NOT_ALLOWED detail per field and param naming it, and nothing in the request is saved. So does null for checkout, customer_account, inventory, invoices, or subscriptions in settings, which clears every field in it.
| Route | Field | Why it stays with the merchant |
|---|---|---|
PATCH /v1/settings | payments.statement_descriptor | Flint applies it to the merchant's payment processor account, and buyers recognize charges by it. |
PATCH /v1/settings | tax_identity | It is the merchant's legal name, registered address, and tax IDs. |
PATCH /v1/settings | tax | It decides the tax the merchant collects. |
PATCH /v1/settings | payment_limits | They are the merchant's risk limits on payment amounts. |
PATCH /v1/settings | checkout.enabled_payment_options | Adding ach_debit requests a new capability for the merchant's payment account. A checkout session or payment link can still choose its own options. |
PATCH /v1/settings | invoices.payment_policy | It sets the payment options invoices offer and their amount limits. |
PATCH /v1/settings | invoices.remit_to_address | It is where buyers send invoice payments. |
PATCH /v1/settings | invoices.default_collection_mode, invoices.default_invoice_payment_term_id, invoices.autopay_retry_policy | They decide whether and when Flint charges buyers for invoices, including ones the studio creates, and whether late fees apply. |
PATCH /v1/settings | inventory.origin_policies | They decide whether Flint refunds a paid order it can't fill and whether a renewal without stock bills the buyer. |
PATCH /v1/settings | subscriptions.default_billing_schedule_owner, subscriptions.dunning_retry_days, subscriptions.dunning_end_action, subscriptions.external_dunning_end_action | They decide whether Flint bills new subscriptions, when it retries failed charges, and what happens after they fail. |
PATCH /v1/settings | customer_account.buyer_capabilities | They let buyers pause, skip, or cancel subscription charges and offer them retention discounts. |
PATCH /v1/merchant | email | It receives Flint's account notices. |
PATCH /v1/merchant | phone, address | The payment processor uses them to verify the business. |
PATCH /v1/merchant | support_email, support_phone, support_url, website_url | The payment processor requires them and reviews the website. Where the app can run onboarding, it sends them through POST /v1/onboarding/advance. |
PATCH /v1/merchant | timezone | It sets the dates Flint uses for tax and reports. |
PATCH /v1/merchant | api_version, expected_api_version | The merchant's own keys and webhook endpoints use its API version. |
PATCH /v1/merchant | metadata | It belongs to the merchant's own integration. |
See Brand checkout and set custom domains.
What a platform can't do#
Plan your product around these limits.
- Take a fee on live payments before Flint approves the platform. A platform fee works in test mode once a studio approves your platform fee cap. In live mode it needs the
platform_feescapability, which takes Flint's review. Until then, charge studios for Classboard directly, outside their payments. - Charge a fee beyond the cap, or on a subscription, invoice, or payment link. A fee never exceeds the cap the studio approved for that mode, and only payments created with a partner app token carry one. Subscriptions, invoices, and payment links accept none.
- Create live studios or drive live onboarding with a partner app token before Flint approves the platform. Until then, live signups are refused, and live onboarding and verification sessions for studios that already have a Flint account run under a live credential that the owner approves. Test mode has no such limit. See Get approved as a platform.
- Create a studio without its owner's consent. Flint creates a merchant only when the owner types the code Flint emailed them, and the signup always creates a new merchant. A platform can't install on an existing merchant, choose its email, or receive an API key from the signup.
- Receive every email the owner gets. Flint's emails about risk, disputes, and payouts, and the payment processor's emails about the account, balances, payouts, documents, and payments, lead to Flint's sign-in, so keep the owner's Flint login in your plans. See Maya's Flint login.
- Move the studio's money under the install. The install reads balances, payouts, and payout destinations, but sending or canceling a payout, changing payout settings or destinations, and mounting the
balancesandpayoutscomponents need the studio's own credential, as the table above shows. - Set the name on the studio's buyers' card statements, or register wallet domains. A partner app token can't change
payments.statement_descriptor, and Flint has no install-scoped route for wallet domains. The owner sets the statement name in the Dashboard, and a linked API key covers wallet domains. See What the studio owner sets or learns in Flint. - Split one payment across sellers from a partner app token. A payment with splits is created by the collecting merchant with its own API key, not by an install token on a studio's behalf. A studio's payments stay the studio's. A marketplace that collects as the merchant of record divides one payment between its sellers with seller splits. Test mode works now; live splits are switched off by default and need Flint's approval of your platform. Splits don't cover checkout sessions, payment links, invoices, subscriptions, or a payment that also carries a platform fee.
Onboarding supports US businesses, and every amount is in USD.