Skip to content

Merchant signups

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. POST /v1/merchant-signups returns 409 ACTION_NOT_ALLOWED with reason not_offered and remediation.retry: none while signups are disabled. Retrying cannot enable signups. The signup flow below describes the API for when merchant signups are enabled.

A merchant signup is your platform's request to create a Flint merchant for a business owner. Flint emails the owner a code that names your app, the business, the permissions and platform fee cap you request, and Flint's merchant terms. The owner types the code into your form and ticks Flint's terms checkbox there. You send both to verify, and Flint creates the merchant, installs your app on it, and returns authorization codes you exchange for partner app tokens bound to the new merchant.

The owner never needs a Flint login to finish, and Flint never tells you whether their email already had one. They can sign in to Flint with the same email at any time.

Build payments into your platform follows one studio from signup to payout.

Merchant signups are live-mode resources of your partner app's owning merchant. Every route needs a live credential of that merchant: a live API key, a live workload identity, or a live dashboard session.

  • A test credential gets 403 FORBIDDEN with reason live_mode_required.
  • A key linked to a partner app install (partner_app_install_id set) gets 403 FORBIDDEN with reason linked_key_not_allowed.
  • Partner app tokens can't call these routes.

Reading signups requires developer.merchant_signups.read or developer.merchant_signups.write. Every other route requires developer.merchant_signups.write. These scopes are separate from developer.partner_apps.*, so the service that signs up merchants can't change your app's manifest, fee cap, or client credentials.

Before you start#

  • Set your partner app's merchant_action_url. Signups need it, and it requests the create_merchants platform capability.
  • Live signups, and signups for owners outside your team, need create_merchants to be active in platform.capabilities. Until Flint approves it, you can create test-only signups for your own team's addresses, plus-addresses included, such as you+studio3@yourcompany.example.
  • Keep a PKCE verifier for each signup. The authorization codes verify returns are bound to its challenge.

For this signup rule, your team's addresses are the verified Flint sign-in emails of active members of your app's owning merchant, including members with inherited organization access. Each member must verify their sign-in email before you can use it for a test signup. Plus-addresses of those emails count too. Setting the merchant's account email, support_email, or the platform profile's support email does not verify an address or add it to your team. A support address counts only when it is also an active team member's verified sign-in email. The sandbox buyer-email allowance has its own rules.

Create a merchant signup#

cURL
curl -X POST https://api.withflintpay.com/v1/merchant-signups \
  -H "Authorization: Bearer flint_live_YOUR_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"],
    "sandbox_initial_onboarding": "not_started",
    "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "code_challenge_method": "S256",
    "external_reference_id": "studio_8812"
  }'

POST /v1/merchant-signups returns 201 with a MerchantSignup in status pending, and Flint emails the owner a code that works for 15 minutes.

FieldRule
owner.emailThe owner's address, at most 254 characters. It becomes the merchant's account email and the owner's Flint login. Never use addresses on a domain you control
owner.first_name, owner.last_name1 to 100 characters each. They become the Flint user's name when Flint creates the user
business_nameOptional, 1 to 100 characters. The merchant's display name until onboarding sets its legal name. Without it, Flint names the merchant from the owner's email
modestest, live, or both. One environment grant per mode. live needs create_merchants
requested_permission_idsOptional permissions to request besides the required ones. Defaults to the app's default_requested_permissions; send [] for only the required permissions
timezoneOptional IANA business time zone, such as America/Chicago. Sets the new merchant's time zone for reports and business dates. If omitted, the first live location or a merchant update can set it. Blank or invalid values return 400 INVALID_REQUEST
sandbox_initial_onboardingcomplete (default) or not_started, as initial_onboarding on sandbox create. It sets the new merchant's default sandbox, which the test grant points at
code_challenge, code_challenge_methodRequired. S256 only: 43 base64url characters
external_reference_idOptional, 1 to 255 characters. Your record for this business

Text you send that Flint's email shows (the business and owner names) can't contain a link, a host name, or an email address, such as tidewater.yoga: 400 INVALID_REQUEST with INVALID_VALUE at that field. Your app's name and permission titles follow the same rule when you save the app.

