FlintflintDocs

Onboarding

The onboarding API takes a merchant from an email address to a fully verified account entirely through API calls: no dashboard required. It is a state machine: start with an email, verify it to receive an onboarding_session_token, then read GET /v1/onboarding/state and follow next_step through advance calls until you can issue your first external API key. The same flow handles verification document uploads when the processor requires them, and it works for both human-driven and agent-driven integrations.

Onboarding routes authenticate with the onboarding_session_token before key issuance. After that, the flow remains available with a normal API key for later compliance remediation: when new requirements come due, read state and advance again to resolve them.

The API and agent onboarding guide walks through the full state machine, including document handling and first-key issuance.

Endpoints

Advance onboarding flow#

POST/v1/onboarding/advanceIdempotent

Submits whatever the caller currently knows, re-evaluates onboarding, reconciles onboarding requirements, and returns the next step in the consolidated onboarding state machine. Send an empty JSON object when the current next_step only asks to refresh onboarding requirements.

Request body
artifactsarray of object
capability_requestsarray of object
countrystring

ISO 3166-1 alpha-2 country code.

include_future_requirementsboolean
profileobject
refresh_urlstring
return_urlstring
sandbox_idstring
surfacestring
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/advance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "profile": {
      "support_email": "help@example.com",
      "website_url": "https://example.com"
    },
    "country": "US",
    "capability_requests": [
      {
        "capability": "card_payments",
        "requested": true
      },
      {
        "capability": "transfers",
        "requested": true
      }
    ],
    "artifacts": [
      {
        "artifact_type": "account_token",
        "token": "tok_123"
      }
    ],
    "surface": "embedded"
  }'
