@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/

Install

npm install @capgo/capacitor-pay
npx 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);
}

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 | Record<string, unknown> | Raw IsReadyToPayRequest JSON as defined by the Google Pay API. Supply the card networks and auth methods you intend to support at runtime. |

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

ApplePaySummaryItem

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

GooglePayPaymentOptions

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

Type Aliases

PayPlatform

'ios' | 'android' | 'web'

ApplePayNetwork

'amex' | 'chinaUnionPay' | 'discover' | 'eftpos' | 'electron' | 'girocard' | 'interac' | 'jcb' | 'mada' | 'maestro' | 'masterCard' | 'privateLabel' | 'quicPay' | 'suica' | 'visa' | 'vPay' | 'id' | 'cartesBancaires'

GooglePayEnvironment

'test' | 'production'

Record

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

{ [P in K]: T; }

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'