Skip to content

Create merchants and run KYC from your product

When the businesses that use your software need to take payments, each one becomes its own Flint merchant. Your backend creates the merchant from your own signup form, your pages host identity and business verification (KYC), and Flint tells your code when the business can take payments and receive payouts. The owner never has to leave your product or hand you a key, and its sales settle to its own bank account.

The examples follow one platform. Classboard is scheduling software for studios, and Tidewater Yoga is one of its studios, owned by Maya Okafor. Build payments into your platform follows the same studio past onboarding, through selling, platform fees, and payouts.

How it works#

Onboarding has two parts. A merchant signup creates the merchant and installs your partner app on it, from one emailed code. Onboarding then collects what the payment processor needs to verify the business, in Flint's components inside your pages, until the merchant's readiness says it can take payments.

Creating and verifying a merchantResponse
OwnerYour backendFlintname, email, and business name in your signup formPOST /v1/merchant-signupsemails a code that names your apptypes the code and ticks Flint's merchant termsPOST /v1/merchant-signups/{id}/verifya test and a live authorization codePOST /v1/oauth/token for each codeGET /v1/onboarding/state, then POST /v1/merchant-account-sessionsenters identity, business, and bank details in the component in your pagemerchant.readiness_updated
  1. Owner sends name, email, and business name in your signup form to Your backend
  2. Your backend sends POST /v1/merchant-signups to Flint
  3. Flint sends emails a code that names your app to Owner
  4. Owner sends types the code and ticks Flint's merchant terms to Your backend
  5. Your backend sends POST /v1/merchant-signups/{id}/verify to Flint
  6. Flint returns a test and a live authorization code to Your backend
  7. Your backend sends POST /v1/oauth/token for each code to Flint
  8. Your backend sends GET /v1/onboarding/state, then POST /v1/merchant-account-sessions to Flint
  9. Owner sends enters identity, business, and bank details in the component in your page to Flint
  10. Flint sends merchant.readiness_updated to Your backend

A business whose owner already has a Flint merchant connects it on Flint's consent screen instead, as Connect a business that already has a Flint account describes. Onboarding works the same way after that.

Before you start#

You need four things, and only the last one waits on Flint:

  1. A partner app. Register one app for all your merchants with your own live API key and developer.partner_apps.write, and give it a permission manifest that asks for setting up payments: merchants.onboarding.read, merchants.onboarding.write, merchants.account_sessions.write, and merchants.profile.read. Register a credential so your backend can sign client assertions. Create the app and Register a credential cover both.
  2. A merchant_action_url on the app. It is the page in your product where Flint sends the owner when one of its emails asks them 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.
  3. A signup key. A live API key on your own merchant account with developer.merchant_signups.write. Keep it separate from the key that manages the app, so the service that signs businesses up can't change your manifest, fee cap, or credentials.
  4. Flint's approval, for live mode. Live signups, and live onboarding run with your partner app token, need the create_merchants and merchant_onboarding capabilities to be active. Flint grants them in a one-time review of your platform: finish your own account's live onboarding, describe your platform in platform_profile, and accept the Flint Platform Agreement. Become an approved platform has the requirements and statuses.

Test mode doesn't wait for the review. Until Flint approves create_merchants, you can create test-only signups for your own team's verified addresses, plus-addresses included, such as you+studio3@classboard.example, and build the whole flow in sandboxes.

Create the merchant#

1. Start a signup#

Maya enters her name, email, and the studio's name in Classboard's form. Classboard's backend keeps a PKCE verifier for the signup and sends its challenge with the signup key:

cURL
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",
    "timezone": "America/Chicago",
    "modes": ["test", "live"],
    "requested_permission_ids": ["setup_payments", "sell"],
    "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "code_challenge_method": "S256",
    "external_reference_id": "studio_8812"
  }'

The response is 201 with a MerchantSignup in status pending. modes decides which environment grants the install gets; live needs create_merchants. requested_permission_ids picks optional permissions from your manifest, and the required ones are always included. external_reference_id is your own record for the business, and you can filter signups by it later.

Flint checks your app, the permissions, your merchant_action_url, the create_merchants capability, and the signup quotas before it sends any email. A refused signup sends nothing. Create a merchant signup lists each check, its error, and the quotas.

2. The owner confirms with a code#

Flint emails Maya from Flint Pay. The email names Classboard, the studio, the title of each permission requested, Classboard's platform fee cap if it has one, and Flint's merchant terms. It says that entering the code creates her Flint account and connects Classboard. The code has 8 characters in two groups, such as K7QM-4TXD, and works for 15 minutes.

Maya types the code into Classboard's form. Beside the code field, show Flint's merchant terms checkbox, linked to the signup's merchant_terms.url. When she submits, send the code and her acceptance:

cURL
curl -X POST https://api.withflintpay.com/v1/merchant-signups/msu_01KF3A7D2Q8W4E6R0T2Y4U6I8O/verify \
  -H "Authorization: Bearer $CLASSBOARD_SIGNUP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: verify-studio-8812" \
  -d '{
    "verification_code": "K7QM-4TXD",
    "terms_acceptance": {
      "merchant_terms_version": "2026-10-01",
      "ip_address": "203.0.113.7",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_1) AppleWebKit/605.1.15"
    },
    "expected_version": 1
  }'

merchant_terms_version must equal the signup's merchant_terms.version, and the IP address and user agent are Maya's browser's. Flint creates a new merchant and its default sandbox, records her acceptance, installs Classboard with a test grant and a live grant, and returns test_authorization_code and live_authorization_code.

If Maya already has a Flint login, the new merchant is added to it, and her other merchants aren't touched or shared. The responses look the same either way, so Classboard never learns whether she had one.

3. Exchange the codes for partner app tokens#

Exchange each code at POST /v1/oauth/token within 5 minutes, with your client assertion and the PKCE verifier, and without redirect_uri:

cURL
curl -X POST https://api.withflintpay.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=FPAC_LIVE_AUTHORIZATION_CODE" \
  -d "code_verifier=YOUR_CODE_VERIFIER" \
  -d "client_id=FPC_CLIENT_ID" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=YOUR_FRESH_SIGNED_JWT"

Store the merchant_id, partner_app_install_id, and environment_grant_id from each exchange with the studio's record. From then on, mint one partner app token per mode with grant_type=client_credentials, use it for every merchant, and name the studio on each request in Flint-Merchant-Id. Take that ID from your own record, never from input a customer controls. Mint a partner app token covers caching and expiry.

Flint sends partner_app_install.created and environment_grant.created to your app's webhook endpoint after the first exchange, and partner_app_install.updated and environment_grant.created after the second.

When a step goes differently#

What happenedWhat to do
Verify returned 503 SERVICE_UNAVAILABLEFlint finishes creating the merchant anyway. Send verify again with the same code to get the result.
The verify response was lost, or the codes expired before you exchanged themPOST /v1/merchant-signups/{merchant_signup_id}/rotate-authorization-codes mints new codes, within 24 hours of completion, for grants never exchanged. See Mint new authorization codes.
The owner mistyped the codeVerify returns 400 INVALID_REQUEST at verification_code. Five wrong codes use up a code.
The code expired or was used upPOST /v1/merchant-signups/{merchant_signup_id}/resend-code sends a new one, up to 3 per signup.
The owner's email belongs to a Flint login that can't be used for a new merchantVerify returns 409 ACTION_NOT_ALLOWED with reason owner_identity_conflict. The owner contacts Flint support.
The owner already owns 10 active merchantsVerify returns 409 LIMIT_REACHED with reason owned_merchants. The owner archives one first.
The owner never confirmedThe signup reads expired 24 hours after you created it. Start a new one.

A signup sends no webhook events of its own: every change follows one of your requests, except expiry, which expires_at predicts. Merchant signups has every field, limit, and error.

Connect a business that already has a Flint account#

A signup always creates a new merchant. A business whose owner already runs a Flint merchant connects it to your app on Flint's consent screen. Send the owner's browser to GET /v1/oauth/authorize with your client_id, a registered redirect_uri, mode=test or mode=live, a state, and a PKCE challenge. The owner signs in to Flint, picks the merchant, and approves the same permissions. Flint redirects back with a code, which you exchange as above, but with the same redirect_uri.

