Apple Pay Setup Guide

February 9, 2026 · View on GitHub

This document walks through the steps required to enable Apple Pay in a project that uses @capgo/capacitor-pay. Complete every step before calling the plugin at runtime.

1. Accounts and prerequisites

Enroll in the Apple Developer Program using the same Apple ID that signs your iOS builds.
Ensure your app bundle identifier is reserved in App Store Connect.
Use Xcode 14 or newer, and install the latest iOS SDK.

2. Create a Merchant ID

Open Apple Developer > Certificates, Identifiers & Profiles.
In Identifiers, click the plus button and choose Merchant IDs.
Enter a description and a unique identifier following the pattern merchant.com.yourcompany.app.
Save the identifier. This Merchant ID will later be referenced in code as merchantIdentifier.

3. Add and verify the Apple Pay capability in Xcode

Open the iOS workspace or the Capacitor iOS project in Xcode.
Select the App target, open the Signing & Capabilities tab, and click + Capability.
Choose Apple Pay, then attach the merchant IDs you created earlier. Xcode adds them to the entitlements file automatically.
Expand the capability to confirm the Supported Networks list reflects the brands you plan to enable (for example, VISA, MasterCard, AmEx).
Xcode creates an entitlements file next to your target (typically App/App.entitlements) that contains the com.apple.developer.in-app-payments key. Open the file to verify every merchant identifier expected by the app is present:
```
<key>com.apple.developer.in-app-payments</key>
<array>
  <string>merchant.com.example.app</string>
</array>
```
If you ship extensions (widgets, watch apps, or app clips) that also present Apple Pay, repeat the capability assignment on each target so the entitlement is available everywhere.
Build the project for a real device once to refresh provisioning profiles. The Xcode status message under General → Signing should report that the signing certificate is valid; if not, re-download the profiles associated with the merchant IDs.

4. Generate the payment processing certificate

In the developer portal, open the Merchant ID details.
Under Payment Processing Certificate, click Create Certificate.
Download the certificate signing request (.certSigningRequest) generated by Xcode (Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority).
Upload the CSR, download the resulting certificate, and double-click it to add it to your keychain.
Export the certificate as a .cer file and keep it for your payment service provider if required.

5. Configure the payment processor or gateway

Most processors request the Merchant ID and the payment processing certificate. Provide:

Merchant identifier (e.g., merchant.com.yourcompany.app)
Business legal name and contact information
The .cer file generated in the previous step

Follow your processor’s onboarding steps to complete tokenization.

6. Verify domain association (if applicable)

If your payment processor requires Apple Pay on the web, add your site domain in the developer portal and upload the apple-developer-merchantid-domain-association file to https://<domain>/.well-known/.

7. Backend session validation

Your server must broker the merchant validation handshake before the device can show the Apple Pay sheet:

Listen for the validation URL emitted by the plugin. On iOS this arrives during the onvalidatemerchant phase of PKPaymentAuthorizationController.
From your backend send a POST request to https://apple-pay-gateway.apple.com/paymentservices/startSession including your merchant identifier, domain name, and display name. Sign the request with the merchant identity certificate created in step 5.
Return the Apple session JSON directly to the device. The plugin forwards it to PassKit to complete the handshake.
Keep the session ephemeral—log minimal metadata for auditing and never store the session payload itself.

8. Update the Capacitor project

In Pay.requestPayment, set merchantIdentifier to the Merchant ID created earlier.
Provide a list of networks (supportedNetworks) that matches the networks approved by your processor.
Include realistic summary items and ensure the total is a final amount.

Recurring payments (subscriptions)

This plugin supports Apple Pay recurring payments on iOS 16+ via recurringPaymentRequest.

Key points:

You still provide paymentSummaryItems (what’s shown in the sheet).
The recurring metadata is provided via recurringPaymentRequest.
If you pass recurringPaymentRequest on iOS 15 or earlier, the plugin rejects the call.

Example:

import { Pay } from '@capgo/capacitor-pay';

await Pay.requestPayment({
  apple: {
    merchantIdentifier: 'merchant.com.example.app',
    countryCode: 'US',
    currencyCode: 'USD',
    supportedNetworks: ['visa', 'masterCard'],
    paymentSummaryItems: [
      { label: 'Pro Plan', amount: '9.99' },
      { label: 'Example Store', amount: '9.99' },
    ],
    recurringPaymentRequest: {
      paymentDescription: 'Pro Plan Subscription',
      managementURL: 'https://example.com/account/subscription',
      regularBilling: {
        label: 'Pro Plan',
        amount: '9.99',
        intervalUnit: 'month',
        intervalCount: 1,
        startDate: Date.now(),
      },
    },
  },
});

9. Build and test on device

Apple Pay is unavailable on the iOS simulator. Use a real device signed into an Apple ID with a supported card in Wallet.
Install the build via Xcode or TestFlight.
Trigger Pay.isPayAvailable() to ensure the device reports available: true.
Call Pay.requestPayment and verify that the Apple Pay sheet loads and returns a payment token.

10. Move to production

Disable the sandbox merchant environment in your processor dashboard once you’re ready for production.
Rebuild the app using distribution certificates and submit the build for App Review.
Provide Apple with sample test accounts or screenshots showing the Apple Pay flow, if requested.

After these steps the Capacitor plugin can successfully authorize payments using Apple Pay.