Flint checks, in order and before it sends any email:

  1. The partner app is yours and active. Otherwise 404 RESOURCE_NOT_FOUND at partner_app_id, or 409 ACTION_NOT_ALLOWED with reason unsupported_state for a deleted app.
  2. Every requested_permission_ids value is in the app's manifest. Otherwise 400 INVALID_REQUEST with INVALID_VALUE at that item.
  3. The app has a merchant_action_url, and its name and permission titles hold no link. Otherwise 409 ACTION_NOT_ALLOWED with reason configuration_required and resource_type: partner_app.
  4. The app's live create_merchants capability. While it isn't active, a signup whose modes include live gets 409 ACTION_NOT_ALLOWED with capability: create_merchants, param: modes, and the capability's inactive reason. A test-only signup for an owner without a verified team sign-in email is refused the same way with param: owner.email, before any signup or email is created. Sending another code checks team membership and verification again.
  5. The quotas below.
LimitValueResponse
Signups per app per UTC day20 before create_merchants is active; 1,000 after, or the limit Flint set for your platform409 LIMIT_REACHED, reason merchant_signups, with limit and resets_at
Codes per owner mailbox, across every app3 per 15 minutes; 10 per 24 hours429 RATE_LIMIT_EXCEEDED with Retry-After; 409 LIMIT_REACHED, reason verification_codes, with limit and resets_at
Codes per signup3409 LIMIT_REACHED, reason verification_codes, with limit

Plus-addresses count as their mailbox: maya+1@ and maya+2@ share the limits of maya@.

The code email#

Flint sends the email from Flint Pay, and you can't change it. It names your app and, once Flint has reviewed your platform, the website host Flint reviewed, so the owner can tell your app from a look-alike. It lists the business name, the title of each permission you requested, your platform fee cap, and Flint's merchant terms, and says that entering the code creates the owner's Flint account and connects your app in the modes you chose. When your app declares payment_splits, the email also asks the owner to approve receiving split funds and links your seller terms, frozen as they were when you created the signup.

The code is 8 characters in two groups of four, such as K7QM-4TXD. The email tells the owner that an app only ever asks for a code like this one, and never for a 6-digit Flint sign-in code.

Verify the signup#

In your form, show Flint's merchant terms checkbox, linked to merchant_terms.url, beside the code field. When the owner submits it:

cURL
curl -X POST https://api.withflintpay.com/v1/merchant-signups/msu_01KF3A7D2Q8W4E6R0T2Y4U6I8O/verify \
  -H "Authorization: Bearer flint_live_YOUR_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
  }'
  • verification_code is accepted with or without the hyphen, in either case.
  • terms_acceptance states that the owner ticked the checkbox, with the owner's browser IP address (IPv4 or IPv6) and user agent (1 to 1,024 characters). merchant_terms_version must equal the signup's merchant_terms.version. Flint's platform terms oblige you to show the checkbox and report real values. Request logs redact the code, the IP address, and the user agent.

Flint checks, in order and before any effect:

  1. The signup is pending. A completed signup returns 409 ACTION_NOT_ALLOWED with reason already_applied; any other status returns reason unsupported_state with current_status.
  2. The create_merchants check from create, again, so a platform Flint paused after create is refused and the code keeps working.
  3. The attempt caps: 5 wrong codes use up a code, and wrong codes for one owner mailbox are capped at 10 per 24 hours and 30 per 7 days. They return 409 LIMIT_REACHED with reason verification_attempts, with limit and, for the mailbox caps, resets_at. Flint checks them before the code, so once tries run out, a right code is refused too.
  4. The code. A wrong, expired, or replaced code returns 400 INVALID_REQUEST with INVALID_VALUE at verification_code, the same answer for each.

After the code matches, Flint resolves the owner:

The email belongs toResult
No Flint userFlint creates the owner's login, with this email verified
A Flint user whose email is verifiedThe new merchant is added to their login. Their other merchants aren't touched or shared
A login Flint can't use for this, such as one whose email was never verified409 ACTION_NOT_ALLOWED with reason owner_identity_conflict. The owner contacts Flint support. Afterwards, resend a code within expires_at or start a new signup
An owner who already owns 10 active merchants409 LIMIT_REACHED with reason owned_merchants and limit. The owner must archive one

Flint then creates a new merchant, always a new one, sets up its environments and default sandbox, installs your app with the permissions the email listed (narrowed to what your manifest still offers) and the fee cap it showed (lowered to your current cap), and records the owner's acceptance of the terms. The response is 200 with a MerchantSignupWithAuthorizationCodes: the completed signup, test_authorization_code and live_authorization_code for the modes it installed, and authorization_codes_expire_at.

When verify fails partway#