JSON
{
  "data": {
    "merchant_id": "mer_123",
    "merchant_created": true,
    "email_verified": true,
    "default_sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "can_issue_api_key": true,
    "status": "needs_external_action",
    "next_step": {
      "code": "complete_verification_step",
      "owner": "human",
      "surface": "embedded",
      "machine_completable": false,
      "external_action": {
        "kind": "embedded",
        "client_secret": "seti_123",
        "publishable_key": "pk_test_123",
        "expires_at": "2026-03-18T20:00:00Z"
      }
    },
    "profile": {
      "email": "owner@example.com",
      "support_email": "help@example.com",
      "support_phone": "+14155552671",
      "support_url": "https://example.com/support",
      "website_url": "https://example.com"
    },
    "requirements": {
      "currently_due": [
        {
          "field": "merchant_category_code"
        },
        {
          "field": "business_website"
        }
      ],
      "eventually_due": [
        {
          "field": "representative_first_name"
        }
      ],
      "current_deadline_at": "2026-04-01T00:00:00Z"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create onboarding API key#

POST/v1/onboarding/api-keyIdempotent

Creates the first long-lived external API key and exits onboarding.

Request body
namestringrequired
sandbox_idstring
scopesarray of string
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/api-key \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "First backend integration",
    "scopes": [
      "commerce.orders.read",
      "commerce.orders.write",
      "customers.customers.read",
      "customers.customers.write"
    ]
  }'
JSON
{
  "data": {
    "api_key_id": "key_123",
    "merchant_id": "mer_123",
    "name": "Sandbox orders integration",
    "sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "key_prefix": "flint_test_abcd1234",
    "scopes": [
      "accounts.api_keys.read",
      "accounts.api_keys.write",
      "commerce.orders.read",
      "commerce.orders.write"
    ],
    "key_type": "external",
    "status": "active",
    "last_used_at": "2026-03-17T15:00:00Z",
    "expires_at": "2027-03-17T14:30:00Z",
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z",
    "secret_key": "flint_test_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Submit onboarding document#

POST/v1/onboarding/document-submissionsIdempotent

Submits confirmed upload IDs for a document request and returns refreshed onboarding document state.

Query parameters
sandbox_idstring

Optional sandbox to bind when using an onboarding session token.

Request body
document_request_idstringrequired
sandbox_idstring
upload_idsarray of stringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/document-submissions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "document_request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6",
    "upload_ids": [
      "upl_front_123",
      "upl_back_123"
    ]
  }'
JSON
{
  "data": {
    "status": "waiting_for_review",
    "next_step": {
      "code": "wait_for_review",
      "owner": "system",
      "surface": "review",
      "machine_completable": false
    },
    "document_requests": [
      {
        "document_request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6",
        "subject": {
          "subject_type": "individual",
          "subject_id": "primary"
        },
        "document_type": "identity_document",
        "status": "pending_review",
        "required_sides": [
          "front",
          "back"
        ],
        "side_statuses": [
          {
            "side": "front",
            "status": "submitted",
            "upload_id": "upl_front_123"
          },
          {
            "side": "back",
            "status": "submitted",
            "upload_id": "upl_back_123"
          }
        ],
        "allowed_content_types": [
          "image/jpeg",
          "image/png",
          "application/pdf"
        ],
        "max_bytes": 10485760,
        "blocking": true
      }
    ]
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create onboarding document upload#

POST/v1/onboarding/document-uploadsIdempotent

Creates a signed one-file upload session for one side of an onboarding document request.

Query parameters
sandbox_idstring

Optional sandbox to bind when using an onboarding session token.

Request body
content_lengthintegerrequired
content_typestringrequired
document_request_idstringrequired
file_namestringrequired
sandbox_idstring
sidestringrequired
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/document-uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "document_request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6",
    "side": "front",
    "file_name": "license-front.jpg",
    "content_type": "image/jpeg",
    "content_length": 734003
  }'
JSON
{
  "data": {
    "upload_id": "upl_123",
    "document_request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6",
    "side": "front",
    "upload_method": "PUT",
    "upload_url": "https://uploads.example.com/signed-target",
    "upload_body_type": "raw",
    "upload_headers": {
      "Content-Type": "image/jpeg"
    },
    "expires_at": "2026-03-18T20:00:00Z",
    "max_bytes": 10485760,
    "allowed_content_types": [
      "image/jpeg",
      "image/png",
      "application/pdf"
    ],
    "confirm_endpoint": "/v1/onboarding/document-uploads/upl_123/confirm"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Confirm onboarding document upload#

POST/v1/onboarding/document-uploads/{upload_id}/confirmIdempotent

Confirms that a signed upload target contains the uploaded file before document submission.

Path parameters
upload_idstringrequired

Onboarding document upload ID.

Query parameters
sandbox_idstring

Optional sandbox to bind when using an onboarding session token.

Request body
checksumobject
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/document-uploads/upl_123/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "checksum": {
      "algorithm": "sha256",
      "value": "b1946ac92492d2347c6235b4d2611184"
    }
  }'
JSON
{
  "data": {
    "upload_id": "upl_123",
    "document_request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6",
    "side": "front",
    "status": "confirmed",
    "content_type": "image/jpeg",
    "content_length": 734003,
    "confirmed_at": "2026-03-18T19:55:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Start onboarding flow#

POST/v1/onboarding/startIdempotent

Starts the consolidated onboarding flow by emailing a short-lived verification code and returning a temporary verification token.

Request body
emailstringrequired
first_namestringrequired
last_namestringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "email": "owner@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }'
JSON
{
  "data": {
    "verification_started": true,
    "verification_token": "devver_v1.c2FtcGxlLXZlcmlmaWNhdGlvbi10b2tlbg",
    "expires_at": "2026-03-18T20:00:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get onboarding state#

GET/v1/onboarding/state

Returns the consolidated onboarding state machine, including the primary next step for agents or humans. This endpoint is read-only; when the response asks for refresh_onboarding_requirements, call POST /v1/onboarding/advance with an empty JSON object to reconcile onboarding requirements.

Query parameters
sandbox_idstring

Optional sandbox to bind when evaluating test-mode onboarding.

Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/onboarding/state \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "merchant_id": "mer_123",
    "merchant_created": true,
    "email_verified": true,
    "default_sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "can_issue_api_key": true,
    "status": "needs_external_action",
    "next_step": {
      "code": "complete_verification_step",
      "owner": "human",
      "surface": "embedded",
      "machine_completable": false,
      "external_action": {
        "kind": "embedded",
        "client_secret": "seti_123",
        "publishable_key": "pk_test_123",
        "expires_at": "2026-03-18T20:00:00Z"
      }
    },
    "profile": {
      "email": "owner@example.com",
      "support_email": "help@example.com",
      "support_phone": "+14155552671",
      "support_url": "https://example.com/support",
      "website_url": "https://example.com"
    },
    "requirements": {
      "currently_due": [
        {
          "field": "merchant_category_code"
        },
        {
          "field": "business_website"
        }
      ],
      "eventually_due": [
        {
          "field": "representative_first_name"
        }
      ],
      "current_deadline_at": "2026-04-01T00:00:00Z"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Verify onboarding email#

POST/v1/onboarding/verify-emailIdempotent

Verifies the emailed code, provisions the Flint user and merchant if needed, and returns a short-lived session token for the rest of onboarding.

Request body
merchant_idstring
verification_codestringrequired
verification_tokenstringrequired
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/onboarding/verify-email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "verification_token": "devver_v1.c2FtcGxlLXZlcmlmaWNhdGlvbi10b2tlbg",
    "verification_code": "482193"
  }'
JSON
{
  "data": {
    "onboarding_session_token": "devsess_v1.c2FtcGxlLWRldmVsb3Blci1zZXNzaW9uLXRva2Vu",
    "user": {
      "user_id": "usr_123",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "owner@example.com",
      "status": "active",
      "default_merchant_id": "mer_123",
      "created_at": "2026-03-18T19:45:00Z",
      "updated_at": "2026-03-18T19:45:00Z"
    },
    "merchant": {
      "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"
    },
    "default_sandbox_id": "test_01JQEXAMPLEDEFAULT12345678",
    "status": "merchant_ready",
    "merchant_created": true,
    "can_issue_api_key": true,
    "next_step": {
      "code": "check_onboarding_state",
      "owner": "agent",
      "surface": "api",
      "machine_completable": true,
      "submit_endpoint": "/v1/onboarding/state",
      "submit_method": "GET"
    }
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc