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

# How Connect works

> Accept payments and save cards for the businesses on your platform with one set of platform keys.

Connect lets a platform accept payments for businesses connected to it. Your
platform runs the website and the integration. Each connected merchant owns the
payments, customers, and saved cards that belong to it.

## Who is involved

| Party              | Role                                                                         | Owns                                                                   |
| ------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Platform           | Your business. It operates the payment page and holds the platform API keys. | Platform keys, payment domains, and platform webhook endpoints         |
| Connected merchant | A business on your platform that receives payments.                          | Its PaymentIntents, SetupIntents, customers, and saved payment methods |
| Customer           | The person paying a connected merchant.                                      | Represented by an optional customer record owned by the merchant       |

A connected merchant is identified by its Ionic merchant ID, such as
`mer_BBBBBBBBBBBBBB`. Store this ID on your own merchant record when the business
connects to your platform. Merchant-scoped Connect requests select a merchant with it; platform-level
requests do not.

## Platform keys

Create platform keys in **Connect → API keys**.

| Key                      | Runs on                | Used for                                                       |
| ------------------------ | ---------------------- | -------------------------------------------------------------- |
| Platform secret key      | Your server            | API requests for your platform and for its connected merchants |
| Platform publishable key | The customer's browser | Ionic Blocks on your payment page                              |

One publishable key serves every merchant connected to your platform. Test keys
select test mode and live keys select live mode. Connections, customers, and
object IDs are separate in each mode.

## Selecting a merchant

A request that acts for a connected merchant names that merchant once.

On your server, send the `Ionic-Account` header with the platform secret key, or
pass the `account` request option to the server SDK. The SDK sends the header
for that request:

```ts theme={null}
const paymentIntent = await ionic.paymentIntents.create(
  { "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:payment:inv_123", amount: 12500, currency: "usd", reference: "inv_123" },
  { account: "mer_BBBBBBBBBBBBBB" },
);
```

In the browser, pass the same merchant when you create the Ionic client:

```js theme={null}
const ionic = Ionic(platformPublishableKey, { account: "mer_BBBBBBBBBBBBBB" });
```

The merchant is fixed for that client. To collect for a different merchant,
create a new client.

PaymentIntents, SetupIntents, and customers accept a merchant selection; each
endpoint that accepts `Ionic-Account` says so in the API reference. Payment
domains and platform webhook endpoints belong to the platform itself, so those
requests carry no merchant selection.

## Permissions

A Connect request succeeds when the platform key and the merchant's connection
both grant the permission the operation needs.

| Operation                                  | Permission            |
| ------------------------------------------ | --------------------- |
| Create and confirm payments                | `payments:write`      |
| Read payments and receive payment webhooks | `payments:read`       |
| Create, confirm, and cancel SetupIntents   | `setup_intents:write` |
| Retrieve and list SetupIntents             | `setup_intents:read`  |
| Create and update customers                | `customers:write`     |
| Retrieve customers                         | `customers:read`      |

## Payment domains

Register each website your platform operates in **Connect → Payment domains**,
once per mode. Connected merchants with an active connection and the required permissions can use that website with your
platform publishable key. See [Platform payment domains](/guides/platform-payment-domains).

## Webhooks

A platform webhook endpoint receives eligible events from merchants with active
connections and the matching resource read permission. Each event names the merchant that owns the object in `event.account`.
Match it to the merchant stored with the payment before acting on the event. See
[Platform webhooks](/webhooks/endpoints#platform-webhooks-for-connected-accounts).

## Connect your first merchant

Follow [Connect a merchant](/guides/connect-a-merchant) to request access, handle
the merchant's approval, and save the merchant ID for subsequent requests.

## Next steps

<CardGroup cols={2}>
  <Card title="Accept payments" icon="credit-card" href="/guides/connect-blocks">
    Create a PaymentIntent for a connected merchant and collect the card with Ionic Blocks.
  </Card>

  <Card title="Save cards" icon="id-card" href="/guides/connect-save-cards">
    Save a card for a connected merchant's customer without taking a payment.
  </Card>
</CardGroup>