Once the code is used, Flint finishes creating the merchant even if your request fails, and the signup keeps reading pending with supported_actions: ["verify"] until it's done. A failure returns 503 SERVICE_UNAVAILABLE. Send verify again with the same code, with the same Idempotency-Key or a new one, to wait for or continue the same completion and get its result. Flint doesn't apply the platform check or the attempt caps to these retries.

An idempotent replay returns the signup without the codes. To get codes again, call rotate-authorization-codes.

Exchange the authorization codes#

Exchange each code at the token endpoint with your app's client credential and the PKCE verifier, and without redirect_uri, within 5 minutes:

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"

A signup code sent with a redirect_uri returns invalid_grant. Otherwise the exchange works as for a consent-screen code: it returns a partner app token bound to the new merchant and the code's mode, and afterwards you mint the merchant's tokens with grant_type=client_credentials. The first exchange sends partner_app_install.created and environment_grant.created; the second sends partner_app_install.updated and environment_grant.created. A code works once: exchanging it a second time returns invalid_grant and revokes the token the first exchange returned.

Mint new authorization codes#

POST /v1/merchant-signups/{merchant_signup_id}/rotate-authorization-codes mints new codes for grants this signup created that were never exchanged, bound to the signup's challenge, and supersedes the earlier ones. Use it when the verify response was lost or the codes expired. It takes an optional body with only expected_version.

It works within 24 hours of completed_at while nothing else has happened to the install. Any revoke, or an authorization of your app on the consent screen, ends it for good. It returns 409 ACTION_NOT_ALLOWED with:

  • already_applied once every grant has been exchanged. Mint partner app tokens for the merchant with grant_type=client_credentials instead.
  • unsupported_state when the signup isn't completed.
  • not_offered once the 24 hours or the install's state ends rotation. The owner then reauthorizes your app on the consent screen.

Resend or cancel#

POST /v1/merchant-signups/{merchant_signup_id}/resend-code emails a new code for a pending signup. The new code replaces the old one and resets its attempt count, and an email still queued for the old code is never sent. A signup sends at most 3 codes. The create_merchants check and the per-mailbox limits apply again.

POST /v1/merchant-signups/{merchant_signup_id}/cancel cancels a pending signup and voids its code. Canceling again returns 409 ACTION_NOT_ALLOWED with reason already_applied.

Both take an optional body with only expected_version, and any other status returns 409 ACTION_NOT_ALLOWED with reason unsupported_state.

Read merchant signups#

cURL
curl "https://api.withflintpay.com/v1/merchant-signups?partner_app_id=papp_01KEZF7C00D8DXK5AXR7NPRJ0J&status=pending" \
  -H "Authorization: Bearer flint_live_YOUR_SIGNUP_KEY"

GET /v1/merchant-signups lists your apps' signups, newest first, then by merchant_signup_id. Filter by partner_app_id, external_reference_id, owner_email (compared in lower case), one or more status values, created_after (inclusive), and created_before (exclusive). A merchant that owns no app gets an empty list. GET /v1/merchant-signups/{merchant_signup_id} returns one. A signup of another merchant's app returns 404 RESOURCE_NOT_FOUND, the same as an unknown ID.

StatusMeaning
pendingA code was sent and not yet verified, or Flint is completing the signup after verify
completedFlint created the merchant and installed your app. merchant_id, partner_app_install_id, terms_acceptance and completed_at are set
expiredNot verified within 24 hours, by expires_at. Expiry follows from the time, so it doesn't change version, and no event is sent
canceledCanceled while pending

completed, expired and canceled are final. supported_actions lists verify and cancel while pending, and only verify while Flint is completing it. There are no merchant_signup webhook events: every change follows one of your requests, except expiry, which expires_at predicts. You learn about the merchant's progress through the install's forwarded events, such as merchant.readiness_updated.

A completed signup is the record of the owner's consent and is kept for as long as the merchant exists, including after a disconnect. Pending, expired and canceled signups are deleted 30 days after they end.

After the signup#

The install carries merchant_signup_id, and the installing merchant sees it too. The install's live token runs the merchant's onboarding once your app's merchant_onboarding capability is active, and its test token runs it in test mode. Mount account_onboarding in your own page with a merchant account session, or send the owner to Flint's hosted page with an onboarding access link. Live payments start when readiness.payments.status is ready, and Flint sends merchant.readiness_updated to your installed-merchant endpoint when readiness changes.

