@capgo/capacitor-pay

Accept Apple Pay and Google Pay in your Capacitor app with one JavaScript API, using the native payment sheets.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-pay in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-pay to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Availability: isPayAvailable() checks if the device can pay with your networks.
• Native sheet: requestPayment() presents Apple Pay or Google Pay and returns a structured result with the payment data.
• Apple Pay options: merchant identifier, supported networks, capabilities and contact fields.
• Google Pay options: test or production environment, card networks, and gateway or direct tokenization.
• Platforms: iOS and Android. iOS uses PassKit, Android uses Google Pay through Play services. Not available on web.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/pay/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-pay` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

# Install (choose one)
npm install @capgo/capacitor-pay
pnpm add @capgo/capacitor-pay
yarn add @capgo/capacitor-pay
bun add @capgo/capacitor-pay

# Then sync Capacitor (choose one)
npx cap sync
pnpm exec cap sync
yarn cap sync
bunx cap sync

Platform setup

Before invoking the plugin, complete the native configuration documented in this repository:

• Apple Pay (iOS): see docs/apple-pay-setup.md for merchant ID creation, certificates, Xcode entitlements, and device testing.
• Google Pay (Android): follow docs/google-pay-setup.md to configure the business profile, tokenization settings, and runtime JSON payloads.

Finish both guides once per app to unlock the native payment sheets on devices.

Google Pay request and response types are bundled with this plugin, so you do not need to install @types/googlepay unless you also use Google's web JavaScript client elsewhere in your app.

Usage

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

// Check availability on the current platform.
const availability = await Pay.isPayAvailable({
  apple: {
    supportedNetworks: ['visa', 'masterCard', 'amex'],
  },
  google: {
    // Optional: falls back to a basic CARD request if omitted.
    isReadyToPayRequest: {
      apiVersion: 2,
      apiVersionMinor: 0,
      allowedPaymentMethods: [
        {
          type: 'CARD',
          parameters: {
            allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
            allowedCardNetworks: ['AMEX', 'DISCOVER', 'MASTERCARD', 'VISA'],
          },
        },
      ],
    },
  },
});

if (!availability.available) {
  // Surface a friendly message or provide an alternative checkout.
  return;
}

if (availability.platform === 'ios') {
  const result = await Pay.requestPayment({
    apple: {
      merchantIdentifier: 'merchant.com.example.app',
      countryCode: 'US',
      currencyCode: 'USD',
      supportedNetworks: ['visa', 'masterCard'],
      paymentSummaryItems: [
        { label: 'Example Product', amount: '19.99' },
        { label: 'Tax', amount: '1.60' },
        { label: 'Example Store', amount: '21.59' },
      ],
      requiredShippingContactFields: ['postalAddress', 'name', 'emailAddress'],
    },
  });
  console.log(result.apple?.paymentData);
} else if (availability.platform === 'android') {
  const result = await Pay.requestPayment({
    google: {
      environment: 'test',
      paymentDataRequest: {
        apiVersion: 2,
        apiVersionMinor: 0,
        allowedPaymentMethods: [
          {
            type: 'CARD',
            parameters: {
              allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
              allowedCardNetworks: ['AMEX', 'DISCOVER', 'MASTERCARD', 'VISA'],
              billingAddressRequired: true,
              billingAddressParameters: {
                format: 'FULL',
              },
            },
            tokenizationSpecification: {
              type: 'PAYMENT_GATEWAY',
              parameters: {
                gateway: 'example',
                gatewayMerchantId: 'exampleGatewayMerchantId',
              },
            },
          },
        ],
        merchantInfo: {
          merchantId: '01234567890123456789',
          merchantName: 'Example Merchant',
        },
        transactionInfo: {
          totalPriceStatus: 'FINAL',
          totalPrice: '21.59',
          currencyCode: 'USD',
          countryCode: 'US',
        },
      },
    },
  });

  console.log(result.google.paymentData);
  // Process the payment token on your backend server here.
}

Recurring payments

Apple Pay has first-class support via recurringPaymentRequest (iOS 16+):

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(),
      },
    },
  },
});

Google Pay does not have a dedicated "recurring request" object in PaymentDataRequest. For subscriptions you typically:

1. Collect a token once with a normal paymentDataRequest.
2. Store it server-side and create recurring charges with your PSP/gateway (Stripe/Adyen/Braintree/etc).

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

const paymentDataRequest: GooglePayPaymentDataRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [
    {
      type: 'CARD',
      parameters: {
        allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
        allowedCardNetworks: ['AMEX', 'DISCOVER', 'MASTERCARD', 'VISA'],
      },
      tokenizationSpecification: {
        type: 'PAYMENT_GATEWAY',
        parameters: {
          gateway: 'example',
          gatewayMerchantId: 'exampleGatewayMerchantId',
        },
      },
    },
  ],
  merchantInfo: {
    merchantId: '01234567890123456789',
    merchantName: 'Example Merchant',
  },
  transactionInfo: {
    totalPriceStatus: 'FINAL',
    totalPrice: '9.99',
    currencyCode: 'USD',
    countryCode: 'US',
  },
};

const result = await Pay.requestPayment({
  google: {
    environment: 'test',
    paymentDataRequest,
  },
});

// Send `result.google.paymentData` to your backend and use your PSP to start the subscription.

requestPayment() is the completion path on both platforms.

Shipping methods (Apple Pay)

Pass shippingMethods to let the user choose how the order is delivered, for example home delivery or pickup in a store. The first method is selected by default. When the user changes the address or the method, the sheet waits until you answer with updateApplePayShipping(), passing the selectionId of the event. Answer every event, also when your own lookup fails; without an update within 20 seconds the sheet reports the selection as failed. When the methods have different amounts, the applePayShippingMethodSelected listener is required:

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

const deliveryMethods = [
  { identifier: 'home', label: 'Home delivery', amount: '4.95', startDate: '2026-10-16', endDate: '2026-10-17' },
  { identifier: 'store', label: 'Pick up in store', amount: '0.00', detail: 'Ready tomorrow' },
];

await Pay.addListener('applePayShippingContactSelected', async (contact) => {
  // Apple only shares city, postal code and country until the payment is authorized
  // An empty `shippingMethods` array marks the address as unserviceable
  const shippingMethods = await getShippingMethodsFor(contact.postalAddress?.isoCountryCode);
  await Pay.updateApplePayShipping({
    selectionId: contact.selectionId,
    paymentSummaryItems: getSummaryItems(shippingMethods[0]),
    shippingMethods,
  });
});

await Pay.addListener('applePayShippingMethodSelected', async (shippingMethod) => {
  await Pay.updateApplePayShipping({
    selectionId: shippingMethod.selectionId,
    paymentSummaryItems: getSummaryItems(shippingMethod),
  });
});

const result = await Pay.requestPayment({
  apple: {
    merchantIdentifier: 'merchant.com.example.app',
    countryCode: 'NL',
    currencyCode: 'EUR',
    supportedNetworks: ['visa', 'masterCard'],
    requiredShippingContactFields: ['postalAddress', 'name', 'emailAddress'],
    shippingMethods: deliveryMethods,
    paymentSummaryItems: getSummaryItems(deliveryMethods[0]),
  },
});

// `result.apple.shippingMethod` is the method the user selected

API

• isPayAvailable(...)
• requestPayment(...)
• updateApplePayShipping(...)
• addListener('applePayShippingContactSelected', ...)
• addListener('applePayShippingMethodSelected', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces
• Type Aliases

isPayAvailable(...)

isPayAvailable(options?: PayAvailabilityOptions | undefined) => Promise<PayAvailabilityResult>

Checks whether native pay is available on the current platform. On iOS this evaluates Apple Pay, on Android it evaluates Google Pay.

Returns: Promise<PayAvailabilityResult>

requestPayment(...)

requestPayment(options: PayPaymentOptions) => Promise<PayPaymentResult>

Presents the native pay sheet for the current platform. Provide the Apple Pay configuration on iOS and the Google Pay configuration on Android.

This promise is the completion path on both platforms.

Returns: Promise<PayPaymentResult>

updateApplePayShipping(...)

updateApplePayShipping(options: ApplePayShippingUpdate) => Promise<void>

Answers the latest applePayShippingContactSelected or applePayShippingMethodSelected event with new totals and, for a new address, new shipping methods. iOS only.

The Apple Pay sheet waits for this call, so call it once for every event you listen to, also when your own lookup fails. Without an update within 20 seconds, the sheet reports the selection as failed.

addListener('applePayShippingContactSelected', ...)

addListener(eventName: 'applePayShippingContactSelected', listenerFunc: (contact: ApplePayShippingContactSelectedEvent) => void) => Promise<PluginListenerHandle>

Called when the user selects or changes the shipping address in the Apple Pay sheet. iOS only.

Until the payment is authorized, Apple only shares a redacted address (city, state, postal code and country). The sheet waits until you call updateApplePayShipping(). Without a listener the sheet keeps its current totals.

Returns: Promise<PluginListenerHandle>

addListener('applePayShippingMethodSelected', ...)

addListener(eventName: 'applePayShippingMethodSelected', listenerFunc: (shippingMethod: ApplePayShippingMethodSelectedEvent) => void) => Promise<PluginListenerHandle>

Called when the user selects another shipping method in the Apple Pay sheet. iOS only.

The sheet waits until you call updateApplePayShipping(). Without a listener the sheet keeps its current totals, so this listener is required when the shipping methods have different amounts.

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Removes all listeners for this plugin.

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version

Returns: Promise<{ version: string; }>

Interfaces

PayAvailabilityResult

ApplePayAvailabilityResult

GooglePayAvailabilityResult

PayAvailabilityOptions

ApplePayAvailabilityOptions

GooglePayAvailabilityOptions

GooglePayIsReadyToPayRequest

Self-contained Google Pay request type based on the official request objects and DefinitelyTyped definitions.

The plugin forwards the provided JSON to the native Google Pay SDK on Android, while keeping the type surface local so consumers do not need to install @types/googlepay.

GooglePayAllowedPaymentMethod

GooglePayCardPaymentMethodParameters

GooglePayBillingAddressParameters

GooglePayCardNetworkParameters

GooglePayGatewayTokenizationSpecification

GooglePayPaymentGatewayTokenizationParameters

Tokenization parameters for PAYMENT_GATEWAY tokenization, which sends the payment data to a supported third-party gateway for tokenization and processing.

GooglePayDirectTokenizationSpecification

GooglePayDirectTokenizationParameters

GooglePayCustomTokenizationSpecification

ApplePayRequestPaymentResult

ApplePayPaymentResult

ApplePayContact

ApplePayShippingMethod

GooglePayRequestPaymentResult

GooglePayPaymentResult

GooglePayPaymentData

GooglePayAddress

GooglePayPaymentMethodData

GooglePayCardInfo

GooglePayAssuranceDetails

GooglePayPaymentMethodTokenizationData

GooglePayOfferData

GooglePaySelectionOptionData

PayPaymentOptions

ApplePayPaymentOptions

ApplePaySummaryItem

ApplePayRecurringPaymentRequest

ApplePayRecurringPaymentSummaryItem

GooglePayPaymentOptions

GooglePayPaymentDataRequest

Self-contained Google Pay payment request type based on the official request objects and DefinitelyTyped definitions.

The plugin forwards the provided JSON to the native Google Pay SDK on Android, while keeping the type surface local so consumers do not need to install @types/googlepay.