Overview
This guide covers Apple Pay integration for Bolt Embeddable Checkout.
The Bolt React Native SDK provides an ApplePay component that renders a native PKPaymentButton on iOS. On Android, the component renders nothing.
Apple Pay supports two modes:
| Mode | Description | Entitlement Required? |
|---|---|---|
webview (default) |
Uses the Bolt-hosted Apple Pay iframe for merchant validation and tokenization. | No |
native |
Uses the native PassKit payment sheet directly on device. | Yes |
WebView Mode (Default)
WebView mode is the simplest way to get started — no Apple Pay entitlement or merchant certificate setup is required. Bolt handles merchant validation and tokenization server-side.
import { ApplePay } from '@boltpay/react-native/payments';
function CheckoutScreen() {
return (
<ApplePay
config={{
countryCode: 'US',
currencyCode: 'USD',
total: { label: 'Your Store', amount: '9.99' },
}}
referrer="https://your-store.example.com"
buttonType="buy"
buttonStyle="black"
onComplete={(result) => {
// result: { token, bin?, expiration?, billingContact?, boltReference? }
}}
onError={(error) => console.error(error)}
/>
);
}
NOTE
The referrer prop is required in WebView mode. This must be the merchant website URL registered with both Bolt and Apple for merchant validation to succeed.
Native Mode
If you need the native PassKit payment sheet, set mode="native". This requires your app to have the Apple Pay entitlement configured with your Apple-registered merchant identifier.
WARNING
The merchantId in native mode is not your Bolt publishable key — it is the identifier you register in the Apple Developer portal.
Xcode Setup
Open your app target in Xcode:
- Go to Signing & Capabilities.
- Click + Capability.
- Select Apple Pay.
- Check your merchant ID.
Expo Setup
Add the following to your app.json:
{
"ios": {
"entitlements": {
"com.apple.developer.in-app-payments": ["merchant.com.yourapp"]
}
}
}
Then re-run expo prebuild and rebuild your app.
Usage
<ApplePay
mode="native"
config={{
merchantId: 'merchant.com.yourapp',
countryCode: 'US',
currencyCode: 'USD',
total: { label: 'Your Store', amount: '9.99' },
}}
buttonType="buy"
onComplete={(result) => { /* ... */ }}
/>
Props Reference
| Prop | Type | Default | Description |
|---|---|---|---|
config |
ApplePayConfig |
required | Country/currency, total amount, and optional merchant ID (mode='native' only). |
onComplete |
(ApplePayResult) => void |
required | Called with token, bin, expiration, and billing contact on success. |
onError |
(Error) => void |
— | Called on payment failure. |
mode |
'webview' | 'native' |
'webview' |
'webview' uses the Bolt-hosted iframe (no entitlement needed). 'native' uses PassKit. |
buttonType |
ApplePayButtonType |
'plain' |
Button label variant. Auto-localized by Apple. |
buttonStyle |
'black' | 'white' | 'whiteOutline' |
'black' |
Button color theme. |
referrer |
string |
— | Merchant website URL registered with Bolt and Apple. Required for WebView mode. |
style |
ViewStyle |
— | Container style overrides (height, margin, etc.). |
ApplePayButtonType Values
'plain', 'buy', 'checkout', 'book', 'subscribe', 'donate', 'order', 'setUp', 'inStore', 'reload', 'addMoney', 'topUp', 'rent', 'support', 'contribute', 'tip'
ApplePayResult
{
token: string;
bin?: string;
expiration?: string;
billingContact?: object;
boltReference?: string;
}