The owner keeps a Flint login without using it. It exists from the moment the signup completes, with the email they confirmed, and they can use it any time by signing in to Flint with an emailed code. Your install can't change that email.

While the install manages the merchant, Flint's emails that ask the owner to finish verification lead to your merchant_action_url, and the processor's notification link does too. Emails that lead to your app lists the parameters Flint adds, and the emails that still lead to Flint's sign-in, so the owner needs their Flint login for them. Flint's merchant emails to the owner name your app and offer sign-in to Flint.

If the owner does sign 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, and Settings > Connected apps lists your app's install as created through its signup.

When the install is revoked for the first time, by anyone, emails go back to Flint for good, and Flint tells the owner once that they can sign in to Flint to manage their account. Revoking ends everything your install received. The signup issued no API key, CLI login, or onboarding session, so no credential of the merchant's stays with you. Account sessions and onboarding access links your install opened stop working at their next refresh. A component already mounted in the owner's browser can keep working until the payment processor's session for it expires. Payouts continue on their schedule. Reconnecting through the consent screen doesn't bring email routing back, and a new signup creates another merchant.

The Merchant signup object#

A platform's request to create a merchant for an owner, who confirms it with a code Flint emails them. Once verified, it is the record of the owner's consent, kept for as long as the merchant exists.

Returned by GET /v1/merchant-signups/{merchant_signup_id} and carried by the endpoints below.

Attributes

business_namestring

The new merchant's display name until onboarding sets its legal name. Absent when the request didn't send one: Flint then names the merchant from the owner's email.

canceled_atstring

When the signup was canceled.

code_expires_atstring

When the current code expires, present while the signup is `pending` and its code still works.

completed_atstring

When the signup completed.

created_atstringRequired

When the signup was created.

expires_atstringRequired

When a `pending` signup expires: 24 hours after it was created. A signup Flint is completing never expires.

external_reference_idstring

Your identifier for this business, as you sent it. Absent when you didn't send one.

merchant_idstring

The merchant the signup created, present once it is `completed`.

merchant_signup_idstringRequired

Unique identifier for the merchant signup.

merchant_termsobjectRequired

Flint's merchant terms the owner must accept.

modesarray of enumRequired

The modes the signup installs the app in, one environment grant each, `test` first.

  • test
  • live
ownerobjectRequired

The owner the code went to.

partner_app_idstringRequired

The partner app the signup installs on the new merchant.

partner_app_install_idstring

The install the signup created, present once it is `completed`. Its `merchant_signup_id` names this signup.

platform_fee_capobject

The app's platform fee cap the code email showed, frozen at create. Absent when the app has none.

requested_permissionsarray of objectRequired

The permissions the code email asked the owner to approve, frozen at create: the requested ones, or the app's defaults, plus every required permission, in manifest order. At verify, each grant gets them narrowed to what the app's manifest still offers.

sandbox_initial_onboardingenumRequired

The onboarding state of the new merchant's default sandbox, which the test grant points at.

  • complete
  • not_started
statusenumRequired

Where the signup is. `completed`, `expired` and `canceled` are final. `expired` follows from `expires_at`, so it doesn't advance `version`.

  • pending
  • completed
  • expired
  • canceled
supported_actionsarray of enumRequired

Lifecycle actions Flint accepts now: `verify` and `cancel` while `pending`, only `verify` while Flint is completing it after verify, `[]` otherwise. resend-code and rotate-authorization-codes are operations, not lifecycle actions, so they are never listed.

  • cancel
  • verify
terms_acceptanceobject

The owner's acceptance, present once the signup is `completed`.

timezonestring

Business time zone set on the new merchant. Absent when signup did not include one. Uses an IANA time zone name.

updated_atstringRequired

When the signup last changed.

versionintegerRequired

Persisted version of this resource's owned state. Expanded resources and external observations can change independently.

