FlintflintDocs

Onboarding

The onboarding API takes a merchant from an email address to an active Flint account and makes the first sandbox API key available after email verification, without sending the developer through the Flint dashboard. It is a state machine: start with an email, verify it to receive an onboarding_session_token, then read GET /v1/onboarding/state. Submit machine-completable work to advance. When next_step.launch requires a human browser, mint credentials separately with POST /v1/merchant-account-sessions, render the returned embedded components, then poll state.

Before key issuance, onboarding routes authenticate with the onboarding_session_token. Afterward, the same flow accepts a normal API key for later compliance work. The initial key is sandbox-bound and can be issued while provider verification is still outstanding. Payment and payout operations stay gated by their requested capabilities. Browser exit is never completion. State and readiness are backend-observed, pending_verification means wait, and merchant-account-session refresh uses POST /v1/merchant-account-sessions/refresh with the latest signed launch_token.

The API and agent onboarding guide walks through the full state machine, including document handling and first-key issuance.

Endpoints

Create merchant account session#

POST/v1/merchant-account-sessionsIdempotentRequires scope: merchants.account_sessions.write

Creates an embedded browser handoff for one or more allowlisted account components.

Request body
collection_strategyenum
upfrontincremental
componentsarray of enumrequired
account_onboardingaccount_managementpayoutsbalancestax_documentsnotification_banner
future_requirementsenum
omitinclude
sandbox_idstring
targeted_requirement_idsarray of string
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTMERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_REPAIR_REQUIREDMERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_REQUIREDMERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_UNAVAILABLEMERCHANT_ACCOUNT_SESSION_INELIGIBLEMERCHANT_ACCOUNT_SESSION_INVALID_COMPONENTMERCHANT_ACCOUNT_SESSION_INVALID_LAUNCH_TOKENMERCHANT_ACCOUNT_SESSION_INVALID_POLICY_COMBINATIONMERCHANT_ACCOUNT_SESSION_LAUNCH_TOKEN_SCOPE_MISMATCHMERCHANT_ACCOUNT_SESSION_POLICY_NOT_SUPPORTED_BY_COMPONENTMERCHANT_ACCOUNT_SESSION_PREPARATION_FAILEDMERCHANT_ACCOUNT_SESSION_TARGETED_REMEDIATION_UNAVAILABLERATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/merchant-account-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "components": [
      "account_onboarding"
    ],
    "collection_strategy": "upfront",
    "future_requirements": "include"
  }'
