@capgo/capacitor-pay

Capacitor plugin to trigger native payments with Apple Pay and Google Pay using a unified JavaScript API.

Documentation

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

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

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

# 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.

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: {
      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);
}

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.

API

• isPayAvailable(...)
• requestPayment(...)
• 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.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | PayAvailabilityOptions |

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.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | PayPaymentOptions |

Returns: Promise<PayPaymentResult>

getPluginVersion()

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

Get the native Capacitor plugin version

Returns: Promise<{ version: string; }>

Interfaces

PayAvailabilityResult

| Prop | Type | | --------------- | ----------------------------------------------------------------------------------- | | available | boolean | | platform | PayPlatform | | apple | ApplePayAvailabilityResult | | google | GooglePayAvailabilityResult |

ApplePayAvailabilityResult

| Prop | Type | Description | | ---------------------------------- | -------------------- | ------------------------------------------------------------------------------------ | | canMakePayments | boolean | Indicates whether the device can make Apple Pay payments in general. | | canMakePaymentsUsingNetworks | boolean | Indicates whether the device can make Apple Pay payments with the supplied networks. |

GooglePayAvailabilityResult

| Prop | Type | Description | | ------------- | -------------------- | ------------------------------------------------------------------------------ | | isReady | boolean | Indicates whether the Google Pay API is available for the supplied parameters. |

PayAvailabilityOptions

| Prop | Type | | ------------ | ------------------------------------------------------------------------------------- | | apple | ApplePayAvailabilityOptions | | google | GooglePayAvailabilityOptions |

ApplePayAvailabilityOptions

| Prop | Type | Description | | ----------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | supportedNetworks | ApplePayNetwork[] | Optional list of payment networks you intend to use. Passing networks determines the return value of canMakePaymentsUsingNetworks. |

GooglePayAvailabilityOptions

| Prop | Type | Description | | ------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | environment | GooglePayEnvironment | Environment used to construct the Google Payments client. Defaults to 'test'. | | isReadyToPayRequest | GooglePayIsReadyToPayRequest | Raw IsReadyToPayRequest JSON as defined by the Google Pay API. Supply the card networks and auth methods you intend to support at runtime. |

GooglePayIsReadyToPayRequest

Typed helper for the Google Pay IsReadyToPayRequest JSON. The native Android implementation still accepts arbitrary JSON (forward compatible).

| Prop | Type | Description | | --------------------------- | -------------------------------------------- | ------------------------------------------------------------ | | allowedPaymentMethods | GooglePayAllowedPaymentMethod[] | The list of payment methods you want to check for readiness. |

GooglePayAllowedPaymentMethod

| Prop | Type | | ------------------------------- | ----------------------------------------------------------------------------------------------------- | | type | (string & Record<never, never>) | 'CARD' | | parameters | GooglePayCardPaymentMethodParameters | | tokenizationSpecification | GooglePayTokenizationSpecification |

GooglePayCardPaymentMethodParameters

| Prop | Type | | ------------------------------ | ----------------------------------------------------------------------------------------------- | | allowedAuthMethods | GooglePayAuthMethod[] | | allowedCardNetworks | GooglePayCardNetwork[] | | billingAddressRequired | boolean | | billingAddressParameters | GooglePayBillingAddressParameters |

GooglePayBillingAddressParameters

| Prop | Type | | ------------------------- | ------------------------------------------------------------------------------------------- | | format | 'MIN' | 'FULL' | (string & Record<never, never>) | | phoneNumberRequired | boolean |

GooglePayTokenizationSpecification

| Prop | Type | | ---------------- | --------------------------------------------------------------------------------------------------------- | | type | (string & Record<never, never>) | 'PAYMENT_GATEWAY' | 'DIRECT' | | parameters | Record<string, string> |

PayPaymentResult

| Prop | Type | | -------------- | ------------------------------------------------------------------------------------------------ | | platform | Exclude<PayPlatform, 'web'> | | apple | ApplePayPaymentResult | | google | GooglePayPaymentResult |

ApplePayPaymentResult

| Prop | Type | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | paymentData | string | Raw payment token encoded as base64 string. | | paymentString | string | Raw payment token JSON string, useful for debugging. | | transactionIdentifier | string | Payment transaction identifier. | | paymentMethod | { displayName?: string; network?: ApplePayNetwork; type: 'credit' | 'debit' | 'prepaid' | 'store'; } | | | shippingContact | ApplePayContact | | | billingContact | ApplePayContact | |

ApplePayContact

| Prop | Type | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | { givenName?: string; familyName?: string; middleName?: string; namePrefix?: string; nameSuffix?: string; nickname?: string; } | | emailAddress | string | | phoneNumber | string | | postalAddress | { street?: string; city?: string; state?: string; postalCode?: string; country?: string; isoCountryCode?: string; subAdministrativeArea?: string; subLocality?: string; } |

GooglePayPaymentResult

| Prop | Type | Description | | ----------------- | ---------------------------------------------------------------- | ------------------------------------ | | paymentData | Record<string, unknown> | Payment data returned by Google Pay. |

PayPaymentOptions

| Prop | Type | | ------------ | --------------------------------------------------------------------------- | | apple | ApplePayPaymentOptions | | google | GooglePayPaymentOptions |

ApplePayPaymentOptions

