Skip to main content

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.

​
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:

Platform vs. Connect accounts

  • Platform Merchant — 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 cannot accept payments itself.
  • Connect Merchant — a regular xPay merchant that lives under a Platform. Accepts payments, owns its own customers, disputes, and settlements. Linked to its parent via platform merchantId.
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.

​
When to use it

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.

​
How it works

1

Register a Connect merchant

From the Platform dashboard - connect page, create a new Connect merchant.
2

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 and the Platform’s owner are notified by email.
3

Act on behalf of a Connect merchant

Once activated, the Platform can switch into any of its Connect merchants:
  • Dashboard: use the Connect account dropdown in the header (or the Connect page) to switch context.
  • API: include the header x-connect-merchant-id: <connectMerchantId> on any authenticated request.
All read/write operations execute as the Connect merchant.
4

Switch back to the Platform

Drop the x-connect-merchant-id header (or click Switch to Platform account in the dashboard) to return to the Platform context.

​
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.”
HeaderValueRequired when
x-connect-merchant-idA Connect merchant ID (e.g. me_abc123…) owned by the authenticated PlatformActing 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.
Idempotency keys are scoped per-merchant. Two requests with the same idempotency key but different x-connect-merchant-id values are treated as independent.

​
Behavioural rules

Any payment-creation API call made directly as a Platform merchant (no x-connect-merchant-id) is rejected with “Platform merchants cannot accept payments”. Payments must always be scoped to a Connect merchant.
Once activated, a Connect merchant has its own keys, settlements, dispute handling. The Platform link does not affect runtime behaviour — it only governs who can act on behalf of whom.
When a Connect merchant is approved, the activation email is sent to the Connect merchant’s owner and CC’d to the Platform’s owner so the Platform can track onboarding progress.

​
Dashboard UX

Connect page

  • Register Connect account — create a new Connect merchant inline. The new merchant is added to the Platform’s roster immediately.
  • Switch — jump into any Connect merchant; the dashboard reloads scoped to that merchant.

Header switcher

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 Switch to Platform account to return.