> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaycheckout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Connect

> Onboard and manage sub-merchants under a single platform account. Platform Connect lets you act on behalf of multiple connected merchants from one login, while keeping each merchant's transactions, and settlements isolated.

## What is Platform Connect?

Platform Connect is xPay's multi-account solution for marketplaces, software platforms, and aggregators that need to accept payments **on behalf of** other businesses. The setup splits responsibility between two roles:

<Card title="Platform vs. Connect accounts">
  <ul>
    <li><strong>Platform Merchant</strong> — the parent account. Onboards Connect merchants, switches into them from the dashboard, and uses one set of API keys to operate across all of its connected accounts. A Platform merchant <em>cannot accept payments itself</em>.</li>
    <li><strong>Connect Merchant</strong> — a regular xPay merchant that lives under a Platform. Accepts payments, owns its own customers, disputes, and settlements. Linked to its parent via platform <code>merchantId</code>.</li>
  </ul>
</Card>

<Note>
  Platform Connect is enabled per-account by xPay. To turn on the Platform Connect solution for your merchant, reach out to your account manager or [hello@xpaycheckout.com](mailto:hello@xpaycheckout.com).
</Note>

***

## When to use it

<Tabs>
  <Tab title="Marketplaces">
    Sellers list and transact on your platform. Each seller is a Connect merchant — they get their own payouts and dispute responsibility, while you keep one integration.
  </Tab>

  <Tab title="SaaS platforms">
    Your customers run their own businesses on top of your software (booking systems, e-commerce builders, vertical SaaS). Onboard each customer as a Connect merchant so they can accept payments without integrating xPay themselves.
  </Tab>

  <Tab title="Aggregators / resellers">
    You bring xPay to a network of sub-merchants. Manage onboarding, KYB, and operations centrally — payments and settlements still flow merchant-by-merchant.
  </Tab>
</Tabs>

***

## How it works

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant PD as Platform Dashboard
    participant XS as xPay Server
    participant CM as Connect Merchant

    rect transparent
    note over PD,XS: 1. Register a Connect merchant
    XS-->>PD: { merchantId, merchantName }
    end

    rect transparent
    note over CM,XS: 2. Connect merchant completes onboarding (KYB)
    CM->>XS: Submit business details / KYC docs
    XS-->>XS: Internal verification → activated
    end

    rect transparent
    note over PD,XS: 3. Platform acts on behalf of Connect merchant
    PD->>XS: API call with header x-connect-merchant-id: <connectMerchantId>
    XS-->>XS: Validate connectMerchantId belongs to Platform
    XS-->>PD: Response scoped to Connect merchant
    end
```

<Steps>
  <Step title="Register a Connect merchant">
    From the Platform dashboard - [connect page](https://app.xpaycheckout.com/connect), create a new Connect merchant.
  </Step>

  <Step title="Onboard the Connect merchant">
    The Connect merchant completes the standard xPay onboarding flow (business details, KYC, settlement bank, documents). When approved, both the Connect merchant's owner <em>and</em> the Platform's owner are notified by email.
  </Step>

  <Step title="Act on behalf of a Connect merchant">
    Once activated, the Platform can switch into any of its Connect merchants:

    <ul>
      <li><strong>Dashboard:</strong> use the <em>Connect account</em> dropdown in the header (or the <em>Connect</em> page) to switch context.</li>
      <li><strong>API:</strong> include the header <code>x-connect-merchant-id: \<connectMerchantId></code> on any authenticated request.</li>
    </ul>

    All read/write operations execute as the Connect merchant.
  </Step>

  <Step title="Switch back to the Platform">
    Drop the <code>x-connect-merchant-id</code> header (or click <em>Switch to Platform account</em> in the dashboard) to return to the Platform context.
  </Step>
</Steps>

***

## The `x-connect-merchant-id` header

This single header is the entire wire-protocol of Platform Connect. It tells xPay: *"I am authenticated as the Platform, but please scope this request to one of my Connect merchants."*

| Header                  | Value                                                                         | Required when                          |
| ----------------------- | ----------------------------------------------------------------------------- | -------------------------------------- |
| `x-connect-merchant-id` | A Connect merchant ID (e.g. `me_abc123…`) owned by the authenticated Platform | Acting on behalf of a Connect merchant |

xPay validates on every request that the supplied `connectMerchantId` actually belongs to the calling Platform. Any mismatch returns `403 Forbidden — Connect Merchant Id does not exist`.

<Tip>
  Idempotency keys are scoped per-merchant. Two requests with the same idempotency key but different <code>x-connect-merchant-id</code> values are treated as independent.
</Tip>

***

## Behavioural rules

<AccordionGroup>
  <Accordion title="Platform merchants cannot accept payments">
    Any payment-creation API call made directly as a Platform merchant (no <code>x-connect-merchant-id</code>) is rejected with <code>"Platform merchants cannot accept payments"</code>. Payments must always be scoped to a Connect merchant.
  </Accordion>

  <Accordion title="Connect merchants behave like standalone merchants">
    Once activated, a Connect merchant has its own keys, settlements, dispute handling. The Platform link does not affect runtime behaviour — it only governs <em>who can act on behalf of whom</em>.
  </Accordion>

  <Accordion title="Onboarding approval emails">
    When a Connect merchant is approved, the activation email is sent to the Connect merchant's owner <em>and</em> CC'd to the Platform's owner so the Platform can track onboarding progress.
  </Accordion>
</AccordionGroup>

***

## Dashboard UX

<Card title="Connect page">
  <ul>
    <li><strong>Register Connect account</strong> — create a new Connect merchant inline. The new merchant is added to the Platform's roster immediately.</li>
    <li><strong>Switch</strong> — jump into any Connect merchant; the dashboard reloads scoped to that merchant.</li>
  </ul>
</Card>

<Card title="Header switcher">
  <p>A persistent dropdown in the dashboard header lets you switch between Connect merchants from anywhere. A pulsing dot indicates that you are currently acting as a Connect merchant; click <em>Switch to Platform account</em> to return.</p>
</Card>