JSON
{
  "business_name": "Tidewater Yoga",
  "completed_at": "2026-11-12T18:02:11Z",
  "created_at": "2026-11-12T17:58:40Z",
  "expires_at": "2026-11-13T17:58:40Z",
  "external_reference_id": "studio_8812",
  "merchant_id": "mer_01KEZF7C00ZP3MCWG5NY2AFAP3",
  "merchant_signup_id": "msu_01KEZF7C00X5R105NFF6R983T5",
  "merchant_terms": {
    "url": "https://withflintpay.com/legal/terms",
    "version": "2026-10-01"
  },
  "modes": [
    "test",
    "live"
  ],
  "owner": {
    "email": "maya@tidewateryoga.example",
    "first_name": "Maya",
    "last_name": "Okafor"
  },
  "partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
  "partner_app_install_id": "pinst_01KEZF7C00WNK3HP83YWT71FYT",
  "platform_fee_cap": {
    "maximum_fee_currency_options": {
      "USD": {
        "amount": 500,
        "currency": "USD"
      }
    },
    "percent": 2.5
  },
  "requested_permissions": [
    {
      "description": "Run verification and bank account setup for your studio.",
      "permission_id": "setup_payments",
      "required_scopes": [
        "merchants.onboarding.read",
        "merchants.onboarding.write",
        "merchants.account_sessions.write"
      ],
      "title": "Set up payments"
    },
    {
      "description": "Create orders, checkouts and refunds.",
      "permission_id": "sell",
      "required_scopes": [
        "commerce.orders.write",
        "checkouts.checkout_sessions.write",
        "commerce.refunds.write"
      ],
      "title": "Sell classes"
    }
  ],
  "sandbox_initial_onboarding": "not_started",
  "status": "completed",
  "supported_actions": [],
  "terms_acceptance": {
    "accepted_at": "2026-11-12T18:02:11Z",
    "merchant_terms_version": "2026-10-01"
  },
  "updated_at": "2026-11-12T18:02:11Z",
  "version": 3
}

List merchant signups#

GET/v1/merchant-signups

Requires scope developer.merchant_signups.read or developer.merchant_signups.write

Rate limit: read

Lists the signups of your partner apps, newest first, then by `merchant_signup_id`. A merchant that owns no app gets an empty list. Live only: test credentials get 403 FORBIDDEN with reason live_mode_required, and a key linked to a partner app install gets 403 FORBIDDEN with reason linked_key_not_allowed. Partner app tokens can't call it. Default order: created_at descending, then merchant_signup_id descending.

Query parameters

partner_app_idstring

Return signups of this partner app.

external_reference_idstring

Return signups with this external_reference_id.

owner_emailstring

Return signups for this owner email, compared in lower case.

statusarray of enum

Return signups with any of these statuses. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • pending
  • completed
  • expired
  • canceled
created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.

Response · 200

A page of merchant signups.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl https://api.withflintpay.com/v1/merchant-signups \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

A page of merchant signups.

