Buy Button

The Buy Button frame consolidates the Apple Pay, Google Pay, and card frames into a single button. It renders the one that matches the payment method in the quote signature. When the customer taps to pay, it opens the native Apple Pay or Google Pay sheet, or runs the card pipeline directly. Behind the UI, it runs the same buy orchestration pipeline as the headless Buy frame: it evaluates transaction requirements, creates the transaction, and completes post-transaction processing. The difference is the experience. The Buy frame is headless and leaves every screen under your control. The Buy Button frame provides a visible payment button, plus the native Apple Pay or Google Pay sheet, so you can offer express checkout without building that UI yourself. The message protocol is identical to the Buy frame, so you handle the same events either way. For platform-specific walkthroughs, see manual integration: Web, React Native, Flutter, iOS, and Android.

URL

https://platform.moonpay.com/platform/v1/buy-button

Initialization parameters

Property	Type	Required	Description
`clientToken`	`string`	✅	The client token returned from the connect flow.
`channelId`	`string`	✅	A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages. The format of this string is up to you.
`signature`	`string`	✅	The quote `signature` from the quote endpoint. Pass `signature` as returned.
`externalTransactionId`	`string`		Your own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.
`applePayButtonSettings`	`string`		A `JSON.stringify`-ed, URL-encoded object that styles the Apple Pay button variant. See Apple Pay button settings.

Apple Pay button settings

The Buy Button frame renders the button that matches the payment method in the quote signature. applePayButtonSettings styles the Apple Pay button variant only. It has no effect when the frame renders the card or Google Pay button. Use applePayButtonSettings to style the Apple Pay button without injecting custom CSS. Build a settings object, pass it through JSON.stringify, URL-encode the result, and append it to the frame URL. Every property is optional. Any property you omit keeps the button’s default.

Property	Type	Allowed values
`width`	`string`	Button width in pixels, as a bare number (`"320"`) or a `px` value (`"320px"`). Normalized to `"<n>px"`. Defaults to `100%` so the button fills the container.
`height`	`string`	Button height in pixels, in the same format as `width`. Defaults to `44px`.
`borderRadius`	`string`	Corner radius in pixels, in the same format as `width`. Defaults to `16px`.
`paddingX`	`string`	Horizontal padding in pixels, in the same format as `width`. Defaults to `16px`.
`paddingY`	`string`	Vertical padding in pixels, in the same format as `width`. Defaults to `8px`.
`style`	`string`	The button’s visual style. One of `black`, `white-outline`, or `white`. When you omit this, the button follows the frame’s appearance: light renders the black button and dark renders the white button.
`type`	`string`	The button label. One of `plain`, `buy`, `top-up`, `reload`, `continue`, `check-out`, or `pay`. Defaults to `pay`.
`locale`	`string`	The button’s language. One of `en-US`, `ar-AB`, `ca-ES`, `zh-CN`, `zh-HK`, `zh-TW`, `hr-HR`, `cs-CZ`, `da-DK`, `de-DE`, `nl-NL`, `en-AU`, `en-GB`, `fi-FI`, `fr-CA`, `fr-FR`, `el-GR`, `he-IL`, `hi-IN`, `hu-HU`, `id-ID`, `it-IT`, `ja-JP`, `ko-KR`, `ms-MY`, `nb-NO`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `es-MX`, `es-ES`, `sv-SE`, `th-TH`, `tr-TR`, `uk-UA`, or `vi-VN`.

Dimensions accept pixels only. A bare number is treated as pixels and normalized to a px value.

Validation

Validation applies each property on its own:

A property with an invalid value is ignored, and the remaining valid properties still apply. Invalid values include a non-pixel dimension such as 50%, and a style, type, or locale outside its allowed set.
If the whole value is not valid JSON, the frame ignores applePayButtonSettings entirely and uses the defaults.

Example

This object sets a 52px-tall white button with a 26px corner radius, the buy label, and French text:

{
  "height": "52",
  "borderRadius": "26",
  "style": "white",
  "type": "buy",
  "locale": "fr-FR"
}

Run it through JSON.stringify, URL-encode the result, and append it to the frame URL:

