Skip to content
This repository has been archived by the owner on Feb 8, 2024. It is now read-only.

Latest commit

 

History

History
681 lines (446 loc) · 60 KB

README.md

File metadata and controls

681 lines (446 loc) · 60 KB
Raw

@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 @fresha/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(...)

initialize(paymentOptions: PaymentOptions) => Promise<void>

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

Param Type Description
paymentOptions PaymentOptions - An object containing environment type that should be used.

isReadyToPay(...)

isReadyToPay(request: IsReadyToPayRequest) => Promise<IsReadyToPayResponse>

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

Param Type Description
request IsReadyToPayRequest - Contains supported payment methods

Returns: Promise<IsReadyToPayResponse>

loadPaymentData(...)

loadPaymentData(request: PaymentDataRequest) => Promise<PaymentData>

Initiates a payment base on PaymentDataRequest object.

Param Type Description
request PaymentDataRequest - PaymentDataRequest object that will be used for the payment.

Returns: Promise<PaymentData>

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",
}
Prop Type Description Default
environment Environment This value specifies which Google Pay environment to target "TEST"

IsReadyToPayResponse

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

Prop Type Description
result boolean Whether the user is able to provide payment information through the Google Pay payment sheet. 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 IsReadyToPayRequest.allowedPaymentMethods.
paymentMethodPresent boolean The current user's ability to pay with one or more of the payment methods specified in IsReadyToPayRequest.allowedPaymentMethods This property only exists if IsReadyToPayRequest.existingPaymentMethodRequired was set to true. The property value will always be true if the PaymentsClient is configured for a test environment.

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.

Prop Type Description Default
apiVersion number Major API version. For this specification's version, this value should be 2. Make sure this matches PaymentDataRequest.apiVersion so the isReadyToPay client method can correctly check whether the specified API version is supported for the current context. This field is required.
apiVersionMinor number Minor API version. For this specification's version, this value should be 0. Make sure this matches PaymentDataRequest.apiVersionMinor so the isReadyToPay client method can correctly check whether the specified API version is supported for the current context. This field is required.
allowedPaymentMethods IsReadyToPayPaymentMethodSpecification[] List of allowed payment methods. This field is required and must contain at least one allowed payment method. Check each filtering criteria within the payment method's parameters field to see if the properties within are applicable for IsReadyToPayRequest.
existingPaymentMethodRequired boolean If set to true then the IsReadyToPayResponse.paymentMethodPresent property will be populated with a boolean indicating the current user's ability to pay with one or more of the payment methods specified in IsReadyToPayRequest.allowedPaymentMethods false

IsReadyToPayPaymentMethodSpecification

Specification of accepted payment method for use in isReadyToPay.

Prop Type Description
type PaymentMethodType Type of payment method. This field is required.
parameters CardParameters Payment method parameters. The parameters set here affect which payment methods will be available for the user to choose from.
tokenizationSpecification 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.

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.

Prop Type Description Default
allowedAuthMethods CardAuthMethod[] Allowed authentication methods. This field specifies what set of fields or your gateway/processor supports for authenticating a card transaction. Please note that some of your processor's capabilities may vary by market, so consult your processor to determine the authentication forms they support. In general, you should list/support as many authentication methods possible as to increase the chances that a user will be able to complete a purchase. Not all cards support all authentication methods, so the more methods you or your processor support the better. This field is required.
allowedCardNetworks CardNetwork[] Allowed card networks. This field specifies what set of card networks your gateway/processor supports for a card transaction. Note: Some cards may contain multiple brands and be processed across different networks. In particular when TransactionInfo.countryCode is set to "BR", users will be prompted to choose whether to process the transaction over a debit network or credit network, and you should use this field to know which network to process the transaction with. For all other markets, this field will be set to a suggestion of a card network to use for processing, but you or your processor may choose to use different rails. This card network value should not be displayed. This field is required.
allowPrepaidCards boolean Whether a prepaid card may be used for this transaction. If omitted, defaults to true. true
allowCreditCards boolean Whether a credit card may be used for this transaction. If omitted, defaults to true. true
assuranceDetailsRequired boolean Set to true to request assuranceDetails. If omitted, defaults to false. You may set if you need object provides information about the validation performed on the returned payment data. false
billingAddressRequired boolean Whether a billing address is required from the buyer. If omitted, defaults to false. Note: you should only set this field to true when billing address 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. false
billingAddressParameters BillingAddressParameters Optional billing address parameters. If omitted, the default values specified in BillingAddressParameters will be assumed.
cardNetworkParameters CardNetworkParameters[] List of card network parameters. This field is optional. You may set it when network specific parameters are needed to complete a transaction.