JSON
{
  "data": [
    {
      "business_name": "Tidewater Yoga",
      "completed_at": "2026-11-12T18:02:11Z",
      "created_at": "2026-11-12T17:58:40Z",
      "expires_at": "2026-11-13T17:58:40Z",
      "external_reference_id": "studio_8812",
      "merchant_id": "mer_01KEZF7C00ZP3MCWG5NY2AFAP3",
      "merchant_signup_id": "msu_01KEZF7C00X5R105NFF6R983T5",
      "merchant_terms": {
        "url": "https://withflintpay.com/legal/terms",
        "version": "2026-10-01"
      },
      "modes": [
        "test",
        "live"
      ],
      "owner": {
        "email": "maya@tidewateryoga.example",
        "first_name": "Maya",
        "last_name": "Okafor"
      },
      "partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
      "partner_app_install_id": "pinst_01KEZF7C00WNK3HP83YWT71FYT",
      "platform_fee_cap": {
        "maximum_fee_currency_options": {
          "USD": {
            "amount": 500,
            "currency": "USD"
          }
        },
        "percent": 2.5
      },
      "requested_permissions": [
        {
          "description": "Run verification and bank account setup for your studio.",
          "permission_id": "setup_payments",
          "required_scopes": [
            "merchants.onboarding.read",
            "merchants.onboarding.write",
            "merchants.account_sessions.write"
          ],
          "title": "Set up payments"
        },
        {
          "description": "Create orders, checkouts and refunds.",
          "permission_id": "sell",
          "required_scopes": [
            "commerce.orders.write",
            "checkouts.checkout_sessions.write",
            "commerce.refunds.write"
          ],
          "title": "Sell classes"
        }
      ],
      "sandbox_initial_onboarding": "not_started",
      "status": "completed",
      "supported_actions": [],
      "terms_acceptance": {
        "accepted_at": "2026-11-12T18:02:11Z",
        "merchant_terms_version": "2026-10-01"
      },
      "updated_at": "2026-11-12T18:02:11Z",
      "version": 3
    }
  ],
  "meta": {
    "api_version": "2026-09-07"
  },
  "next_page_token": "opaque-next-page-token",
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Create a merchant signup#

POST/v1/merchant-signupsIdempotent

Requires scope developer.merchant_signups.write

Rate limit: write

Merchant signups are not available yet. While disabled, this endpoint returns 409 ACTION_NOT_ALLOWED with reason not_offered and retry none. Have the owner create a Flint account through onboarding or flint signup, then install your app through the consent screen. The following describes the flow when enabled. Starts creating a merchant for an owner: Flint emails the owner a code that names your app, the business, the permissions and fee cap you request, and Flint's merchant terms. Show the owner Flint's terms checkbox in your form, collect the code, and send both to verify. Flint checks, in order and before any email: the partner app is yours and active (404 RESOURCE_NOT_FOUND at partner_app_id, or 409 ACTION_NOT_ALLOWED with reason unsupported_state for a deleted app); every requested_permission_ids value is in the manifest (400 INVALID_VALUE at that item); the app has a merchant_action_url, and its name and permission titles hold no link (409 ACTION_NOT_ALLOWED with reason configuration_required); the app's live create_merchants capability; then the quotas. Until create_merchants is active, modes including live are refused with 409 ACTION_NOT_ALLOWED, capability create_merchants, param modes and the capability's inactive reason, and an owner outside your merchant's team is refused the same way with param owner.email. Quotas: 20 signups per app per UTC day before create_merchants is active and 1,000 after (409 LIMIT_REACHED with reason merchant_signups, limit and resets_at); 3 codes per owner mailbox per 15 minutes across every app (429 RATE_LIMIT_EXCEEDED with Retry-After) and 10 per 24 hours (409 LIMIT_REACHED with reason verification_codes). Plus-addresses count as their mailbox. The response never says whether the email already has a Flint login. Live only: test credentials get 403 FORBIDDEN with reason live_mode_required, and a key linked to a partner app install gets 403 FORBIDDEN with reason linked_key_not_allowed. Partner app tokens can't call it.

Request body

business_namestring

The new merchant's display name until onboarding sets its legal name, 1 to 100 characters, without links or email addresses: the code email shows it. Without it, Flint names the merchant from the owner's email.

code_challengestringRequired

The PKCE S256 challenge: base64url SHA-256 of a verifier you keep. The authorization codes verify returns are bound to it.

code_challenge_methodenumRequired

Must be `S256`.

  • S256
external_reference_idstring

Your identifier for this business, such as your account ID. List signups by it.

modesarray of enumRequired

The modes to install the app in. `live` needs the app's live `create_merchants` capability. Until it is active, a signup may install only in `test`, and only for an owner on your merchant's team (plus-addresses included).

  • test
  • live
ownerobjectRequired

The owner Flint emails the code to.

partner_app_idstringRequired

Your partner app to install on the new merchant. It must be active and have a `merchant_action_url`.

requested_permission_idsarray of string

Optional manifest permissions to request besides the required ones. Defaults to the app's `default_requested_permissions`. Send `[]` to request only the required permissions.

sandbox_initial_onboardingenum

The onboarding state of the new merchant's default sandbox, which the test grant points at. Send `not_started` to rehearse verification in test mode.

  • complete
  • not_started
timezonestring

IANA business time zone for the new merchant, such as America/Chicago. Used for reports and business dates. Omit to leave it unset until a live location or a merchant update sets it.

Response · 201

The merchant signup.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/merchant-signups \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "business_name": "Tidewater Yoga",
    "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
    "code_challenge_method": "S256",
    "external_reference_id": "studio_8812",
    "modes": [
      "test",
      "live"
    ],
    "owner": {
      "email": "maya@tidewateryoga.example",
      "first_name": "Maya",
      "last_name": "Okafor"
    },
    "partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
    "requested_permission_ids": [
      "setup_payments",
      "sell"
    ],
    "sandbox_initial_onboarding": "not_started"
  }'

Get a merchant signup#

GET/v1/merchant-signups/{merchant_signup_id}

Requires scope developer.merchant_signups.read or developer.merchant_signups.write

Rate limit: read

Returns one of your partner apps' signups. A completed signup stays readable, including the owner's name and email, after the merchant disconnects the app. Live only: test credentials get 403 FORBIDDEN with reason live_mode_required, and a key linked to a partner app install gets 403 FORBIDDEN with reason linked_key_not_allowed. Partner app tokens can't call it.