https://platform.moonpay.com/platform/v1/buy-button?...&applePayButtonSettings=%7B%22height%22%3A%2252%22%2C%22borderRadius%22%3A%2226%22%2C%22style%22%3A%22white%22%2C%22type%22%3A%22buy%22%2C%22locale%22%3A%22fr-FR%22%7D

Events

All events are dispatched using the message pattern described in the frames protocol. The Buy Button frame uses the same event payloads as the Buy frame; only the experience differs.

Outbound events

frame->parent These events are sent from this frame to the parent window.

`handshake`

The frame requests that you open a message channel.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "handshake"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type HandshakeEvent = Message<{
  kind: "handshake";
}>;

`ready`

The frame finished loading and the payment button is rendered. Use this to coordinate UI transitions if needed.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ready"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ReadyEvent = Message<{
  kind: "ready";
}>;

`buttonPressed`

The customer tapped the pay button in the buy button. The frame emits this the instant the button is tapped. For Apple Pay and Google Pay, it fires before the OS presents the payment sheet (PassKit on iOS, the Google Pay sheet on Android). For card, it fires before the card pipeline runs. Treat it as an intent-to-buy signal: use it to react to the tap, for example to show a loading state or fire analytics. This event carries no payload. Route it by channelId. buttonPressed is not a purchase outcome. It still fires if the customer opens the payment sheet and then cancels, and it fires before any authorization happens. For the transaction result, listen for complete, which reports the outcome once the payment resolves.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "buttonPressed"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ButtonPressedEvent = Message<{
  kind: "buttonPressed";
}>;

`complete`

The transaction is complete. Use the transaction ID to track final status via polling.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "id": "txn_01",
      "status": "pending"
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type BuyButtonCompleteEvent = Message<{
  kind: "complete";
  payload: {
    transaction: {
      id: string;
      status: "pending" | "completed" | "failed";
    };
  };
}>;

`challenge`

Verification is required before the transaction can proceed. Render the challenge frame at the provided URL. Do not construct the URL yourself — use it as-is.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "challenge",
  "payload": {
    "kind": "frame",
    "url": "https://platform.moonpay.com/platform/v1/challenge?challengeToken=..."
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type BuyButtonChallengeEvent = Message<{
  kind: "challenge";
  payload: {
    kind: string;
    /** Fully-formed URL to pass directly as the challenge frame src. */
    url: string;
  };
}>;

`error`

A terminal error occurred. Remove the frame and surface the message to the developer.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "error",
  "payload": {
    "code": "invalidQuote",
    "message": "Unable to decode the quote signature."
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type BuyButtonErrorEvent = Message<{
  kind: "error";
  payload: {
    code: "configurationError" | "invalidQuote" | "generic";
    /** A developer-facing error message. Not intended to be rendered in UI. */
    message: string;
  };
}>;

Code	Description
`configurationError`	Missing or invalid `signature` parameter
`invalidQuote`	Unable to decode the quote signature
`generic`	Unspecified error

Inbound events

parent->frame These events are sent from the parent window to this frame.

`ack`

Acknowledge the handshake.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ack"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type AckEvent = Message<{
  kind: "ack";
}>;

`setQuote`

Provide a new quote to the frame. Send this when the current quote expires before the customer completes the purchase. Pass signature as returned by the quote endpoint.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "setQuote",
  "payload": {
    "quote": {
      "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type SetQuoteEvent = Message<{
  kind: "setQuote";
  payload: {
    quote: {
      /** The signature from a valid quote. */
      signature: string;
    };
  };
}>;

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

URL

Initialization parameters

Apple Pay button settings

Validation

Example

Events

Outbound events

`handshake`

`ready`

`buttonPressed`

`complete`

`challenge`

`error`

Inbound events

`ack`

`setQuote`

​URL

​Initialization parameters

​Apple Pay button settings

​Validation

​Example

​Events

​Outbound events

​handshake

​ready

​buttonPressed

​complete

​challenge

​error

​Inbound events

​ack

​setQuote

URL

Initialization parameters

Apple Pay button settings

Validation

Example

Events

Outbound events

`handshake`

`ready`

`buttonPressed`

`complete`

`challenge`

`error`

Inbound events

`ack`

`setQuote`