FurlPay Docs
Open App
  • Services & Availability
  • Quickstart
  • For AI Agents
  • Monorepo
  • API Routes
  • Authenticationupdated
  • Webhook Eventsupdated
  • Error Codesupdated
  • Rate Limitsnew
  • Configuration & Setupnew
  • Merchant Paymentsnew
  • Payroll & Payoutsnew
  • Agentic Payments (x402)updated
  • Agent Trust & Mandates (TAP)updated
  • CCTP Cross-Chainupdated
  • LI.FI Swapsupdated
  • FurlPay Travels (Travel MCP)updated
  • Solana Actions & Blinks
  • Settlement Workspacenew
  • FURL Tokennew
  • Claude Connectorupdated
  • AI Assistants
  • Circlenew
  • Ramp Providersnew
  • Telegram Mini Appnew
  • Stripe Crypto
  • Persona KYC
  • Regulatory status
  • Screening & Casesnew
  • Security Postureupdated
  • Signing & WebAuthnupdated
  • Help Center
  • Getting Started
  • KYC Verification
  • Passkeys & Biometrics
  • Privacy & Data Protection
  • Transaction Statuses
  • Gasless Transfers
  • Deposits & Withdrawals
  • Managing Virtual Cards
  • Freezing & Unfreezing Cards
  • Declined Transactions
  • SDK & API Support
  • x402 Monetization Basics
  • Booking Travel
  • Travel Refunds & Cancellations

Resources

  • Changelog
  • System Status
  • OpenAPI Spec
  • Community
  • GitHub
Docs/Business/Settlement Workspace

Business

Settlement workspace and business onboarding

The settlement workspace at /settlement is the business console: payments, payouts, treasury, compliance, reconciliation and developer settings in one place. A business reaches it through a seven-step onboarding that the server controls end to end.

Drafts are not instructions to move money

Records saved in the workspace (beneficiaries, payouts, schedules, invoices, payment links, split rules, checkout configurations) are stored as drafts. The workspace endpoint cannot activate an automation, produce an approval, publish a payable link or move a balance. Real collection goes through merchant payments; real payroll goes through payroll.

Workspace sections

ParameterTypeDescription
Overviewrequired/settlementBalances, in-transit totals and activity for 24h, 7d, 30d and 90d, derived only from the account's own ledger.
Paymentsrequired/settlement/paymentsTransactions, receive, links, invoices, checkout.
Payoutsrequired/settlement/payoutsSend, batch, schedules, approvals, beneficiaries.
Treasuryrequired/settlement/treasuryBalances, convert, rules; virtual accounts sit under this tab.
Compliancerequired/settlement/complianceThe business's own verification and screening state.
Reconcilerequired/settlement/reconcileReconciliation and reports.
Developersrequired/settlement/developersAPI keys and webhook settings.

Every URL under /settlement is validated on the server: it is a real page, a redirect to one, or a 404. Figures the ledger does not record, such as finality, fees or transaction hashes, are shown as a dash rather than estimated.

Assets and networks in drafts

Drafts accept Arbitrum, Base, Ethereum, Solana and Polygon, and the assets USDC, EURC, USDT, USD, EUR and GBP. Avalanche, SOL and ETH are shown as explicitly unavailable: FurlPay does not detect settlement deposits on Avalanche, and settlement holds stablecoins and fiat rather than volatile native tokens. Listing an asset in a draft form does not mean FurlPay custodies or converts it.

Business onboarding

Onboarding lives at /settlement/onboarding/<step>. The client edits one step at a time. The server alone decides which steps are complete, the screening result, the document review state and activation. Steps cannot be skipped: each one requires the earlier steps to be complete.

ParameterTypeDescription
1. Business informationrequiredbusiness-informationLegal name, type (company, individual, marketplace, non-profit), industry, country, size.
2. Verify identityrequiredidentityAuthorised representative and document uploads.
3. Business detailsrequiredbusiness-detailsOwnership and control.
4. Compliance and riskrequiredcomplianceSanctions screening of the business, its owners and the representative.
5. Set up treasuryrequiredtreasuryWallets and account preferences.
6. Configure settlementrequiredsettlementSplit rules; whole percentages that must total 100, at most 10 rules.
7. Review and activaterequiredreviewReadiness is re-derived from stored state; client state is never trusted.

Documents

Required: certificate of incorporation, articles of association, proof of business address and the front of a government ID. Optional: business licence and ID back. Files must be PDF, PNG or JPEG, at most 10 MB, and are stored in a private bucket with no public URLs.

Screening

Screening covers the legal name, trading name, each owner and the representative. A result is reused for identical inputs for 24 hours. A provider error or a timeout (10 seconds) is recorded as failed and shown as "Screening unavailable"; it is never recorded as clear. A potential match sends the case to compliance review. Details are in Screening and cases.

Compliance review

Review actions are restricted to accounts holding the compliance_officer role. A reviewer can never decide their own case. Each decision records who, when, what and why, and is written to the audit log. Editing business, identity or ownership facts after approval reopens the review, because the approval covered the old facts.

Activation

Activation succeeds only when no blocker remains. The response lists the exact blockers otherwise, for example: required documents missing, documents pending approval, sanctions screening not run or expired, screening awaiting review, verification provider not configured, document storage unavailable, treasury or settlement not configured.

What activation does not do

Activation records that a business completed onboarding in the workspace. It does not grant a licence, open a bank account, or turn on a payment rail. Each rail keeps its own gate.

API

MethodPathDescription
GET/api/settlement/workspaceSnapshot: balances, overview metrics, up to 500 transactions, saved drafts, storage state
POST/api/settlement/workspaceSave one draft record { id, data }; destination addresses are validated for their network
PATCH/api/settlement/workspaceArchive a draft record
GET/api/settlement/transactionsSearch and filter the account's ledger transactions
GET/api/settlement/onboardingOnboarding state, step status and readiness
PUT/api/settlement/onboardingSave or complete one step; 422 with field errors, 409 with blockers
POST/api/settlement/onboardingActions: run screening, complete the compliance step, start identity verification, activate
POST / DELETE/api/settlement/onboarding/documentsUpload or remove a document
GET / POST/api/settlement/onboarding/reviewCompliance officers only: review queue and decisions

All routes require a signed-in session. When storage is not configured, write routes answer 503 and state that nothing was saved; the workspace snapshot still loads and reports storage: "unavailable".

Setup

  • Supabase configured, with migrations 0037_settlement_workspace, 0038_settlement_onboarding and 0039_compliance_cases applied. Migration 0038 also creates the private document bucket.
  • An identity provider: COMPLIANCE_IDENTITY_PROVIDER set to persona (default, needs PERSONA_API_KEY) or sumsub (needs SUMSUB_APP_TOKEN and SUMSUB_SECRET_KEY). Without one, identity verification reports unavailable and activation stays blocked.
  • A screening provider: COMPLIANCE_SCREENING_PROVIDER, default furlpay (the bundled sanctions list) or complyadvantage with its API key.
  • At least one account granted the compliance_officer role through the role-grant process, or no case can be reviewed.
Did this page help?
Edit this page on GitHub

← Previous

Solana Actions & Blinks

Next →

FURL Token