Path parameters

merchant_signup_idstringRequired

ID of the merchant signup. Must be a valid ID with prefix msu_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Response · 200

The merchant signup.

Same response as Create a merchant signup.

curl https://api.withflintpay.com/v1/merchant-signups/msu_01KEZF7C00SRGYRMBPKRKW8V9J \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The merchant signup.

JSON
{
  "data": {
    "business_name": "Tidewater Yoga",
    "completed_at": "2026-11-12T18:02:11Z",
    "created_at": "2026-11-12T17:58:40Z",
    "expires_at": "2026-11-13T17:58:40Z",
    "external_reference_id": "studio_8812",
    "merchant_id": "mer_01KEZF7C00ZP3MCWG5NY2AFAP3",
    "merchant_signup_id": "msu_01KEZF7C00X5R105NFF6R983T5",
    "merchant_terms": {
      "url": "https://withflintpay.com/legal/terms",
      "version": "2026-10-01"
    },
    "modes": [
      "test",
      "live"
    ],
    "owner": {
      "email": "maya@tidewateryoga.example",
      "first_name": "Maya",
      "last_name": "Okafor"
    },
    "partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
    "partner_app_install_id": "pinst_01KEZF7C00WNK3HP83YWT71FYT",
    "platform_fee_cap": {
      "maximum_fee_currency_options": {
        "USD": {
          "amount": 500,
          "currency": "USD"
        }
      },
      "percent": 2.5
    },
    "requested_permissions": [
      {
        "description": "Run verification and bank account setup for your studio.",
        "permission_id": "setup_payments",
        "required_scopes": [
          "merchants.onboarding.read",
          "merchants.onboarding.write",
          "merchants.account_sessions.write"
        ],
        "title": "Set up payments"
      },
      {
        "description": "Create orders, checkouts and refunds.",
        "permission_id": "sell",
        "required_scopes": [
          "commerce.orders.write",
          "checkouts.checkout_sessions.write",
          "commerce.refunds.write"
        ],
        "title": "Sell classes"
      }
    ],
    "sandbox_initial_onboarding": "not_started",
    "status": "completed",
    "supported_actions": [],
    "terms_acceptance": {
      "accepted_at": "2026-11-12T18:02:11Z",
      "merchant_terms_version": "2026-10-01"
    },
    "updated_at": "2026-11-12T18:02:11Z",
    "version": 3
  },
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Cancel a merchant signup#

POST/v1/merchant-signups/{merchant_signup_id}/cancelIdempotent

Requires scope developer.merchant_signups.write

Rate limit: write

Cancels a `pending` signup and voids its code, so a code email still queued is never sent. A canceled signup returns 409 ACTION_NOT_ALLOWED with reason already_applied; any other status, including a signup Flint is completing after verify, returns reason unsupported_state with current_status. Live only: test credentials get 403 FORBIDDEN with reason live_mode_required, and a key linked to a partner app install gets 403 FORBIDDEN with reason linked_key_not_allowed. Partner app tokens can't call it.

Path parameters

merchant_signup_idstringRequired

ID of the merchant signup. Must be a valid ID with prefix msu_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

Optional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.

Response · 200

The merchant signup.

Same response as Create a merchant signup.

curl -X POST https://api.withflintpay.com/v1/merchant-signups/msu_01KEZF7C00SRGYRMBPKRKW8V9J/cancel \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 1
  }'

Send a new merchant signup code#

POST/v1/merchant-signups/{merchant_signup_id}/resend-codeIdempotent

Requires scope developer.merchant_signups.write

Rate limit: write

Emails the owner a new code for a `pending` signup. The new code replaces the old one and resets the attempt count; a code email still queued for the old code is never sent. A signup sends at most 3 codes (409 LIMIT_REACHED with reason verification_codes and limit 3), within the per-mailbox send caps of create. The app's create_merchants capability is checked again, so a paused platform sends no more codes. Any other status returns 409 ACTION_NOT_ALLOWED with reason unsupported_state. It is a message operation, not a lifecycle action, so supported_actions never lists it. Live only: test credentials get 403 FORBIDDEN with reason live_mode_required, and a key linked to a partner app install gets 403 FORBIDDEN with reason linked_key_not_allowed. Partner app tokens can't call it.

Path parameters

merchant_signup_idstringRequired

ID of the merchant signup. Must be a valid ID with prefix msu_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

Optional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.

Response · 200