Authorize test and live separately: each mode is its own grant. A live install doesn't need a merchant that has finished onboarding. Build the authorize URL and Exchange the code have the parameters, errors, and responses.

Run KYC onboarding#

Onboarding is a loop. Read GET /v1/onboarding/state with the partner app token for the merchant's mode, do what its next_step says, and read it again until status is complete:

cURL
curl https://api.withflintpay.com/v1/onboarding/state \
  -H "Authorization: Bearer $CLASSBOARD_LIVE_PARTNER_TOKEN" \
  -H "Flint-Merchant-Id: $TIDEWATER_MERCHANT_ID"
statusMeaningWhat your backend does
needs_inputYour backend has a call to make. next_step.action_type is advance_onboarding.Send the fields in next_step.required_fields, such as country and profile.support_email, to POST /v1/onboarding/advance.
needs_external_actionThe owner must enter details. next_step.action_type is create_merchant_account_session.Send next_step.merchant_account_session unchanged as the body of POST /v1/merchant-account-sessions, and mount the component for the owner.
waiting_for_reviewFlint or the payment processor is reviewing what the owner submitted.Read the state again later. Don't open another session.
completeOnboarding is finished.Read readiness on GET /v1/merchant to learn whether the business can take payments.

Onboarding supports businesses in the United States, and their buyers can pay with cards issued anywhere. Set profile.support_email before the first live activation: buyers see it on receipts, and Flint doesn't fall back to the account email. Read the state and Submit account intent cover each field.

Verify the business in your page#

Create a merchant account session only after your product has authenticated the owner and confirmed they manage this merchant. A partner app token proves the business approved your app, not who is at the browser.

cURL
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"
  }'

Return the client session to the owner's browser and mount Account Onboarding with Connect.js. The owner enters identity details, business details, documents, the payout bank account, and the processor's agreement in the component. None of it passes through your backend. A partner app token opens account_onboarding and notification_banner only.

The incremental strategy collects only what the payment processor needs now, so the form is short and the processor can ask for more later. To collect everything up front, send "collection_strategy": "upfront" and "future_requirements": "include". Merchant account sessions has the Connect.js recipe and the refresh rules.

Or send the owner to Flint's hosted page#

Without Connect.js, create an onboarding access link with the same credential and redirect the owner to its url:

cURL
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"}'

Flint's page shows "Verification for Tidewater Yoga", names Classboard as the requester, and returns the owner to return_url when they finish or exit. The return_url origin must match your merchant_action_url or one of your redirect URIs. The link opens once, within 5 minutes, and whoever opens it can enter the business's details, so redirect the owner at once and never email or log it. See Onboarding access links.

After the owner exits#

Leaving the component isn't completion: the owner may not have submitted everything. Read the onboarding state again, and keep reading it on the polling schedule while status is waiting_for_review.

KYC status and requirements#

Onboarding state describes setup. Whether the business can take payments now is readiness on GET /v1/merchant, which the partner app token reads with merchants.profile.read:

JSON
{
  "data": {
    "merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
    "business_name": "Tidewater Yoga",
    "readiness": {
      "payments": { "status": "ready", "next_actions": [] },
      "payouts": {
        "status": "pending",
        "status_reason": "pending_verification",
        "next_actions": []
      },
      "observed_at": "2026-11-21T14:19:00Z"
    }
  },
  "request_id": "req_01KWM6T2B5VJ0Q8ZK3N1H7D4RA"
}

The response above is shortened. payments decides whether buyers can pay, and payouts whether the balance can reach the bank. They move separately: here Tidewater Yoga can take card payments while the processor confirms its bank account, and sales wait in its balance until payouts are ready.

Axis statusMeaning
readyWorks now.
pendingWaiting. pending_verification means submitted details are under review, and onboarding_not_started means the owner hasn't submitted yet.
blockedSomething must be resolved first. status_reason says what, and next_actions says who acts.
not_requestedThe account never requested this capability.
not_availableFlint couldn't observe readiness. Read it again later.