BillingAddressParameters

Optional billing address parameters for the returned billing address.

Prop Type Description Default
format BillingAddressFormat Billing address format. If omitted, defaults to BillingAddressFormat.MIN. Note: you should only set format to BillingAddressFormat.FULL 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.
phoneNumberRequired boolean Whether billing phone number required. If omitted, defaults to false. Note: you should only set this to true when a phone number 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. false

CardNetworkParameters

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

This should only be set for PaymentMethodType.CARD.

Prop Type Description
cardNetwork CardNetwork Type of card network parameters. Currently only CardNetwork.VISA and CardNetwork.MASTERCARD are supported. This field is required.
acquirerBin string Acquiring institution identification code as assigned by the DS receiving the AReq message for the given card network. This is an optional field. We recommend setting this field to allow SCA challenges to be done for the given card network.
acquirerMerchantId string Acquirer-assigned Merchant identifier for VISA. This is an optional field. We recommend setting this field to allow SCA challenges to be done for the given card network.

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.

Prop Type Description
type 'PAYMENT_GATEWAY' The type of payment method tokenization to apply to the selected payment method.
parameters PaymentGatewayTokenizationParameters Specific parameters used for payment gateway tokenization.

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.

Prop Type Description
type 'DIRECT' The type of payment method tokenization to apply to the selected payment method.
parameters DirectTokenizationParameters Specific parameters used for direct tokenization.

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:

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

Prop Type Description
protocolVersion string The version of the encryption/signature protocol being used. This field is required when the payment method requires encryption. Unless you were already using an older protocolVersion, you should be using the latest version defined in https://developers.google.com/pay/api/web/payment-data-cryptography.
publicKey string Elliptic Curve public key suitable for using with the NIST P-126 curve. This public key will be used to encrypt the sensitive payment method information. This field is required when the payment method requires encryption.

PaymentData

Payment data.

Contains the payment data requested in PaymentDataRequest

Prop Type Description
apiVersion number Major API version. This value will match what was set in PaymentDataRequest.apiVersion.
apiVersionMinor number Minor API version. This value will match what was set in PaymentDataRequest.apiVersionMinor.
email string The buyer's email. This value will only be set if PaymentDataRequest.emailRequired was set to true.
shippingAddress Address The shipping address. This object will only be returned if PaymentDataRequest.shippingAddressRequired was set to true.
paymentMethodData PaymentMethodData Data about the selected payment method.

Address

Description of a user's address.

Prop Type Description Default
name string Name of the recipient at this address.
address1 string The first line of the address. Will be set to empty string if the address does not have a first line. ""
address2 string The second line of the address. Will be set to empty string if the address does not have a second line. ""
address3 string The third line of the address. Will be set to empty string if the address does not have a third line. ""
locality string The locality (e.g. city or town).
administrativeArea string The administrative area (e.g. state or province).
countryCode string The two-letter ISO-3166 country code.
postalCode string The postal code (also known in some places as ZIP code). Note: some regions do not have postal codes. In those cases this field will be set to an empty string.
sortingCode string The sorting code. Note: some regions do not have sorting codes. In those cases this field will be set to an empty string.
phoneNumber string The phone number. This field will only be present if the caller requested that a phone number be returned.

PaymentMethodData

Data for a payment method.

Prop Type Description
type PaymentMethodType Type of payment method.
info CardInfo Payment method information. The definition of this field depends on which payment method type was set in PaymentMethodData. - For PaymentMethodType.CARD, this field will be an object conforming to CardInfo.
description string User-facing message to describe the payment method funding this transaction. You are required to show this message to the buyer as confirmation of their funding source. Please refer to the documentation for more information. IMPORTANT: Do not attempt to parse the contents of this string as the format, contents, and length may change at any time. If you need additional details, see PaymentMethodData.info.
tokenizationData PaymentMethodTokenizationData Tokenization data for the payment method.

CardInfo

Data for a PaymentMethodType.CARD payment method.

Prop Type Description
assuranceDetails AssuranceDetails
cardNetwork CardNetwork The card network. This card network value should not be displayed to the buyer, but can be used when the details of a buyer's card are needed. An example would be for customer support to help the buyer identify the card used for this transaction. For a user-visible description, use PaymentMethodData.description instead.
cardDetails string The details about the card. This value will be generally the last 4 digits of the card. These details should not be displayed to the buyer, but can be used when the details of a buyer's card are needed. An example would be for customer support to help the buyer identify the card used for this transaction. For a user-visible description, use PaymentMethodData.description instead.
billingAddress Address The billing address associated with the card. Note this billing address will only be populated when billing address is set as required through CardParameters.billingAddressRequired.

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.

