Merchant Collect iframe integration

1. Embedding

Load the collect page URL returned by the server inside an iframe.

1.1 iframe permissions: allow (do not use allow-same-origin)

The collect page may be embedded by other sites in an iframe (cross-origin). The parent page only needs to set:

Attribute	Description
`allow="clipboard-write"`	Allows clipboard write inside the iframe (e.g. Copy Link); otherwise the browser may block copy.

Do not set allow-same-origin in sandbox: otherwise the iframe would be treated as same-origin with the embedder, allowing our page to access the embedder’s document and creating a security risk. Without sandbox, the iframe loads under our domain normally; cookies, storage, and canvas export/download work; the parent only needs to grant clipboard via allow="clipboard-write".

2. Close event: postMessage contract

When the user clicks the close button inside the collect page, the iframe sends a postMessage to the parent window so the parent can hide the iframe, close a modal, or run other logic.

2.1 Message payload

Field	Type	Description
`type`	string	Always `'MERCHANT_COLLECT_CLOSED'`; use this to identify the close event.
`source`	string	Always `'merchant-collect'`; identifies the sending page.

Example:

{
  "type": "MERCHANT_COLLECT_CLOSED",
  "source": "merchant-collect"
}

2.2 When the message is sent

Sent only when the page is inside an iframe (i.e. window.parent !== window).

Sent to window.parent; targetOrigin is determined by env or default.

3. Parent page: how to listen

3.1 Plain JavaScript

3.2 Validate origin (recommended)

Validate event.origin and only accept messages from trusted origins:

4. URL parameter: darkMode (optional)

The collect page accepts a URL query parameter darkMode to override the user’s local/persisted theme so the parent and embed can match.

Parameter	Values	Effect
`darkMode`	`true` / `1` / `yes`	Force dark
`darkMode`	`false` / `0` / `no`	Force light

If omitted or invalid, the current theme is unchanged (local or system preference).

When setting the iframe src, the parent can append this parameter to the server-returned collect URL, e.g.:

https://example.com/en/merchant-collect?token=xxx&darkMode=true

5. Set dark mode via postMessage (overrides URL)

The parent can send a postMessage to the collect iframe to switch dark/light mode at runtime. This overrides the URL darkMode parameter (e.g. load with URL light, then switch to dark via postMessage).

5.1 Message format (parent → iframe)

Field	Type	Description
`type`	string	Must be `'MERCHANT_COLLECT_SET_DARK_MODE'`.
`darkMode`	boolean	`true` = dark, `false` = light.

5.2 How to send

Get the iframe’s contentWindow and call postMessage with the collect page’s origin as the second argument (use window.location.origin when same-origin):

The message is only handled when the collect page is inside an iframe; the theme set by postMessage overrides the current URL darkMode parameter.

FE: Create stablecoin collection sub-account link

Merchant Collect iframe integration#

1. Embedding#

1.1 iframe permissions: allow (do not use allow-same-origin)#

2. Close event: postMessage contract#

2.1 Message payload#

2.2 When the message is sent#

3. Parent page: how to listen#

3.1 Plain JavaScript#

3.2 Validate origin (recommended)#

4. URL parameter: darkMode (optional)#

5. Set dark mode via postMessage (overrides URL)#

5.1 Message format (parent → iframe)#

5.2 How to send#