Embed the checkout
Render the hosted payment page inside an iframe on your own site, and the postMessage events it sends your page.
If you'd rather keep customers on your own site instead of sending them away to the full hosted page, you can render the exact same hosted payment page inside an iframe. The customer fills in their card without ever leaving your checkout, and PCI scope still stays out of your stack.
This works for every flow that returns a redirectUrl: one-time payments and subscription first charges alike. The integration is identical to the redirect flow: you still create the payment or subscription, get back a redirectUrl, and fulfil on the webhook. The only difference is that instead of a 302, you point an iframe at that URL.
<iframe
src="{{redirectUrl from POST /payments or POST /subscriptions}}"
width="100%"
height="600"
frameborder="0"
allow="payment"
></iframe>Register your embed origins first
For security, the payment page refuses to render inside a frame unless the
embedding site's origin is registered on your merchant account. Tell your
account manager which origins (e.g. https://your-shop.example) will host the
iframe before shipping — until then the browser will block the frame.
While developing, payments created with a test API key can be embedded
from http://localhost or http://127.0.0.1 on any port without registering
anything. Live payments only ever embed from your registered origins.
Sandboxed iframes
APMs open the customer's bank in a new tab from
a click inside the frame. If your iframe has a sandbox attribute, add
allow-popups allow-popups-to-escape-sandbox to it, or every APM button
reports the tab as blocked. Cards and wallets need nothing extra.
Inside an iframe the page adapts automatically: 3DS challenges render in-frame, and instead of navigating away the page signals completion to your parent window via postMessage. APMs are the exception: the bank's page can't be framed, so it opens in a new tab. To split one payment across several frames of your own checkout, one per payment method, see Choose what the checkout offers. Listen for these messages (always check event.origin is the Mintcash payment page origin):
window.addEventListener("message", (event) => {
const msg = event.data;
if (msg?.type === "mintcash:checkout") {
// msg.ok === true only when msg.status === "succeeded"
// msg.status: "succeeded" | "pending" | "declined" | "failed" | "expired" | "cancelled"
}
if (msg?.type === "mintcash:resize") {
iframe.style.height = `${msg.height}px`; // keep the frame sized to content
}
});Message reference
The page sends these message types:
| Message | Payload | When it fires |
|---|---|---|
mintcash:checkout | { ok, status } | When the charge attempt reaches an outcome — see the status table below |
mintcash:resize | { height } | Once on load, then whenever the form's rendered height settles after a change. Useful to avoid inner scrollbars |
mintcash:wallet | { wallet, available } | Wallet-only pages only: once per wallet shown, when the page knows whether that wallet works on the customer's device |
mintcash:progress | { stage: "started" } | Once per checkout, when the customer commits to paying: card form submit, a wallet button tap or authorisation, or a bank tile tap |
A page opened with a view adds it to every message, for example "view": "card,wallets", so you can tell apart several frames of one payment. Without a view the messages are unchanged.
mintcash:progress is optional to handle. It arrives before any 3DS challenge or bank page, so use it to keep the frame mounted and lock your own UI until a mintcash:checkout result arrives. That matters most for subscriptions, whose status stays created until the first charge settles, so polling your server can't tell you the customer has started paying.
The standalone Apple Pay button also sends mintcash:wallet:start when the customer taps it, and expects a mintcash:wallet:session reply from your page. Its guide covers that exchange.
mintcash:checkout statuses, and what to do with each:
status | ok | What happened | What to do |
|---|---|---|---|
succeeded | true | The charge was confirmed (directly, or after a 3DS challenge) | Close the modal, show your confirmation. Wait on the webhook to fulfil |
pending | false | The attempt is settling asynchronously — in flight, not failed. For a bank payment that's still open after the page's waiting window, the page keeps watching and may post its final status later | Keep the session open; your webhook delivers the final outcome |
declined | false | The provider declined the charge, or a bank refused the payment before the customer reached it | Show a failure state and finish the session |
failed | false | Verification (3DS) failed, or the bank refused the payment after the customer reached it | Show a failure state and finish the session |
expired | false | The session is no longer active | Show a failure state and finish the session |
cancelled | false | The customer closed the Apple Pay sheet without paying (wallet-only pages and the standalone button), or, sent once on load, the page has nothing to offer. A page narrowed by view stays silent instead, since your other frames may still be payable | Unlock your page. Nothing was charged. After a closed sheet the customer can tap again; otherwise offer another way to pay |
Delivery details worth knowing:
- Messages are posted only to the origins registered on your merchant account (plus your localhost page for test-mode payments) — never broadcast with
*. Checkevent.originanyway; other scripts on your page can post messages too. - Expect
mintcash:resizeto fire multiple times per session.mintcash:checkoutarrives once per attempt outcome; a bank payment reported aspendingmay send its final status later, so rely on the webhook for the outcome. After a terminal status (declined,failed,expired) no further messages follow for that session. - In standalone (redirect) mode nothing is posted — the messages exist only when the page is framed.
Treat the postMessage as a UI signal only — update your page, close the modal, show your own confirmation. Fulfilment still happens exclusively on the webhook — payment.succeeded for one-time payments, subscription.succeeded for subscriptions.
Make it look like yours
The framed page picks up your merchant account's theme automatically — accent colour and its ink, page background, body text, font, panel padding, and the input fields' colours, labels, and borders, down to the button ring and error colours. Play with the knobs below to see how the embedded checkout would look on your site, then copy the resulting theme and send it to your account manager to apply it.
saveCardEnabled.See also
- Accept a one-time payment — the flow behind the framed page
- Set up a subscription — first charges collected on the same page
- Choose what the checkout offers —
methods,view, and one payment across several frames - Accept APMs — the bank tab, the return flow and what the customer sees
- Customise the payment page — theming and fully custom checkouts