Apple Pay

The Apple Pay component (fs-apple-pay) renders Apple's official Apple Pay button inside a secure iframe served from FastSpring's domain. When the buyer clicks it, a FastSpring-hosted window opens where they review the order and complete the payment.

This page is the complete reference for the Apple Pay component: when it appears, how to mount it, the options it accepts, and how to style it. For setup context, see the Integration Guide.

When the button appears

The button appears only when both of the following are true:

The browser supports Apple Pay

Safari on macOS or iOS.

Apple Pay is enabled for your store

It must be turned on as a payment method in your store settings.

If either condition isn't met, the component renders nothing, takes no space, and other payment methods take over. No error is shown, so you can mount it on every checkout.

Mount

Add a target element to your HTML:

<div id="apple-pay-element"></div>

Then create the component from your sdk instance and mount it:

const applePayComponent = sdk.components.create('fs-apple-pay', {
    // options + style go here
});

applePayComponent.mount('#apple-pay-element');

Component options

Top-level options passed alongside style:

Option	Type	Default	Description
`variant`	`'black'` \| `'white'`	`'black'`	Button color, the only color choice Apple permits. `'black'` suits light checkouts; use `'white'` on dark ones. The white button has no border, so it blends into a white background.
`frame`	`{ width, maxWidth }`	see `frame`	The component's own box: width and cap. A layout option, so it sits beside `style`, not inside it.

`frame`: the component's size

Property	Type	Default	Description
`width`	`string`	`100%`	Component width. Fills the container you mount it into.
`maxWidth`	`string`	`680px`	Caps the component width on wide screens. Every component uses the same value. `'none'` removes the cap.

What happens during payment

Your page is dimmed while Apple Pay is open

The SDK adds a gray overlay to prevent a second checkout from starting. It's removed automatically when the window closes, the buyer abandons the payment, or the payment completes. Clicking the overlay closes the Apple Pay window and restores the checkout.

Declines are shown in the window

If the payment is declined, the window shows "This transaction has been declined. Please use a different payment method or contact your bank." and stays open, so the buyer can try again.

Same callbacks as card payments

A successful payment fires onOrderCompleted, and a decline fires onPaymentFailed, using the callbacks you pass to FastSpring.init().

Styling

Apple draws the button, so the stylable surface is small: the variant option for color, frame for width, and two button properties for height and corner radius.

sdk.components.create('fs-apple-pay', {
    style: {
        state: {
            default: {
                button: { /* height, borderRadius */ },
            },
        },
    },
});

Only the default state, and no globalStyles

Apple renders the button's hover and press feedback natively, so only default is wired; overrides under other state keys are ignored. The component also takes nothing from globalStyles; set its styles directly.

`button`: the Apple Pay button

Maps onto Apple's public CSS custom properties for the real <apple-pay-button>. Width comes from frame; the button always fills it.

Property	Type	Default	Description
`height`	`string`	`48px`	Button height. Apple permits a minimum of `30px`.
`borderRadius`	`string`	`4px`	Corner radius. Apple permits 0 to 50% of the height.

Full example

sdk.components.create('fs-apple-pay', {
    variant: 'white',
    frame: { width: '100%', maxWidth: '480px' },
    style: {
        state: {
            default: {
                button: { height: '56px', borderRadius: '10px' },
            },
        },
    },
}).mount('#apple-pay-element');