Prop Type Description
accountVerified boolean If true, indicates that Cardholder possession validation has been performed on returned payment credential.
cardHolderAuthenticated boolean If true, indicates that identification and verifications (ID&V) was performed on the returned payment credential. If false, the same risk-based authentication can be performed as you would for card transactions. This risk-based authentication can include, but not limited to, step-up with 3D Secure protocol if applicable.

PaymentMethodTokenizationData

Tokenization data for the payment method.

Prop Type Description
type PaymentMethodTokenizationType The type of tokenization to be applied to the selected payment method. This value will match the PaymentMethodTokenizationSpecification.type specified in the request.
token string The generated payment method token. The contents of this token and how it should be used will depend on the selected PaymentMethodTokenizationSpecification.type.

PaymentDataRequest

Request for payment data.

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

Prop Type Description Default
merchantInfo MerchantInfo Detailed merchant information. This field is required.
apiVersion number Major API version. For this specification's version, this value should be 2. This field is required.
apiVersionMinor number Minor API version. For this specification's version, this value should be 0. This field is required.
emailRequired boolean Whether to collect the email from the buyer. The returned email can be retrieved from PaymentData.email If omitted, defaults to false. false
shippingAddressRequired boolean Whether a shipping address is required from the buyer. The returned shipping address can be retrieved from Address. If omitted, defaults to false. false
shippingAddressParameters ShippingAddressParameters Optional shipping address parameters. If omitted, the default values specified in ShippingAddressParameters will be assumed.
allowedPaymentMethods PaymentMethodSpecification[] List of allowed payment methods. This field is required and must contain at least one PaymentMethodSpecification.
transactionInfo TransactionInfo Detailed information about the transaction. This field is required.

MerchantInfo

Detailed information about the merchant.

Prop Type Description
merchantName string A user visible merchant name. This name may be shown to the user in Google Pay to describe who the user made a transaction with. This field is optional. If not set, the Business name in your Google Pay Developer Profile will be used.

ShippingAddressParameters

Optional shipping address parameters for the returned shipping address.

Prop Type Description Default
allowedCountryCodes string[] Allowed country codes for the shipping address. This list should be an array of ISO 3166-1 alpha-2 country codes (e.g., ["US", "CA", "JP"]). If omitted, a shipping address from any supported country may be returned.
phoneNumberRequired boolean Whether a phone number is additionally required from the buyer for the shipping address (the phone number will only be returned if an address is required, otherwise this field has no effect). If omitted, defaults to false. false

PaymentMethodSpecification

Specification of accepted payment method for use in loadPaymentData.

Prop Type Description
type PaymentMethodType Type of payment method. This field is required.
parameters CardParameters Payment method parameters. The parameters set here affect which payment methods will be available for the user to choose from.
tokenizationSpecification 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.

TransactionInfo

Detailed information about the transaction.

Prop Type Description Default
transactionId string Correlation ID to refer to this transaction. This field is optional. It is generated by the merchant and is used for referring to this transaction later on (e.g. for debugging issues when communicating with Google).
currencyCode string ISO 4217 alphabetic currency code of the transaction. This is a required field.
countryCode string ISO 3166-1 alpha-2 country code for the country where the transaction will be completed/processed. This is an optional field. We recommend setting this field to allow country-specific customizations (for example, in some countries we may need to provide extra information to you or your processor in order to complete a transaction).
totalPrice string Total price of this transaction. The format of this string should follow the regular expression format: [0-9]+(\.[0-9][0-9])? (e.g., "10.45") This field is required if CheckoutOption.TransactionInfo.totalPriceStatus is set to TotalPriceStatus.ESTIMATED or TotalPriceStatus.FINAL.
totalPriceLabel string Total price label of this transaction. The string will be shown as the total price label on the cart modal dialog page. This field is optional, but required if developer wants to show cart information. Otherwise, the cart modal dialog will not be rendered even if transactionInfo.displayItems is set.
totalPriceStatus TotalPriceStatus Status of this transaction's total price. This field is required. Note: some payment methods require that this field be set to [TotalPriceStatus|FINAL] and that the total price to be specified and final.
checkoutOption CheckoutOption Optional checkout option parameter. Whether to use the 'Continue' or the 'Pay Now' button for a buy flow. If omitted, defaults to CheckoutOption.DEFAULT and renders the 'Continue' button for a buy flow. "DEFAULT"

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:

    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

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'

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'