The merchant signup.

Same response as Create a merchant signup.

curl -X POST https://api.withflintpay.com/v1/merchant-signups/msu_01KEZF7C00SRGYRMBPKRKW8V9J/resend-code \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 1
  }'

Mint new authorization codes for a merchant signup#

POST/v1/merchant-signups/{merchant_signup_id}/rotate-authorization-codesIdempotent

Requires scope developer.merchant_signups.write

Rate limit: sensitive_write

Mints new authorization codes for a completed signup's grants that were never exchanged, bound to the signup's code_challenge, and supersedes the earlier ones. Use it when the verify response was lost or the codes expired before you exchanged them. It works only within 24 hours of completed_at and while nothing else has happened to the install: any revoke, or an authorization of the app on the consent screen, ends it for good. Refused with 409 ACTION_NOT_ALLOWED: reason already_applied once every grant has been exchanged (mint partner app tokens with grant_type=client_credentials instead), unsupported_state when the signup isn't completed, and not_offered once the window or the install's state ends rotation; the owner then reauthorizes on the consent screen. An idempotent replay returns the signup without the codes. It is a code rotation, not a lifecycle action, so supported_actions never lists it. Live only: test credentials get 403 FORBIDDEN with reason live_mode_required, and a key linked to a partner app install gets 403 FORBIDDEN with reason linked_key_not_allowed. Partner app tokens can't call it.

Path parameters

merchant_signup_idstringRequired

ID of the merchant signup. Must be a valid ID with prefix msu_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

Optional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.

Response · 200

The completed merchant signup with its authorization codes.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/merchant-signups/msu_01KEZF7C00SRGYRMBPKRKW8V9J/rotate-authorization-codes \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 3
  }'

Verify a merchant signup#

POST/v1/merchant-signups/{merchant_signup_id}/verifyIdempotent

Requires scope developer.merchant_signups.write

Rate limit: sensitive_write

Uses the owner's code and their acceptance of Flint's merchant terms, then creates the merchant, installs the app on it in the signup's modes, and returns one authorization code per mode. Exchange each at POST /v1/oauth/token with the code_verifier for the signup's code_challenge and without redirect_uri, within 5 minutes. Checks, in order, before any effect: the signup is pending (409 ACTION_NOT_ALLOWED with reason already_applied when completed, unsupported_state with current_status otherwise); the app's create_merchants capability again; the attempt caps (409 LIMIT_REACHED with reason verification_attempts: 5 wrong codes use up a code, and wrong codes for one owner mailbox are capped at 10 per 24 hours and 30 per 7 days, with resets_at); the code. A wrong, expired or replaced code is 400 INVALID_REQUEST with INVALID_VALUE at verification_code. After the code matches, an owner Flint can't use is refused with 409 ACTION_NOT_ALLOWED and reason owner_identity_conflict (the owner contacts Flint support, then you resend a code or start a new signup), and an owner who already owns 10 active merchants with 409 LIMIT_REACHED and reason owned_merchants. Completion is resumable. Once the code is used, Flint finishes creating the merchant even if this request fails; a failure returns 503 SERVICE_UNAVAILABLE. Send verify again, with the same Idempotency-Key or a new one and the same code, to wait for or continue the same completion and get the result. An idempotent replay returns the signup without the codes: mint new ones with rotate-authorization-codes. Live only: test credentials get 403 FORBIDDEN with reason live_mode_required, and a key linked to a partner app install gets 403 FORBIDDEN with reason linked_key_not_allowed. Partner app tokens can't call it.

Path parameters

merchant_signup_idstringRequired

ID of the merchant signup. Must be a valid ID with prefix msu_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

Optional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.

terms_acceptanceobjectRequired

The owner's acceptance of Flint's merchant terms.

verification_codestringRequired

The 8-character code Flint emailed the owner, such as `K7QM-4TXD`, with or without the hyphen, in either case. Request logs redact it.

Response · 200

The completed merchant signup with its authorization codes.

Same response as Mint new authorization codes for a merchant signup.

curl -X POST https://api.withflintpay.com/v1/merchant-signups/msu_01KEZF7C00SRGYRMBPKRKW8V9J/verify \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 1,
    "terms_acceptance": {
      "ip_address": "203.0.113.7",
      "merchant_terms_version": "2026-10-01",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_1) AppleWebKit/605.1.15"
    },
    "verification_code": "K7QM-4TXD"
  }'

Was this helpful?