FlintflintDocs

Merchants

A merchant is the payment and legal tenant in Flint: it owns the processor account, settlement details, and business profile. The public merchant surface is merchant-scoped: you read and update the authenticated merchant, and external API keys stay bound to exactly one merchant.

A merchant may optionally belong to an organization for hierarchy and settings inheritance; a merchant without an organization_id is a valid standalone tenant. payments, payouts, and requirements report current readiness, while observed_at says when Flint evaluated it. onboarding_status, has_past_due, and current_deadline_at provide the related account state. Use the onboarding and account management surfaces to resolve outstanding requirements.

For creating and verifying merchants programmatically, see the API and agent onboarding guide.

The merchant profile and logo share version. Send the last-read value as expected_version on PATCH to reject a concurrent profile edit with MERCHANT_CHANGED. A logo change advances the same version as contact, address, metadata, and business-profile changes. Readiness changes do not advance the profile version.

Endpoints

The Merchant object#

Every field on a merchant, as returned by retrieve and carried by the endpoints below.

Attributes
addressobject
api_versionstring

Default API version for requests without a Flint-Version header. Shared across live and test environments.

api_version_changed_atstring

When the merchant's default API version last changed.

api_version_pinned_atstring

When the merchant's default API version was first set.

api_version_previousstring

Previous API version, present while a supported rollback is available.

api_version_rollback_expires_atstring

When the 72-hour rollback offer expires. Explicit changes to any supported version remain available afterward.

bannersarray of object
business_namestring
business_typeenum

Flint-normalized business profile type. Unknown backend/provider values are returned as unknown.

individualcompanynon_profitgovernment_entityunknown
created_atstring

RFC3339 timestamp.

current_deadline_atstring

RFC3339 timestamp.

emailstringrequired
has_past_duebooleanrequired

Whether Flint's synced readiness projection has past-due account requirements.

logoobject
merchant_idstringrequired
metadatamap of string
observed_atstringrequired

RFC3339 timestamp.

onboarding_statusenumrequired

Activation lifecycle status. A merchant can remain completed after activation while later readiness fields or requirements show current account attention is needed.

not_startedin_progresscompleted
organizationobject or null
organization_idstring
paymentsobjectrequired
payoutsobjectrequired
phonestring
requirementsobjectrequired
statusenumrequired
activesuspendedrestrictedclosed
status_reasonstring
support_emailstring
support_phonestring
support_urlstring
updated_atstring

RFC3339 timestamp.

versionintegerrequired

Profile version. Changes to contact details, metadata, organization, support details, or logo advance this version. Readiness updates do not.

website_urlstring
JSON
{
  "address": {
    "city": "New York",
    "country": "US",
    "line1": "123 Main St",
    "postal_code": "10001",
    "state": "NY"
  },
  "banners": [
    {
      "message": "Your account is ready to accept payments.",
      "style": "success"
    }
  ],
  "business_name": "Flint Events LLC",
  "business_type": "company",
  "created_at": "2026-03-17T14:30:00Z",
  "email": "owner@example.com",
  "has_past_due": false,
  "logo": {
    "alt": "Merchant logo",
    "height": 512,
    "url": "https://images.withflintpay.com/ia_merchant_logo/original",
    "width": 512
  },
  "merchant_id": "mer_123",
  "metadata": {
    "segment": "events"
  },
  "observed_at": "2026-06-28T00:00:00Z",
  "onboarding_status": "completed",
  "payments": {
    "next_actions": [],
    "status": "ready",
    "status_reason": null
  },
  "payouts": {
    "next_actions": [
      {
        "action_type": "create_merchant_account_session",
        "merchant_account_session": {
          "collection_strategy": "upfront",
          "component": "account_onboarding",
          "future_requirements": "omit"
        },
        "reason_code": "requirements_past_due",
        "reason_message": "Create a merchant account session to complete past-due merchant requirements.",
        "required_fields": [
          "components"
        ],
        "required_scope": "merchants.account_sessions.write",
        "url": "/v1/merchant-account-sessions"
      }
    ],
    "status": "blocked",
    "status_reason": "requirements_past_due"
  },
  "phone": "+14155552671",
  "requirements": {
    "currently_due": [],
    "disabled_reason": "requirements_past_due",
    "eventually_due": [],
    "past_due": [
      "business_website"
    ],
    "pending_verification": []
  },
  "status": "active",
  "support_email": "support@example.com",
  "support_phone": "+14155552671",
  "support_url": "https://example.com/support",
  "updated_at": "2026-03-17T14:30:00Z",
  "version": 1,
  "website_url": "https://withflintpay.com"
}

Get merchant#

GET/v1/merchants/{merchant_id}Requires scope: merchants.profile.read or merchants.profile.write

Returns the authenticated merchant by ID.

Path parameters
merchant_idstringrequired

Flint merchant ID.

Query parameters
expandarray of enum

Supported expansions: organization. Expansion requires merchants.profile.read plus accounts.organizations.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Repeat expand, for example expand=organization&expand=organization, or pass one comma-separated value.

organization
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/merchants/mer_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "address": {
      "city": "New York",
      "country": "US",
      "line1": "123 Main St",
      "postal_code": "10001",
      "state": "NY"
    },
    "banners": [
      {
        "message": "Your account is ready to accept payments.",
        "style": "success"
      }
    ],
    "business_name": "Flint Events LLC",
    "business_type": "company",
    "created_at": "2026-03-17T14:30:00Z",
    "email": "owner@example.com",
    "has_past_due": false,
    "logo": {
      "alt": "Merchant logo",
      "height": 512,
      "url": "https://images.withflintpay.com/ia_merchant_logo/original",
      "width": 512
    },
    "merchant_id": "mer_123",
    "metadata": {
      "segment": "events"
    },
    "observed_at": "2026-06-28T00:00:00Z",
    "onboarding_status": "completed",
    "payments": {
      "next_actions": [],
      "status": "ready",
      "status_reason": null
    },
    "payouts": {
      "next_actions": [
        {
          "action_type": "create_merchant_account_session",
          "merchant_account_session": {
            "collection_strategy": "upfront",
            "component": "account_onboarding",
            "future_requirements": "omit"
          },
          "reason_code": "requirements_past_due",
          "reason_message": "Create a merchant account session to complete past-due merchant requirements.",
          "required_fields": [
            "components"
          ],
          "required_scope": "merchants.account_sessions.write",
          "url": "/v1/merchant-account-sessions"
        }
      ],
      "status": "blocked",
      "status_reason": "requirements_past_due"
    },
    "phone": "+14155552671",
    "requirements": {
      "currently_due": [],
      "disabled_reason": "requirements_past_due",
      "eventually_due": [],
      "past_due": [
        "business_website"
      ],
      "pending_verification": []
    },
    "status": "active",
    "support_email": "support@example.com",
    "support_phone": "+14155552671",
    "support_url": "https://example.com/support",
    "updated_at": "2026-03-17T14:30:00Z",
    "version": 1,
    "website_url": "https://withflintpay.com"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update merchant#

PATCH/v1/merchants/{merchant_id}IdempotentRequires scope: merchants.profile.write

Applies a sparse update to the authenticated merchant's public business profile fields.

Path parameters
merchant_idstringrequired

Flint merchant ID.

Request body
addressobject
api_versionstring

Set the merchant default to any supported API version. Omit to leave it unchanged. Null is not accepted. The default is shared across live and test environments; requests with Flint-Version use that header instead.

emailstring
expected_versioninteger

Merchant profile version last read. A different current version returns MERCHANT_CHANGED. Send this value when saving a logo to detect concurrent profile edits.

logoobject
metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API.

organization_idstring
phonestring
support_emailstring
support_phonestring

Support phone in E.164 format, for example +12125551234. Send an empty string to clear the phone number.

support_urlstring
website_urlstring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

API_VERSION_RETIREDAUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_API_VERSIONINVALID_EXPECTED_VERSIONINVALID_REQUESTMERCHANT_CHANGEDRATE_LIMIT_EXCEEDEDRESOURCE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/merchants/mer_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {
      "segment": "festivals"
    },
    "phone": "+14155550000",
    "support_email": "help@example.com"
  }'
Rate this doc