Turn on checkout in your product when readiness.payments.status is ready. Status reasons explains each reason and what to do about it.

Requirements the processor asks for#

readiness.requirements lists what the payment processor needs, in Flint requirement codes such as business_tax_id, representative_identity_document, and payout_destination, grouped by when they're due:

ArrayMeaning
currently_dueNeeded now, by due_at when one is set.
past_dueMissed its deadline. A capability it stops is blocked.
pending_verificationSubmitted and under review. Nothing to do.
upcoming_dueRequired from upcoming_due_at. A warning only until then.
eventually_dueNot due yet and has no date.

readiness.requirements.errors lists failed checks, such as document_unreadable or tax_id_mismatch, each with a message and resolution to show the owner. Requirement codes lists every code.

The processor can ask for more after onboarding, so KYC isn't done once. Subscribe to merchant.readiness_updated and read GET /v1/merchant when it fires. When information is due, a next_actions entry of type create_merchant_account_session carries the exact session body, including any targeted_requirements, so the component asks only for what's missing. Send it unchanged and mount it for the owner. Handle later requirements shows the loop.

To see every merchant's readiness without a request per merchant, list your app's installs: each grant shows merchant_readiness. See See which merchants can take payments.

What the merchant sees#

From the owner's side, onboarding stays inside your product:

  1. Your signup form, then an email from Flint Pay with the code. It names your app, the business, what your app may do, your platform fee cap, and Flint's merchant terms. The email tells the owner that an app only ever asks for a code like this one, never for a 6-digit Flint sign-in code.
  2. Your form again, where they type the code and tick Flint's terms checkbox. That's the whole signup. They don't sign in to Flint or create a password.
  3. Flint's verification component in your settings page, or Flint's hosted page titled "Verification for" the business, naming your app as the requester.
  4. Emails that lead back to you. While your install manages the merchant, Flint's emails about finishing verification, and the processor's notification link, lead to your merchant_action_url. Sign the owner in there and open the step readiness names.

The owner has a Flint login from the moment the signup completes, with the email they confirmed, and can sign in to Flint with an emailed code whenever they choose. Some notices still lead to that login: the processor's links about the account, payouts, balances, documents, payments, and disputes, and Flint's dispute, payout, and risk notices. Tell owners in your product that these come from Flint and that they sign in with the email they signed up with. Emails that lead to your app lists each one.

If the owner signs in to the Flint Dashboard, a dismissible banner says your app set up the account and that they can manage payments there or in your app. Settings > Connected apps lists your install as created through its signup.

If the owner disconnects your app, they keep the merchant, its login, and its payouts. Your tokens stop working for it, the signup left you no key or login of theirs to revoke, and emails go back to Flint's sign-in for good. See When the merchant was created by a signup.

Test it#

Build the whole flow in test mode before Flint reviews your platform. No account yet? Sign up and you get a sandbox.

  1. Create a test-only signup, with modes set to ["test"], for a plus-address of your own verified sign-in email. Add "sandbox_initial_onboarding": "not_started" so the new merchant's sandbox starts with requirements due. Without it, the sandbox is already verified.
  2. Verify with the code from your inbox, exchange the test code, and read the onboarding state with the test partner app token.
  3. Mount Account Onboarding and enter the sandbox verification values. Never upload a real identity document to a sandbox.
  4. Read GET /v1/merchant until readiness.payments.status is ready, and check that merchant.readiness_updated reached your endpoint.

Next steps#

Build payments into your platformSell under the install, take a platform fee, and pay out to each merchant.Payments for SaaS platforms, end to endThe calls, events, and deadlines from app registration to the first payout.Merchant signupsEvery field, check, limit, and error for creating merchants.Partner app installsRegister the app, sign client assertions, mint tokens, and handle disconnects.Merchant account sessionsMount verification components and refresh their client secrets.MerchantsReadiness, next actions, and every requirement code.

Ready to build? Create a Flint account and create your first test merchant.

Was this helpful?