How Connect works

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:

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:

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.

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.

Connect your first merchant

Follow Connect a merchant to request access, handle the merchant’s approval, and save the merchant ID for subsequent requests.

Next steps

Accept payments

Create a PaymentIntent for a connected merchant and collect the card with Ionic Blocks.

Save cards

Save a card for a connected merchant’s customer without taking a payment.

Start here

Accept payments

Ionic Blocks

Connect

Recurring billing

After the payment

Build commerce

Concepts

Who is involved

Platform keys

Selecting a merchant

Permissions

Payment domains

Webhooks

Connect your first merchant

Next steps

Accept payments

Save cards

​Who is involved

​Platform keys

​Selecting a merchant

​Permissions

​Payment domains

​Webhooks

​Connect your first merchant

​Next steps

Accept payments

Save cards

Who is involved

Platform keys

Selecting a merchant

Permissions

Payment domains

Webhooks

Connect your first merchant

Next steps