This guide shows you how to check wallet availability, mount the Apple Pay and Google Pay buttons, and handle payment results and express-checkout address changes.
Both wallets must be enabled for your workflow on the Payrails side; the buttons draw their configuration (supported networks, merchant capabilities, gateway parameters) from the init response.
1. Check availability
Only render a wallet button when the shopper’s browser and device support it:
Both return a promise resolving to true or false. Alternatively, construct the button first and read its own capability check — every express button exposes readonly isAvailable: Promise<boolean>:
The button’s isAvailable uses the same underlying check and never rejects (resolves to false on any check-side failure).
Other options worth knowing:
showStoreInstrumentCheckbox / defaultStoreInstrumentState — render a “save for future payments” checkbox under the button.
redirectFor3DS and returnInfo — control how a 3D Secure redirect returns to your site.
- The environment (
TEST / PRODUCTION) is resolved from the server-provided SDK configuration passed into Payrails.init(initResponse).
Notes:
- When the shopper cancels the Apple Pay sheet, the
failed event fires with data.code === 'USER_CANCELLED' so you can distinguish cancellation from a real failure.
abortAfterAuthorizeFailed: true closes the sheet on authorization failure instead of showing Apple’s inline failure state.
showStoreInstrumentCheckbox works the same way as for Google Pay.
The success/failed/pending events are shared with all other payment elements — one listener covers the whole session; filter by e.paymentMethodCode as shown above.
4. Validate the delivery address in express checkout (Apple Pay)
When your Apple Pay configuration requires shipping contact fields, the SDK forwards address changes from the payment sheet to the instance-level deliveryAddressChanged event. Call event.preventDefault() to reject the address (the sheet shows “Delivery to this address is not supported.” and asks the shopper to pick another); do nothing to accept it:
Keep this handler fast — Apple aborts the sheet if it is not answered within roughly 30 seconds, so use it for region/ZIP checks rather than a full cart recompute. The full, unredacted address only becomes available after the shopper authorizes the payment. The same event also fires for PayPal express checkout (with PayPal’s payload shape). Last modified on September 18, 2026