flintDocs

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.

Note:

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

A new account starts with a suggested business_name, taken from the domain of a work email address or, failing that, from the person's name. Change it in the dashboard or with PATCH /v1/merchant using a live key.

Flint checks contact fields when you save them:

  • support_email: one email address with no display name, at most 320 characters, and a domain that contains a dot, such as help@example.com.
  • support_url and website_url: a full http:// or https:// URL of at most 2,048 characters with a valid host name or IP address, such as https://example.com/support. User names, passwords, and leading or trailing spaces are rejected.
  • support_phone and phone: international format, a + followed by 7 to 15 digits that include the country code, such as +12125551234. The first digit can't be 0, and spaces, dashes, and parentheses are rejected.

A value that fails returns a validation error with the field name in param.

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

icon is a square image, at least 128 by 128 pixels, shown where the store needs a small mark: browser tabs and compact headers. It has the same input shape as logo: send source_url and optional alt and external_reference_id on PATCH, or null to clear it. The response is an Image with url, width, and height and any supplied image metadata. Omission preserves the current icon. An image that is not square or is smaller than 128 by 128 pixels returns IMAGE_DIMENSIONS_UNSUPPORTED. The merchant has one icon shared across live and sandbox environments.

Get merchant#

GET/v1/merchant

Requires scope merchants.profile.read or merchants.profile.write

Returns the authenticated merchant.

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
curl https://api.withflintpay.com/v1/merchant \
  -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,
    "icon": {
      "alt": "Merchant icon",
      "height": 256,
      "url": "https://images.withflintpay.com/ia_merchant_icon/original",
      "width": 256
    },
    "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/merchantIdempotent

Requires scope merchants.profile.write

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

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.

business_namestring

Business name buyers see. Surrounding whitespace is trimmed, and the result must have 1 to 120 characters. The name cannot be cleared, and only live credentials can set it.

emailstring
expected_versioninteger

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

iconobject

A square image, at least 128 by 128 pixels, shown where the store needs a small mark: browser tabs and compact headers.

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
reporting_timezonestring
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

Same response as Get merchant.

curl -X PATCH https://api.withflintpay.com/v1/merchant \
  -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": "Flint Events LLC",
    "metadata": {
      "segment": "festivals"
    },
    "phone": "+14155550000",
    "support_email": "help@example.com"
  }'

Was this helpful?