JSON
{
  "data": {
    "components": [
      "account_onboarding"
    ],
    "effective_policy": {
      "collection_strategy": "upfront",
      "future_requirements": "include",
      "targeting": "all"
    },
    "external_action": {
      "kind": "embedded",
      "provider_session_expires_at": "2026-03-18T20:00:00Z",
      "launch_token": "aslaunch_v1.example",
      "launch_token_expires_at": "2026-03-18T20:30:00Z",
      "stripe": {
        "client_secret": "acct_session_client_secret_123",
        "publishable_key": "pk_test_123",
        "components": [
          {
            "component": "account_onboarding",
            "component_props": {
              "collectionOptions": {
                "fields": "eventually_due",
                "futureRequirements": "include"
              }
            }
          }
        ]
      }
    },
    "requirements": {
      "currently_due": [
        "merchant_category_code",
        "business_website"
      ],
      "eventually_due": [
        "representative_first_name"
      ],
      "current_deadline_at": "2026-04-01T00:00:00Z"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Refresh merchant account session#

POST/v1/merchant-account-sessions/refreshIdempotentRequires scope: merchants.account_sessions.write

Creates a fresh provider session from a signed launch token after rechecking the authenticated principal, merchant environment, account controller, and component grant.

Request body
launch_tokenstringrequired
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTMERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_REPAIR_REQUIREDMERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_REQUIREDMERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_UNAVAILABLEMERCHANT_ACCOUNT_SESSION_INELIGIBLEMERCHANT_ACCOUNT_SESSION_INVALID_COMPONENTMERCHANT_ACCOUNT_SESSION_INVALID_LAUNCH_TOKENMERCHANT_ACCOUNT_SESSION_INVALID_POLICY_COMBINATIONMERCHANT_ACCOUNT_SESSION_LAUNCH_TOKEN_SCOPE_MISMATCHMERCHANT_ACCOUNT_SESSION_POLICY_NOT_SUPPORTED_BY_COMPONENTMERCHANT_ACCOUNT_SESSION_PREPARATION_FAILEDMERCHANT_ACCOUNT_SESSION_TARGETED_REMEDIATION_UNAVAILABLERATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/merchant-account-sessions/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "launch_token": "aslaunch_v1.example"
  }'
JSON
{
  "data": {
    "components": [
      "account_onboarding"
    ],
    "effective_policy": {
      "collection_strategy": "upfront",
      "future_requirements": "include",
      "targeting": "all"
    },
    "external_action": {
      "kind": "embedded",
      "provider_session_expires_at": "2026-03-18T20:00:00Z",
      "launch_token": "aslaunch_v1.example",
      "launch_token_expires_at": "2026-03-18T20:30:00Z",
      "stripe": {
        "client_secret": "acct_session_client_secret_123",
        "publishable_key": "pk_test_123",
        "components": [
          {
            "component": "account_onboarding",
            "component_props": {
              "collectionOptions": {
                "fields": "eventually_due",
                "futureRequirements": "include"
              }
            }
          }
        ]
      }
    },
    "requirements": {
      "currently_due": [
        "merchant_category_code",
        "business_website"
      ],
      "eventually_due": [
        "representative_first_name"
      ],
      "current_deadline_at": "2026-04-01T00:00:00Z"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Advance onboarding flow#

POST/v1/onboarding/advanceIdempotentRequires scope: merchants.onboarding.write

Submits whatever the caller currently knows, re-evaluates onboarding, reconciles onboarding requirements, and returns the next step in the consolidated onboarding state machine. Send an empty JSON object when the current next_step only asks to refresh onboarding requirements.

Query parameters
sandbox_idstring

Optional sandbox to bind when advancing test-mode onboarding. The returned next_step.submit_endpoint includes this parameter when needed.

Request body
countryenum

ISO 3166-1 alpha-2 country code.

US
profileobject
requested_capabilitiesone of

Exact initial Flint capability set. Include accept_card_payments and receive_payouts together. Optionally include accept_ach_debit_payments, or omit the field to use the card and payout default set.

sandbox_idstring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

ACCOUNT_SETUP_CONFIGURATION_CONFLICTAUTH_REQUIREDCOUNTRY_NOT_SUPPORTEDINVALID_API_KEYINVALID_COUNTRYINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/advance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "profile": {
      "support_email": "help@example.com",
      "website_url": "https://withflintpay.com"
    },
    "country": "US",
    "requested_capabilities": [
      "accept_card_payments",
      "receive_payouts"
    ]
  }'
JSON
{
  "data": {
    "merchant_id": "mer_123",
    "merchant_created": true,
    "email_verified": true,
    "default_sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "can_issue_api_key": true,
    "status": "needs_external_action",
    "next_step": {
      "code": "complete_verification_step",
      "owner": "human",
      "machine_completable": false,
      "launch": {
        "method": "POST",
        "endpoint": "/v1/merchant-account-sessions",
        "component": "account_onboarding",
        "recommended_policy": {
          "collection_strategy": "upfront",
          "future_requirements": "include"
        },
        "sandbox_id": "test_01JQEXAMPLEDEFAULT12345678"
      }
    },
    "country": "US",
    "requested_capabilities": [
      "accept_card_payments",
      "receive_payouts"
    ],
    "profile": {
      "email": "owner@example.com",
      "support_email": "help@example.com",
      "support_phone": "+14155552671",
      "support_url": "https://example.com/support",
      "website_url": "https://withflintpay.com"
    },
    "requirements": {
      "currently_due": [
        "merchant_category_code",
        "business_website"
      ],
      "eventually_due": [
        "representative_first_name"
      ],
      "current_deadline_at": "2026-04-01T00:00:00Z"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create onboarding API key#

POST/v1/onboarding/api-keyIdempotentRequires an onboarding session

Creates the first long-lived external API key and exits onboarding.

Request body
namestringrequired
sandbox_idstring
scopesarray of string
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/api-key \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "First backend integration",
    "scopes": [
      "commerce.orders.read",
      "commerce.orders.write",
      "customers.read",
      "customers.write"
    ]
  }'
JSON
{
  "data": {
    "api_key_id": "key_123",
    "merchant_id": "mer_123",
    "name": "Sandbox orders integration",
    "sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "key_prefix": "flint_test_abcd1234",
    "scopes": [
      "accounts.api_keys.read",
      "accounts.api_keys.write",
      "commerce.orders.read",
      "commerce.orders.write"
    ],
    "key_type": "external",
    "status": "active",
    "last_used_at": "2026-03-17T15:00:00Z",
    "expires_at": "2027-03-17T14:30:00Z",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "secret_key": "flint_test_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Start onboarding flow#

POST/v1/onboarding/startIdempotentNo API key required

Starts the consolidated onboarding flow by emailing a short-lived verification code and returning a temporary verification token.

Request body
emailstringrequired
first_namestringrequired
last_namestringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

INVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "email": "owner@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }'
JSON
{
  "data": {
    "verification_started": true,
    "verification_token": "devver_v1.c2FtcGxlLXZlcmlmaWNhdGlvbi10b2tlbg",
    "expires_at": "2026-03-18T20:00:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get onboarding state#

GET/v1/onboarding/stateRequires scope: merchants.onboarding.read or merchants.onboarding.write

Returns the consolidated onboarding state machine, including the primary next step for agents or humans. This endpoint is read-only.

Query parameters
sandbox_idstring

Optional sandbox to bind when evaluating test-mode onboarding.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/onboarding/state \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "merchant_id": "mer_123",
    "merchant_created": true,
    "email_verified": true,
    "default_sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "can_issue_api_key": true,
    "status": "needs_external_action",
    "next_step": {
      "code": "complete_verification_step",
      "owner": "human",
      "machine_completable": false,
      "launch": {
        "method": "POST",
        "endpoint": "/v1/merchant-account-sessions",
        "component": "account_onboarding",
        "recommended_policy": {
          "collection_strategy": "upfront",
          "future_requirements": "include"
        },
        "sandbox_id": "test_01JQEXAMPLEDEFAULT12345678"
      }
    },
    "country": "US",
    "requested_capabilities": [
      "accept_card_payments",
      "receive_payouts"
    ],
    "profile": {
      "email": "owner@example.com",
      "support_email": "help@example.com",
      "support_phone": "+14155552671",
      "support_url": "https://example.com/support",
      "website_url": "https://withflintpay.com"
    },
    "requirements": {
      "currently_due": [
        "merchant_category_code",
        "business_website"
      ],
      "eventually_due": [
        "representative_first_name"
      ],
      "current_deadline_at": "2026-04-01T00:00:00Z"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Verify onboarding email#

POST/v1/onboarding/verify-emailIdempotentNo API key required

Verifies the emailed code, provisions the Flint user and merchant if needed, and returns a short-lived session token for the rest of onboarding.

Request body
merchant_idstring
verification_codestringrequired
verification_tokenstringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/verify-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "verification_token": "devver_v1.c2FtcGxlLXZlcmlmaWNhdGlvbi10b2tlbg",
    "verification_code": "482193"
  }'
JSON
{
  "data": {
    "onboarding_session_token": "devsess_v1.c2FtcGxlLWRldmVsb3Blci1zZXNzaW9uLXRva2Vu",
    "user": {
      "user_id": "usr_123",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "owner@example.com",
      "status": "active",
      "default_merchant_id": "mer_123",
      "created_at": "2026-03-18T19:45:00Z",
      "updated_at": "2026-03-18T19:45:00Z"
    },
    "merchant": {
      "merchant_id": "mer_123",
      "email": "owner@example.com",
      "onboarding_status": "completed",
      "status": "active",
      "metadata": {
        "segment": "events"
      },
      "logo": {
        "url": "https://images.withflintpay.com/ia_merchant_logo/original",
        "alt": "Merchant logo",
        "width": 512,
        "height": 512
      },
      "image_revision": 1,
      "phone": "+14155552671",
      "address": {
        "line1": "123 Main St",
        "country": "US",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001"
      },
      "banners": [
        {
          "message": "Your account is ready to accept payments.",
          "style": "success"
        }
      ],
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z",
      "business_name": "Flint Events LLC",
      "has_past_due": false,
      "business_type": "company",
      "support_email": "support@example.com",
      "support_phone": "+14155552671",
      "support_url": "https://example.com/support",
      "website_url": "https://withflintpay.com"
    },
    "default_sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "status": "merchant_ready",
    "merchant_created": true,
    "can_issue_api_key": true,
    "next_step": {
      "code": "check_onboarding_state",
      "owner": "agent",
      "machine_completable": true,
      "submit_endpoint": "/v1/onboarding/state",
      "submit_method": "GET"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc