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 FORBIDDENwith reasonlive_mode_required. - A key linked to a partner app install (
partner_app_install_idset) gets403 FORBIDDENwith reasonlinked_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 thecreate_merchantsplatform capability. - Live signups, and signups for owners outside your team, need
create_merchantsto beactiveinplatform.capabilities. Until Flint approves it, you can create test-only signups for your own team's addresses, plus-addresses included, such asyou+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 -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.
| Field | Rule |
|---|---|
owner.email | The 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_name | 1 to 100 characters each. They become the Flint user's name when Flint creates the user |
business_name | Optional, 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 |
modes | test, live, or both. One environment grant per mode. live needs create_merchants |
requested_permission_ids | Optional permissions to request besides the required ones. Defaults to the app's default_requested_permissions; send [] for only the required permissions |
timezone | Optional 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_onboarding | complete (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_method | Required. S256 only: 43 base64url characters |
external_reference_id | Optional, 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:
- The partner app is yours and active. Otherwise
404 RESOURCE_NOT_FOUNDatpartner_app_id, or409 ACTION_NOT_ALLOWEDwith reasonunsupported_statefor a deleted app. - Every
requested_permission_idsvalue is in the app's manifest. Otherwise400 INVALID_REQUESTwithINVALID_VALUEat that item. - The app has a
merchant_action_url, and its name and permission titles hold no link. Otherwise409 ACTION_NOT_ALLOWEDwith reasonconfiguration_requiredandresource_type: partner_app. - The app's live
create_merchantscapability. While it isn'tactive, a signup whosemodesincludelivegets409 ACTION_NOT_ALLOWEDwithcapability: 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 withparam: owner.email, before any signup or email is created. Sending another code checks team membership and verification again. - The quotas below.
| Limit | Value | Response |
|---|---|---|
| Signups per app per UTC day | 20 before create_merchants is active; 1,000 after, or the limit Flint set for your platform | 409 LIMIT_REACHED, reason merchant_signups, with limit and resets_at |
| Codes per owner mailbox, across every app | 3 per 15 minutes; 10 per 24 hours | 429 RATE_LIMIT_EXCEEDED with Retry-After; 409 LIMIT_REACHED, reason verification_codes, with limit and resets_at |
| Codes per signup | 3 | 409 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 -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_codeis accepted with or without the hyphen, in either case.terms_acceptancestates 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_versionmust equal the signup'smerchant_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:
- The signup is
pending. A completed signup returns409 ACTION_NOT_ALLOWEDwith reasonalready_applied; any other status returns reasonunsupported_statewithcurrent_status. - The
create_merchantscheck from create, again, so a platform Flint paused after create is refused and the code keeps working. - 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_REACHEDwith reasonverification_attempts, withlimitand, for the mailbox caps,resets_at. Flint checks them before the code, so once tries run out, a right code is refused too. - The code. A wrong, expired, or replaced code returns
400 INVALID_REQUESTwithINVALID_VALUEatverification_code, the same answer for each.
After the code matches, Flint resolves the owner:
| The email belongs to | Result |
|---|---|
| No Flint user | Flint creates the owner's login, with this email verified |
| A Flint user whose email is verified | The 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 verified | 409 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 merchants | 409 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 -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_appliedonce every grant has been exchanged. Mint partner app tokens for the merchant withgrant_type=client_credentialsinstead.unsupported_statewhen the signup isn'tcompleted.not_offeredonce 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 "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.
| Status | Meaning |
|---|---|
pending | A code was sent and not yet verified, or Flint is completing the signup after verify |
completed | Flint created the merchant and installed your app. merchant_id, partner_app_install_id, terms_acceptance and completed_at are set |
expired | Not verified within 24 hours, by expires_at. Expiry follows from the time, so it doesn't change version, and no event is sent |
canceled | Canceled 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_namestringThe 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_atstringWhen the signup was canceled.
code_expires_atstringWhen the current code expires, present while the signup is `pending` and its code still works.
completed_atstringWhen the signup completed.
created_atstringRequiredWhen the signup was created.
expires_atstringRequiredWhen a `pending` signup expires: 24 hours after it was created. A signup Flint is completing never expires.
external_reference_idstringYour identifier for this business, as you sent it. Absent when you didn't send one.
merchant_idstringThe merchant the signup created, present once it is `completed`.
merchant_signup_idstringRequiredUnique identifier for the merchant signup.
merchant_termsobjectRequiredFlint's merchant terms the owner must accept.
urlstringRequiredWhere the terms are published. Link to it beside the checkbox in your form.
versionstringRequiredThe terms version. Send it as `terms_acceptance.merchant_terms_version` on verify.
modesarray of enumRequiredThe modes the signup installs the app in, one environment grant each, `test` first.
testlive
ownerobjectRequiredThe owner the code went to.
emailstringRequiredThe owner's email address, lowercased, at most 254 characters. Flint emails the code here, and it becomes the new merchant's account email and the owner's Flint login. Send an address the owner gave you, never one on a domain you control.
first_namestringRequiredThe owner's first name, 1 to 100 characters. It becomes the Flint user's first name when Flint creates the user.
last_namestringRequiredThe owner's last name, 1 to 100 characters. It becomes the Flint user's last name when Flint creates the user.
partner_app_idstringRequiredThe partner app the signup installs on the new merchant.
partner_app_install_idstringThe install the signup created, present once it is `completed`. Its `merchant_signup_id` names this signup.
platform_fee_capobjectThe app's platform fee cap the code email showed, frozen at create. Absent when the app has none.
fixed_fee_currency_optionsmap of objectThe fixed part of the cap per payment, keyed by currency code, added to the percentage part. Omitted when no currency has one. Only USD today.
maximum_fee_currency_optionsmap of objectRequiredThe maximum fee on one payment, keyed by currency code. Only USD today.
percentnumberRequiredThe percentage part of the cap, in percent: 2.5 means 2.5%. 0 when the cap is a fixed part alone.
requested_permissionsarray of objectRequiredThe 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.
descriptionstringRequiredThe permission's description.
permission_idstringRequiredThe manifest permission ID.
required_scopesarray of stringRequiredThe Flint scopes the permission grants.
titlestringRequiredThe permission's title, as the code email showed it.
sandbox_initial_onboardingenumRequiredThe onboarding state of the new merchant's default sandbox, which the test grant points at.
completenot_started
statusenumRequiredWhere the signup is. `completed`, `expired` and `canceled` are final. `expired` follows from `expires_at`, so it doesn't advance `version`.
pendingcompletedexpiredcanceled
supported_actionsarray of enumRequiredLifecycle 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.
cancelverify
terms_acceptanceobjectThe owner's acceptance, present once the signup is `completed`.
accepted_atstringRequiredWhen the owner accepted the terms.
merchant_terms_versionstringRequiredThe terms version accepted.
timezonestringBusiness time zone set on the new merchant. Absent when signup did not include one. Uses an IANA time zone name.
updated_atstringRequiredWhen the signup last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
{
"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#
/v1/merchant-signupsRequires 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_idstringReturn signups of this partner app.
external_reference_idstringReturn signups with this external_reference_id.
owner_emailstringReturn signups for this owner email, compared in lower case.
statusarray of enumReturn 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.
pendingcompletedexpiredcanceled
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, 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 objectRequiredResource, collection, or operation result returned by this request.
business_namestringThe 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_atstringWhen the signup was canceled.
code_expires_atstringWhen the current code expires, present while the signup is `pending` and its code still works.
completed_atstringWhen the signup completed.
created_atstringRequiredWhen the signup was created.
expires_atstringRequiredWhen a `pending` signup expires: 24 hours after it was created. A signup Flint is completing never expires.
external_reference_idstringYour identifier for this business, as you sent it. Absent when you didn't send one.
merchant_idstringThe merchant the signup created, present once it is `completed`.
merchant_signup_idstringRequiredUnique identifier for the merchant signup.
merchant_termsobjectRequiredFlint's merchant terms the owner must accept.
modesarray of enumRequiredThe modes the signup installs the app in, one environment grant each, `test` first.
testlive
ownerobjectRequiredThe owner the code went to.
partner_app_idstringRequiredThe partner app the signup installs on the new merchant.
partner_app_install_idstringThe install the signup created, present once it is `completed`. Its `merchant_signup_id` names this signup.
platform_fee_capobjectThe app's platform fee cap the code email showed, frozen at create. Absent when the app has none.
requested_permissionsarray of objectRequiredThe 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_onboardingenumRequiredThe onboarding state of the new merchant's default sandbox, which the test grant points at.
completenot_started
statusenumRequiredWhere the signup is. `completed`, `expired` and `canceled` are final. `expired` follows from `expires_at`, so it doesn't advance `version`.
pendingcompletedexpiredcanceled
supported_actionsarray of enumRequiredLifecycle 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.
cancelverify
terms_acceptanceobjectThe owner's acceptance, present once the signup is `completed`.
timezonestringBusiness time zone set on the new merchant. Absent when signup did not include one. Uses an IANA time zone name.
updated_atstringRequiredWhen the signup last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier 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.
{
"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#
/v1/merchant-signupsIdempotentRequires 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_namestringThe 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_challengestringRequiredThe PKCE S256 challenge: base64url SHA-256 of a verifier you keep. The authorization codes verify returns are bound to it.
code_challenge_methodenumRequiredMust be `S256`.
S256
external_reference_idstringYour identifier for this business, such as your account ID. List signups by it.
modesarray of enumRequiredThe 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).
testlive
ownerobjectRequiredThe owner Flint emails the code to.
emailstringRequiredThe owner's email address, lowercased, at most 254 characters. Flint emails the code here, and it becomes the new merchant's account email and the owner's Flint login. Send an address the owner gave you, never one on a domain you control. The local part before @ must be at most 64 octets (UTF-8 bytes).
first_namestringRequiredThe owner's first name, 1 to 100 characters, without links or email addresses: the code email shows it.
last_namestringRequiredThe owner's last name, 1 to 100 characters, without links or email addresses: the code email shows it.
partner_app_idstringRequiredYour partner app to install on the new merchant. It must be active and have a `merchant_action_url`.
requested_permission_idsarray of stringOptional 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_onboardingenumThe onboarding state of the new merchant's default sandbox, which the test grant points at. Send `not_started` to rehearse verification in test mode.
completenot_started
timezonestringIANA 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.
dataobjectRequiredResource, collection, or operation result returned by this request.
business_namestringThe 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_atstringWhen the signup was canceled.
code_expires_atstringWhen the current code expires, present while the signup is `pending` and its code still works.
completed_atstringWhen the signup completed.
created_atstringRequiredWhen the signup was created.
expires_atstringRequiredWhen a `pending` signup expires: 24 hours after it was created. A signup Flint is completing never expires.
external_reference_idstringYour identifier for this business, as you sent it. Absent when you didn't send one.
merchant_idstringThe merchant the signup created, present once it is `completed`.
merchant_signup_idstringRequiredUnique identifier for the merchant signup.
merchant_termsobjectRequiredFlint's merchant terms the owner must accept.
modesarray of enumRequiredThe modes the signup installs the app in, one environment grant each, `test` first.
testlive
ownerobjectRequiredThe owner the code went to.
partner_app_idstringRequiredThe partner app the signup installs on the new merchant.
partner_app_install_idstringThe install the signup created, present once it is `completed`. Its `merchant_signup_id` names this signup.
platform_fee_capobjectThe app's platform fee cap the code email showed, frozen at create. Absent when the app has none.
requested_permissionsarray of objectRequiredThe 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_onboardingenumRequiredThe onboarding state of the new merchant's default sandbox, which the test grant points at.
completenot_started
statusenumRequiredWhere the signup is. `completed`, `expired` and `canceled` are final. `expired` follows from `expires_at`, so it doesn't advance `version`.
pendingcompletedexpiredcanceled
supported_actionsarray of enumRequiredLifecycle 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.
cancelverify
terms_acceptanceobjectThe owner's acceptance, present once the signup is `completed`.
timezonestringBusiness time zone set on the new merchant. Absent when signup did not include one. Uses an IANA time zone name.
updated_atstringRequiredWhen the signup last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier 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#
/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_idstringRequiredID 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.
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.
{
"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#
/v1/merchant-signups/{merchant_signup_id}/cancelIdempotentRequires 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_idstringRequiredID 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_versionintegerOptional 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.
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#
/v1/merchant-signups/{merchant_signup_id}/resend-codeIdempotentRequires 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_idstringRequiredID 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_versionintegerOptional 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.
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#
/v1/merchant-signups/{merchant_signup_id}/rotate-authorization-codesIdempotentRequires 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_idstringRequiredID 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_versionintegerOptional 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.
dataobjectRequiredResource, collection, or operation result returned by this request.
authorization_codes_expire_atstringWhen the codes in this response expire, 5 minutes after they were minted. Present with them.
live_authorization_codestringExchange it at POST /v1/oauth/token for the live grant's tokens, with the code_verifier for the signup's code_challenge and without redirect_uri. Present when the signup installed in live mode and the code was minted by this request. Single use. An idempotent replay withholds it: mint new codes with rotate-authorization-codes.
test_authorization_codestringExchange it at POST /v1/oauth/token for the test grant's tokens, with the code_verifier for the signup's code_challenge and without redirect_uri. Present when the signup installed in test mode and the code was minted by this request. Single use. An idempotent replay withholds it: mint new codes with rotate-authorization-codes.
business_namestringThe 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_atstringWhen the signup was canceled.
code_expires_atstringWhen the current code expires, present while the signup is `pending` and its code still works.
completed_atstringWhen the signup completed.
created_atstringRequiredWhen the signup was created.
expires_atstringRequiredWhen a `pending` signup expires: 24 hours after it was created. A signup Flint is completing never expires.
external_reference_idstringYour identifier for this business, as you sent it. Absent when you didn't send one.
merchant_idstringThe merchant the signup created, present once it is `completed`.
merchant_signup_idstringRequiredUnique identifier for the merchant signup.
merchant_termsobjectRequiredFlint's merchant terms the owner must accept.
modesarray of enumRequiredThe modes the signup installs the app in, one environment grant each, `test` first.
testlive
ownerobjectRequiredThe owner the code went to.
partner_app_idstringRequiredThe partner app the signup installs on the new merchant.
partner_app_install_idstringThe install the signup created, present once it is `completed`. Its `merchant_signup_id` names this signup.
platform_fee_capobjectThe app's platform fee cap the code email showed, frozen at create. Absent when the app has none.
requested_permissionsarray of objectRequiredThe 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_onboardingenumRequiredThe onboarding state of the new merchant's default sandbox, which the test grant points at.
completenot_started
statusenumRequiredWhere the signup is. `completed`, `expired` and `canceled` are final. `expired` follows from `expires_at`, so it doesn't advance `version`.
pendingcompletedexpiredcanceled
supported_actionsarray of enumRequiredLifecycle 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.
cancelverify
terms_acceptanceobjectThe owner's acceptance, present once the signup is `completed`.
timezonestringBusiness time zone set on the new merchant. Absent when signup did not include one. Uses an IANA time zone name.
updated_atstringRequiredWhen the signup last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier 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#
/v1/merchant-signups/{merchant_signup_id}/verifyIdempotentRequires 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_idstringRequiredID 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_versionintegerOptional 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_acceptanceobjectRequiredThe owner's acceptance of Flint's merchant terms.
ip_addressstringRequiredThe owner's browser IP address, IPv4 or IPv6. Request logs redact it.
merchant_terms_versionstringRequiredMust equal the signup's `merchant_terms.version`.
user_agentstringRequiredThe owner's browser user agent, 1 to 1,024 characters. Request logs redact it.
verification_codestringRequiredThe 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?