Every business on your platform, taking payments.

1. 01

   Create the merchant

   POST /v1/onboarding/start

   Send the owner's email and name, then confirm the code Flint emails them. Those two calls create the merchant, its owner, and a private sandbox. There is no application to fill in and no queue to wait in before you can build.

   curlCopy

   curl -X POST https://api.withflintpay.com/v1/onboarding/start \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: onboard-northside-001" \
     -d '{
       "email": "owner@northsidecoffee.example",
       "first_name": "Ada",
       "last_name": "Okonkwo"
     }'

   This call takes no API key. It creates the merchant that every later key belongs to.

   one merchant, the first twenty minutes

   Northside Coffee

   Merchant created, email confirmed14:02

   First API key issued14:03

   Verification opened inside your settings page14:04

   First order paid in the sandbox14:19

2. 02

   Hand them a key

   POST /v1/onboarding/api-key

   The first key is available as soon as can_issue_api_key is true, which is right after the email is confirmed. It is bound to the merchant's sandbox, so orders, checkout, refunds, and webhooks all work while the documents are still being collected.

   curlCopy

   curl -X POST https://api.withflintpay.com/v1/onboarding/api-key \
     -H "Authorization: Bearer ONBOARDING_SESSION_TOKEN" \
     -H "Idempotency-Key: first-key-northside-001" \
     -d '{ "name": "Northside Coffee sandbox" }'

   The secret is returned once, on this response. Store it against the merchant in your secrets manager.

   the key, one call later

   Northside Coffee sandbox

   api_key_id

   key_1kmn0aExample

   merchant_id

   mer_1kmn0aExample

   sandbox_id

   test_1kmn0aExample

   status

   Active

   Then one key per job

   • commerce.orders.write
   • commerce.orders.read
   • payments.payment_intents.write
   • payments.payment_intents.read
   • checkouts.checkout_sessions.write
   • checkouts.checkout_sessions.read

   Ask POST /v1/api-keys for three write scopes and the key carries these six, because a write scope includes its read. A key can only grant scopes it holds, so a checkout key can never mint a broader one.

3. 03

   Verify the business inside your product

   POST /v1/merchant-account-sessions

   Submit the business profile with one call, then read the state. When a step needs the owner, next_step.launch names the component to mount, and the session call returns the credentials for it. Identity, documents, the payout bank account, and the agreements are collected in your pages, under your navigation.

   GET /v1/onboarding/stateCopy

   {
     "data": {
       "merchant_id": "mer_1kmn0aExample",
       "can_issue_api_key": true,
       "requested_capabilities": [
         "accept_card_payments",
         "receive_payouts"
       ],
       "requirements": {
         "currently_due": ["business_verification_document"]
       },
       "next_step": {
         "machine_completable": false,
         "launch": {
           "method": "POST",
           "endpoint": "https://api.withflintpay.com/v1/merchant-account-sessions",
           "component": "account_onboarding",
           "recommended_policy": {
             "collection_strategy": "incremental",
             "future_requirements": "omit"
           }
         }
       }
     }
   }

   The response says what to render next. Copy next_step.launch into the session call and your wizard never has to interpret a requirement.

   curlCopy

   curl -X POST https://api.withflintpay.com/v1/merchant-account-sessions \
     -H "Authorization: Bearer MERCHANT_KEY" \
     -H "Idempotency-Key: verify-northside-001" \
     -d '{
       "components": ["account_onboarding", "notification_banner"],
       "collection_strategy": "incremental",
       "future_requirements": "omit"
     }'

   Incremental collection asks only for what is due now. When a requirement comes up months later, the same call opens a session for that one item.

   • POST /v1/onboarding/advance
   • GET /v1/onboarding/state
   • next_step.launch
   • POST /v1/merchant-account-sessions/refresh
4. 04

   Go live when readiness says so

   GET /v1/merchant

   The merchant answers the two questions your product has: can this business charge, and can it be paid. Subscribe to merchant.readiness.updated, read the merchant when it fires, and turn checkout on in your UI when payments reports ready.

   GET /v1/merchantCopy

   {
     "data": {
       "merchant_id": "mer_1kmn0aExample",
       "business_name": "Northside Coffee",
       "payments": { "status": "ready" },
       "payouts": {
         "status": "pending",
         "status_reason": "pending_verification"
       },
       "observed_at": "2026-09-19T14:04:11Z"
     }
   }

   Charging is cleared while payouts finish verifying. Sales made now wait in the merchant's balance and pay out when payouts clears.

   Every status either one can report

   • ready
   • pending
   • blocked
   • not_available
   • not_requested

   Each status that is not ready comes with a reason and the requirements still outstanding.

   status_reason

   Going live is a key swap. The same code that ran in the sandbox runs against real money.

   Flint-Mode: live

{
  "data": [
    {
      "type": "payment",
      "status": "available",
      "merchant_id": "mer_1kmn0aExample",
      "order_id": "ord_1kmn0aExample",
      "amount_money": { "amount": 1053, "currency": "USD" },
      "fee_money": { "amount": 75, "currency": "USD" },
      "net_money": { "amount": 978, "currency": "USD" },
      "available_at": "2026-09-21T00:00:00Z"
    }
  ]
}

Weighing a payfac registration instead? Payfac-as-a-service, compared sets the vendors side by side on onboarding, registration, and economics, and Should my SaaS become a payfac? works through the costs.

reviewed 2026-09-19 against the onboarding, partner app, and webhooks guides · corrections: Flint Help