Onboard buyers and sellers

Onboard sellers to accept payments and receive payouts, and buyers to pay for purchases.

Marketplaces connect buyers with sellers. Buyers pay for goods or services; sellers receive payments and need payouts. frameOS supports both with capability-based onboarding: sellers get identity verification and payout capabilities, while buyers need only payment methods. Sellers can be individuals or businesses depending on your marketplace model.

Use this guide if you're building a marketplace where:

• Sellers list goods or services and receive payments and payouts.
• Buyers purchase from sellers and need to add a payment method.
• You need identity verification for sellers who receive payouts.
• Frame handles onboarding via hosted flow or you use the API with onboarding sessions.
• Each buyer and each seller has a frameOS account with capabilities scoped to their role.

We recommend this configuration when you get started with marketplaces on frameOS. You can compose the flow yourself, use the iOS or Android SDK, or build the API integration directly.

In addition to the flows below, consider optional capabilities for both roles and compliance and verification.

Account types

Marketplaces have two account types with different capabilities:

Buyers only need to add a payment method. Sellers need identity verification and payout configuration before they can receive funds. Sellers can be individual or business accounts — use business for sellers who operate as companies.

Choose your flow: Sellers | Buyers

Before you begin

Sign up at the Frame Developer Portal and obtain your sandbox API key. Use sandbox keys for development and testing — they do not move real money or trigger live verification services.

Sellers

Capabilities

Sellers receive payments and payouts. Request capabilities for identity verification, payment acceptance, and payout methods.

Core capabilities:

Optional capabilities — add based on your marketplace needs:

curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer sk_test_YOUR_SANDBOX_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "capabilities": [
    "kyc",
    "kyc_prefill",
    "creator_shield",
    "card_send",
    "bank_account_send",
    "card_receive",
    "bank_account_receive",
    "geo_compliance",
    "address_verification"
  ],
  "profile": {
    "individual": {
      "email": "seller@example.com",
      "name": {
        "first_name": "Jordan",
        "last_name": "Seller"
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      }
    }
  }
}'

For business sellers, use "type": "business" and provide the business profile. See Accounts for business account parameters.

Onboarding flow

1. Inspect the response and currently_due — The API returns the account with capabilities in pending status. The response includes currently_due — field paths scoped to requirements that must still be collected or verified. Use it to understand what the seller needs to provide.

2. Create an onboarding session — Create an onboarding session and redirect the seller to the session URL. Frame's hosted UI adapts to the account type (individual or business) and guides them through identity verification, payout setup, and terms acceptance.

curl --request POST \
  --url https://api.framepayments.com/v1/onboarding_sessions \
  --header 'Authorization: Bearer sk_test_YOUR_SANDBOX_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
  "return_url": "https://yoursite.com/onboarding-complete"
}'

Redirect the seller to the url in the response. On mobile, use the iOS or Android SDK to present the flow in-app.

3. Capabilities move to active — After the seller completes onboarding, Frame runs background services to approve the capabilities. In the Frame Dashboard, capabilities move from pending to active as each check completes. Use webhooks to be notified when capabilities change so your platform can unlock seller listings or store features.

Payout options

The capabilities you enable for sellers depend on how you want them to receive payouts:

• Push to card — Use card_receive so sellers receive payouts to a debit card. Faster; requires card verification and KYC.
• Bank account — Use bank_account_receive so sellers receive payouts to a bank account. Often preferred for larger amounts; requires bank account verification and KYC.
• Both — Enable card_receive and bank_account_receive and let sellers choose their preferred method during onboarding.

Optional: Creator Shield

For marketplaces where sellers receive payouts, Creator Shield adds continuous fraud monitoring. It runs in the background on every inbound payment and restricts accounts when adverse media or risk signals are detected. Add creator_shield to seller capabilities if you want this protection. See Creator Shield for full details.

Buyers

Capabilities

Buyers pay for purchases. They need card_send and bank_account_send to add and use a payment method. No KYC or payout setup is required.

Core capabilities:

Optional capabilities — add based on your marketplace needs:

curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer sk_test_YOUR_SANDBOX_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "capabilities": ["card_send", "bank_account_send", "address_verification"],
  "profile": {
    "individual": {
      "email": "buyer@example.com",
      "name": {
        "first_name": "Sam",
        "last_name": "Buyer"
      }
    }
  }
}'

Onboarding flow

1. Inspect the response and currently_due — Buyer accounts have fewer currently_due items than sellers (payment method, terms, and any optional verification you requested). Use currently_due to understand what the buyer needs to provide.

2. Create an onboarding session — Create an onboarding session and redirect the buyer to the session URL. Frame's hosted UI shows a streamlined flow to add a payment method — no identity verification unless you requested optional capabilities.

3. Capabilities move to active — Buyers with only card_send and bank_account_send typically activate quickly. Use webhooks to be notified when capabilities change so your platform can unlock checkout as soon as onboarding completes.

Optional capabilities

Summary of optional capabilities by role:

See the linked capability pages for requirements and integration details. Add only what your marketplace needs — each optional capability increases onboarding friction.

Compliance and verification

Marketplaces move money between buyers and sellers. frameOS helps you stay compliant:

• KYC — Required for sellers who receive payouts. KYC prefill can speed onboarding when you already have verified phone data. Buyers with only card_send and bank_account_send do not require KYC — their flow is lighter and focused on payment method setup.
• Terms of service — Frame collects acceptance of terms during onboarding; you can pass terms_of_service when creating the account if the user accepts in your UI first.
• Geocompliance — Optional. Add geo_compliance to seller accounts if you need to enforce location-based rules or restrict access by jurisdiction.
• Business accounts — Sellers operating as companies use the business account type with a different verification flow. See Accounts for business parameters.

Resources

Accounts: Full reference for creating accounts, business accounts, and managing capabilities.

Onboarding Sessions: Use hosted onboarding to collect identity, payment methods, and compliance information.

Creator Shield: Fraud protection for sellers receiving payments.

Quick start: Get up and running with frameOS in minutes.

KYC and KYC Prefill: Identity verification and prefill flows.

Payouts: Card and bank account payout options.

Geocompliance: Location-based rules and restrictions.

SDKs: iOS, Android, and server-side SDKs for building your integration.