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, but that link is not the same thing as merchant ownership; a merchant without an organization_id is still a valid standalone tenant. Fields like onboarding_status, has_past_due, and current_deadline reflect verification progress. Use the onboarding and account management surfaces to resolve outstanding requirements.

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

Endpoints

Get merchant#

GET/v1/merchants/{merchant_id}

Returns the authenticated merchant by ID.

Path parameters
merchant_idstringrequired

Flint merchant ID.

Query parameters
expandarray of enum

Supported expansions: organization. Expansion requires accounts.merchants.read plus accounts.organizations.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=organization&expand=organization. Comma-separated values, expand[]=organization, and numeric expand[0]=organization are accepted for common client compatibility.

organization
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/merchants/mer_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update merchant#

PATCH/v1/merchants/{merchant_id}Idempotent

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

Path parameters
merchant_idstringrequired

Flint merchant ID.

Request body
addressobject
emailstring
image_urlstring
metadatamap of string
organization_idstring
phonestring
support_emailstring
support_phonestring
support_urlstring
website_urlstring
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/merchants/mer_123 \
  -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"
  }'
JSON
{
  "data": {
    "merchant_id": "mer_123",
    "email": "owner@example.com",
    "onboarding_status": "completed",
    "status": "active",
    "metadata": {
      "segment": "events"
    },
    "image_url": "https://cdn.withflintpay.com/merchant/logo.png",
    "phone": "+14155552671",
    "address": {
      "line1": "123 Main St",
      "country": "US",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001"
    },
    "banners": [
      {
        "message": "Your account is ready to accept payments.",
        "style": "success"
      }
    ],
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "business_name": "Flint Events LLC",
    "has_past_due": false,
    "tier": "free",
    "business_type": "company",
    "support_email": "support@example.com",
    "support_phone": "+14155552671",
    "support_url": "https://example.com/support",
    "website_url": "https://example.com"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get merchant readiness#

GET/v1/merchants/{merchant_id}/readiness

Returns the merchant's high-level payment and payout readiness snapshot. Use /v1/capabilities for capability-specific blockers and /v1/payment-options/resolve for transaction-specific payment option availability.

Path parameters
merchant_idstringrequired

Flint merchant ID.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/merchants/mer_123/readiness \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "merchant_id": "mer_123",
    "business_name": "Flint Events LLC",
    "payments": {
      "status": "ready",
      "status_reason": null,
      "next_actions": []
    },
    "payouts": {
      "status": "blocked",
      "status_reason": "requirements_past_due",
      "next_actions": [
        {
          "action_type": "create_account_session",
          "url": "/v1/account-sessions",
          "reason_code": "requirements_past_due",
          "reason_message": "Create an account session to complete past-due merchant requirements.",
          "required_fields": [
            "session_kind"
          ],
          "required_scope": "accounts.merchants.write",
          "account_session": {
            "session_kind": "account_management",
            "include_future_requirements": true
          }
        }
      ]
    },
    "requirements": {
      "currently_due": [],
      "past_due": [
        "business_website"
      ],
      "eventually_due": [],
      "pending_verification": [],
      "disabled_reason": "requirements_past_due"
    },
    "observed_at": "2026-06-28T00:00:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc