zeply.googlepay-capacitor-plugin v1.0.2

zeply.googlepay-capacitor-plugin

@fresha/capacitor-plugin-googlepay

This Google Pay plugin provides interfaces that allow you to initiate a Google Pay payment sheet based on provided PaymentOptions. When transaction is authorized, PaymentData response is returned along with payment details and more importantly- a payment token that you should pass to your backend.

The API is a subset of Google Pay for Web. Necessary typescript types has been extracted from DefinitelyTyped/googlepay.

The docs for payload scheme are available at Google Pay docs.

Install

npm install @zeply.capacitor-plugin-googlepay
npx cap sync

Configuration

Before using this plugin, make sure that your project is correctly configured. Usually your Payment Services Processor will provide detailed instructions, so please read their docs first. The plugin configures your AndroidManifest.xml automatically with the following meta entry:

<meta-data
android:name="com.google.android.gms.wallet.api.enabled"
android:value="true"
/>

Testing

To test the integration, use Google's Test Cards Suite: Google Tutorial

API

• initialize(...)
• isReadyToPay(...)
• loadPaymentData(...)
• Interfaces
• Type Aliases

initialize(...)

initialize(paymentOptions: PaymentOptions) => any

Initiates a Google Pay client along with environment configuration. This function should be called once: before using the plugin.

Returns: any

isReadyToPay(...)

isReadyToPay(request: IsReadyToPayRequest) => any

Indicates whether the device supports Google Pay and whether the user has an allowed payment method.

Returns: any

loadPaymentData(...)

loadPaymentData(request: PaymentDataRequest) => any

Initiates a payment base on PaymentDataRequest object.

Returns: any

Interfaces

PaymentOptions

Configure this object for a production environment once you've tested your implementation and you're ready to receive payments from shoppers.

Example:

{
  environment: "TEST",
}

IsReadyToPayRequest

Request for the user's ability to display the Google Pay payment sheet and provide at least one of the payment methods specified.

A user's ability to pay may be tied to the capabilities of the current context (browser/device) to display required components for the specified payment methods including logging in to a Google Account and providing one of the payment methods specified in IsReadyToPayRequestallowedPaymentMethods

Optionally provides a signal if one or more of the specified payment methods exists for the current user.

IsReadyToPayPaymentMethodSpecification

Specification of accepted payment method for use in isReadyToPay.

CardParameters

Parameters for PaymentMethodType.CARD.

The parameters specified here affect which payment methods are available for users to choose from. For example, the list of supported card networks can be filtered by setting the CardParameters.allowedCardNetworks property.

BillingAddressParameters

Optional billing address parameters for the returned billing address.

CardNetworkParameters

Parameters for card networks that can be used in this request.

This should only be set for PaymentMethodType.CARD.

PaymentGatewayTokenizationSpecification

Payment gateway tokenization parameters.

These parameters will be used to tokenize/transmit the payment method returned to you in a format you can charge or reference.

PaymentGatewayTokenizationParameters

Specific tokenization parameters used for PaymentMethodTokenizationType.PAYMENT_GATEWAY

This object will generally have the following format:

{
  "gateway": "nameOfTheGateway",
  "param1": "value1",
  "param2": "value2",
  ...
}

The specific keys that you must set will depend on the gateway you have specified. Please consult your gateway or processor documentation on which parameters must be specified in this object.

All values must be strings.

DirectTokenizationSpecification

Direct tokenization parameters.

These parameters will be used to tokenize/transmit the direct payment method returned to you in a format you can charge or reference.

DirectTokenizationParameters

Specific tokenization parameters used for PaymentMethodTokenizationType.DIRECT.

Depending on the payment method you may be required to receive the sensitive data in an encrypted and signed format.

Currently the following payment methods require encryption:

• PaymentMethodType.CARD

See Payment data cryptography for more information on how to perform signature verification and decryption of a payment response.

IsReadyToPayResponse

Information about a user's ability to provide payment information through the Google Pay payment sheet.

PaymentDataRequest

Request for payment data.

Contains several options to describe which information is being requested and how it will be transferred.

MerchantInfo

Detailed information about the merchant.

ShippingAddressParameters

Optional shipping address parameters for the returned shipping address.

PaymentMethodSpecification

Specification of accepted payment method for use in loadPaymentData.

TransactionInfo

Detailed information about the transaction.

PaymentData

Payment data.

Contains the payment data requested in PaymentDataRequest

Address

Description of a user's address.

PaymentMethodData

Data for a payment method.

CardInfo

Data for a PaymentMethodType.CARD payment method.

AssuranceDetails

Assurance details about what validation has been performed on the returned payment credentials so that appropriate instrument risk checks can be applied.

Note: If both cardHolderAuthenticated and accountVerified are true, you don’t need to step up the returned credentials. If both aren’t, we recommend you to run the same risk checks and , authentication including 3D Secure flow if applicable.

PaymentMethodTokenizationData

Tokenization data for the payment method.

Type Aliases

Environment

Supported environment names to run Google Pay.

Options:

• PRODUCTION: Used to return chargeable payment methods when a valid Google merchant ID is specified and configured for the domain.

• TEST: Dummy payment methods that are suitable for testing (default).

'PRODUCTION' | 'TEST'

PaymentMethodType

Payment method type enum string.

Options:

• CARD: CARD payment method.

  Note that the payment method information that may be returned to you or your processor for a credit card transaction is meant to be used only once. If you need to charge the user again you must call the APIs to obtain new payment credentials.

  Also note that when we transfer information like PAN (personal account number) to either you or your gateway/processor, they may not correspond to the user's physical card. For support purposes, please use user's card info returned in CardInfo|CardInfo instead.

• PAYPAL: PAYPAL payment method.

'CARD' | 'PAYPAL'

CardAuthMethod

Card authentication method enum string.

Options:

• PAN_ONLY: Authenticate using a PAN (personal account number) only.

  Note: in addition to the PAN (personal account number) there will also be an expiration month and year.

  If you are using PaymentMethodTokenizationType.PAYMENT_GATEWAY, you will not need to handle this sensitive data as it will be delivered to your gateway.

  Warning: do not rely on the PAN returned being stable or being able to be used to reauthorize new transactions as the PAN is meant for one-time use only. Authorization for new transactions may fail if you reuse the credential across unrelated transactions.

• CRYPTOGRAM_3DS: Authenticate using the 3-D Secure (3DS) cryptogram.

  Note: in addition to the 3DS cryptogram there will also be an associated PAN (personal account number), expiration month and year, and Electronic Commerce Indicator for certain card networks.

  If you are using PaymentMethodTokenizationType.PAYMENT_GATEWAY, you will not need to handle this sensitive data as it will be delivered to your gateway.

  Warning: do not rely on the PAN returned being stable or being able to be used to reauthorize new transactions as the PAN and associated 3DS cryptogram are meant for one-time use only. Authorization for new transactions may fail if you reuse the credential across unrelated transactions.

'PAN_ONLY' | 'CRYPTOGRAM_3DS'

CardNetwork

Card network enum string.

Options:

• AMEX: American Express card network.

• DISCOVER: Discover card network.

• ELECTRON: Visa's Electron card network.

  Note that this option can only be set when TransactionInfo.countryCode is set to "BR", and CardParameters.allowedCardNetworks must also contain CardNetwork.VISA

  For processing purposes, you should use this as an indication that the card must be processed through the Electron debit network.

• ELO: Elo card network.

  Note that this option can only be set when TransactionInfo.countryCode is set to "BR".

• ELO_DEBIT: Elo's debit network rail.

  Note that this option can only be set when TransactionInfo.countryCode is set to "BR", and CardParameters.allowedCardNetworks must also contain CardNetwork.ELO

  For processing purposes, you should use this as an indication that the card must be processed through the ELO debit network.

• INTERAC: Interac card network.

• JCB: JCB card network.

• MAESTRO: Maestro card network.

  Note that this option can only be set when TransactionInfo.countryCode is set to "BR", and CardParameters.allowedCardNetworks must also contain CardNetwork.MASTERCARD

  For processing purposes, you should use this as an indication that the card must be processed through the Maestro debit network.

• MASTERCARD: Mastercard card network.

• VISA: Visa card network.

'AMEX' | 'DISCOVER' | 'ELECTRON' | 'ELO' | 'ELO_DEBIT' | 'INTERAC' | 'JCB' | 'MAESTRO' | 'MASTERCARD' | 'VISA'

BillingAddressFormat

Billing address format enum string.

Options:

• MIN: Minimal billing address

  When this format is used, the billing address returned will only contain the following fields:

  • Address.name
  • Address.countryCode
  • Address.postalCode
  • Address.phoneNumber if BillingAddressParameters.phoneNumberRequired is set to true.

  Note: some countries do not use postal codes. The postal code field will be empty in those countries.

• FULL: Full billing address

  All the fields in Address|Address will be returned, with the possible exception of Address.phoneNumber which will only be returned if BillingAddressParameters.phoneNumberRequired is set to true.

  Only select this format when it is required to process the order. Additional form entry or customer data requests can increase friction during the checkout process and can lead to a lower conversion rate.

'MIN' | 'FULL'

PaymentMethodTokenizationSpecification

Tokenization parameters.

These parameters will be used to tokenize/transmit the payment method returned to you in a format you can charge or reference.

PaymentGatewayTokenizationSpecification | DirectTokenizationSpecification

TotalPriceStatus

The status of the total price used.

Options:

• NOT_CURRENTLY_KNOWN: The total price is not known currently.

• ESTIMATED: The total price provided is an estimated price. The final price may change depending on the selected shipping address or billing address, if requested.

• FINAL: The total price is the final total price of the transaction, and will not change based on selections made by the buyer.

'NOT_CURRENTLY_KNOWN' | 'ESTIMATED' | 'FINAL'

CheckoutOption

The options for checkout.

Options:

• DEFAULT: The default option for checkout. Use the 'Continue' button for a buy flow in the payments sheet. Once loadPaymentData completes, the integrator should show an order confirmation screen to finalize the purchase.

• COMPLETE_IMMEDIATE_PURCHASE: Use the 'Pay' button to indicate a buy flow without a confirmation in the payments sheet to indicate that no further confirmation will be shown and the transaction will be processed once the user confirms only if TransactionInfo.totalPriceStatus is set to TotalPriceStatus.FINAL. Otherwise, a payment data request will fail.

'DEFAULT' | 'COMPLETE_IMMEDIATE_PURCHASE'

PaymentMethodTokenizationType

Payment method tokenization type enum string.

Options:

• PAYMENT_GATEWAY: Tokenize a payment response to be consumed or charged by a specified third-party gateway service.

• DIRECT: Tokenize to be consumed/charged directly by the merchant.

'PAYMENT_GATEWAY' | 'DIRECT'