Accept Apple Pay

MintCash supports Apple Pay wherever the underlying provider does. How you integrate depends on the Payment Provider abilities. This guide walks through what it requires of you, the integration path, and what to consider during testing.

Before you start

Complete the setup of your Apple Pay developer account first — Apple Merchant ID and merchant identity certificate. In case you work with a Payment Provider that have it set up for you, you just need to collect those IDs for us. Then, provide the credentials to your account manager and that's it. All the configuration will happen on MintCash side, and because the Apple Pay button renders on our Hosted Payment Page, domain verification is handled on our domain.

Integration

Once your account manager configures your account, the Apple Pay button is rendered on the Hosted Payment Page by default (default or customized HPP). Every one-time payment you create via the API will display the option to proceed with Apple Pay through our platform. Decryption can happen on the provider's side or ours, depending on the provider's capabilities. The integration you write is the same either way.

1. You create the payment; we respond with the redirectUrl.
2. The payment page displays the available payment methods, including Apple Pay.
3. Apple Pay authenticates the customer and returns the encrypted payment data, which we pass to the provider.
4. If the issuer requires extra verification (3DS or OTP), the customer completes it in place on the page.
5. We send the webhook to your callbackUrl with the final state.

Apple Pay-only checkout

If you already collect card payments elsewhere, or simply want a one-tap page, you can ask for a payment page that offers only Apple Pay. Set applePayOnly: true when you create the payment:

const r = await fetch("https://sandbox.mintcash.me/payments", {
  method: "POST",
  headers: {
    Authorization: `Basic ${btoa(`${publicKey}:${secretKey}`)}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalId: orderId,
    amount: 49.99,
    currency: "USD",
    applePayOnly: true,
    customer: {
      externalId: customerId,
      email: customer.email,
      name: customer.name,
    },
  }),
});

const { redirectUrl } = await r.json();

The flag applies to that payment alone, so you can run both versions side by side: payments created without it keep the standard page. Everything else about the integration stays the same, whether you redirect or embed the page: same redirectUrl, same 3DS handling, same webhooks.

On an Apple Pay-only page:

• Only the Apple Pay button is shown. The card form, Google Pay, billing fields and the save-card option are all hidden.
• Unsupported devices get a clear message. If the browser can't make Apple Pay payments (for example Chrome on Windows, or a device with no card in Wallet), the page says Apple Pay isn't available and asks the customer to open it in Safari on an Apple device, instead of showing an empty checkout.
• Cancelling isn't final. If the customer closes the Apple Pay sheet, the page tells them they haven't been charged and they can tap the button again.
• Declines and errors show the same feedback as the standard page.

Embedded Apple Pay-only pages

When the page is embedded in an iframe, it sends two extra signals so your page can react:

• A mintcash:wallet message, once, as soon as it knows whether Apple Pay is available on this device. Use it to hide the frame and show your own payment options when available is false.
• A mintcash:checkout message with status cancelled when the customer closes the Apple Pay sheet without paying. The session stays open, so they can tap again.

window.addEventListener("message", (event) => {
  if (event.origin !== MINTCASH_CHECKOUT_ORIGIN) return;
  const msg = event.data;
  if (msg?.type === "mintcash:wallet" && msg.wallet === "apple_pay") {
    if (!msg.available) showOtherPaymentOptions();
  }
  if (msg?.type === "mintcash:checkout" && msg.status === "cancelled") {
    unlockYourCheckout(); // nothing was charged
  }
});

Standalone Apple Pay button

You can also place a single Apple Pay button on your own checkout, next to your existing payment options, before any payment exists. The payment is only created once the customer taps the button, so you don't create payments for customers who never pick Apple Pay.

The button is an Apple Pay-only page you embed in an iframe, so it needs your embed origins registered (see Embed the checkout). It doesn't work as a redirect.

const r = await fetch("https://sandbox.mintcash.me/wallet-buttons", {
  method: "POST",
  headers: {
    Authorization: `Basic ${btoa(`${publicKey}:${secretKey}`)}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 49.99, currency: "USD" }),
});

const { token, url, expiresAt } = await r.json();

<iframe src="{{url}}" width="100%" height="80" frameborder="0" allow="payment"></iframe>

window.addEventListener("message", async (event) => {
  if (event.origin !== MINTCASH_CHECKOUT_ORIGIN) return;
  const msg = event.data;
  if (msg?.type !== "mintcash:wallet:start") return;

  lockYourCheckout(); // the Apple Pay sheet is open
  try {
    // Your endpoint calls POST /payments with walletToken: token
    const { checkoutToken } = await createPaymentOnYourServer(orderId);
    event.source.postMessage(
      { type: "mintcash:wallet:session", requestId: msg.requestId, sessionToken: checkoutToken },
      event.origin,
    );
  } catch {
    event.source.postMessage(
      { type: "mintcash:wallet:session", requestId: msg.requestId, error: "refused" },
      event.origin,
    );
  }
});

body: JSON.stringify({
  externalId: orderId,
  amount: 49.99, // must match the button
  currency: "USD", // must match the button
  walletToken: token,
  customer: { externalId: customerId, email: customer.email, name: customer.name },
}),

What to test

Run each flow you plan to ship in sandbox before going live, on Safari for both iOS and macOS:

• Happy path: an Apple Pay authorisation that lands on payment.succeeded.
• 3DS challenge: confirm the challenge renders and finalises successfully.
• Webhook delivery: confirm your endpoint receives the final event.
• Cancel: close the Apple Pay sheet and confirm the customer can try again (and, if embedded, that you receive cancelled).
• Unsupported browser: if you use the Apple Pay-only page or the standalone button, open it in a browser without Apple Pay (for example Chrome on Windows) and confirm the fallback works.
• Standalone button: confirm a second tap reuses the same payment, and that an error answer unlocks your checkout.