| Prop | Type | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | merchantIdentifier | string | Merchant identifier created in the Apple Developer portal. | | countryCode | string | Two-letter ISO 3166 country code. | | currencyCode | string | Three-letter ISO 4217 currency code. | | paymentSummaryItems | ApplePaySummaryItem[] | Payment summary items displayed in the Apple Pay sheet. | | supportedNetworks | ApplePayNetwork[] | Card networks to support. | | merchantCapabilities | ApplePayMerchantCapability[] | Merchant payment capabilities. Defaults to ['3DS'] when omitted. | | requiredShippingContactFields | ApplePayContactField[] | Contact fields that must be supplied for shipping. | | requiredBillingContactFields | ApplePayContactField[] | Contact fields that must be supplied for billing. | | shippingType | ApplePayShippingType | Controls the shipping flow presented to the user. | | supportedCountries | string[] | Optional ISO 3166 country codes where the merchant is supported. | | applicationData | string | Optional opaque application data passed back in the payment token. | | recurringPaymentRequest | ApplePayRecurringPaymentRequest | Recurring payment configuration (iOS 16+). |

ApplePaySummaryItem

| Prop | Type | | ------------ | --------------------------------------------------------------------------- | | label | string | | amount | string | | type | ApplePaySummaryItemType |

ApplePayRecurringPaymentRequest

| Prop | Type | Description | | -------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | paymentDescription | string | A description for the recurring payment shown in the Apple Pay sheet. | | regularBilling | ApplePayRecurringPaymentSummaryItem | The recurring billing item (for example your subscription). | | managementURL | string | URL where the user can manage the recurring payment (cancel, update, etc). | | billingAgreement | string | Optional billing agreement text shown to the user. | | tokenNotificationURL | string | Optional URL where Apple can send token update notifications. | | trialBilling | ApplePayRecurringPaymentSummaryItem | Optional trial billing item (for example a free trial period). |

ApplePayRecurringPaymentSummaryItem

| Prop | Type | Description | | ------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | intervalUnit | ApplePayRecurringPaymentIntervalUnit | Unit of time between recurring payments. | | intervalCount | number | Number of intervalUnit units between recurring payments (for example 1 month, 2 weeks). | | startDate | string | number | Start date of the recurring period. On supported platforms this may be either: - a number representing milliseconds since Unix epoch, or - a string in a date format accepted by the native implementation (for example an ISO 8601 date-time string or a yyyy-MM-dd date string). | | endDate | string | number | End date of the recurring period. On supported platforms this may be either: - a number representing milliseconds since Unix epoch, or - a string in a date format accepted by the native implementation (for example an ISO 8601 date-time string or a yyyy-MM-dd date string). |

GooglePayPaymentOptions

| Prop | Type | Description | | ------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | environment | GooglePayEnvironment | Environment used to construct the Google Payments client. Defaults to 'test'. | | paymentDataRequest | GooglePayPaymentDataRequest | Raw PaymentDataRequest JSON as defined by the Google Pay API. Provide transaction details, merchant info, and tokenization parameters. |

GooglePayPaymentDataRequest

Typed helper for the Google Pay PaymentDataRequest JSON. The native Android implementation still accepts arbitrary JSON (forward compatible).

| Prop | Type | Description | | --------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------- | | apiVersion | number | Google Pay API version, typically 2. | | apiVersionMinor | number | Google Pay API minor version, typically 0. | | allowedPaymentMethods | GooglePayAllowedPaymentMethod[] | Allowed payment method configurations. | | merchantInfo | GooglePayMerchantInfo | Merchant information displayed in the Google Pay sheet. | | transactionInfo | GooglePayTransactionInfo | Transaction details (amount, currency, etc). |

GooglePayMerchantInfo

| Prop | Type | | ------------------ | ------------------- | | merchantId | string | | merchantName | string |

GooglePayTransactionInfo

| Prop | Type | | ---------------------- | ------------------------------------------------------------------------------- | | totalPriceStatus | GooglePayTotalPriceStatus | | totalPrice | string | | currencyCode | string | | countryCode | string |

Type Aliases

PayPlatform

'ios' | 'android' | 'web'

ApplePayNetwork

'AmEx' | 'amex' | 'Bancomat' | 'Bancontact' | 'PagoBancomat' | 'CarteBancaire' | 'CarteBancaires' | 'CartesBancaires' | 'ChinaUnionPay' | 'Dankort' | 'Discover' | 'discover' | 'Eftpos' | 'Electron' | 'Elo' | 'girocard' | 'Himyan' | 'Interac' | 'iD' | 'Jaywan' | 'JCB' | 'jcb' | 'mada' | 'Maestro' | 'maestro' | 'MasterCard' | 'masterCard' | 'Meeza' | 'Mir' | 'MyDebit' | 'NAPAS' | 'BankAxept' | 'PostFinanceAG' | 'PrivateLabel' | 'QUICPay' | 'Suica' | 'Visa' | 'visa' | 'VPay' | 'vPay'

GooglePayEnvironment

'test' | 'production'

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

GooglePayAuthMethod

'PAN_ONLY' | 'CRYPTOGRAM_3DS' | (string & Record<never, never>)

GooglePayCardNetwork

'AMEX' | 'DISCOVER' | 'JCB' | 'MASTERCARD' | 'VISA' | (string & Record<never, never>)

Exclude

Exclude from T those types that are assignable to U

T extends U ? never : T

ApplePaySummaryItemType

'final' | 'pending'

ApplePayMerchantCapability

'3DS' | 'credit' | 'debit' | 'emv'

ApplePayContactField

'emailAddress' | 'name' | 'phoneNumber' | 'postalAddress'

ApplePayShippingType

'shipping' | 'delivery' | 'servicePickup' | 'storePickup'

ApplePayRecurringPaymentIntervalUnit

'day' | 'week' | 'month' | 'year'

GooglePayTotalPriceStatus

'NOT_CURRENTLY_KNOWN' | 'ESTIMATED' | 'FINAL' | (string & Record<never, never>)