Object reference

Options for using the Google Pay API.

Request objects

PaymentOptions

Configure for a production environment once you have tested your implementation and are ready to receive payments from shoppers.

Property Type Necessity Description
environment string optional
  • PRODUCTION: return chargeable methods of payment when a valid Google merchant ID is specified and configured for the domain
  • TEST: dummy payment methods returned suitable for testing (default)

Example

Request non-chargeable payment methods suitable for testing.

{
  environment: 'TEST'
}

IsReadyToPayRequest

Specify supported payment methods.

Property Type Necessity Description
apiVersion number required Major API version. For this specification's version this value should be 2.
apiVersionMinor number required Minor API version. For this specification's version this value should be 0.
allowedPaymentMethods PaymentMethod[] required

Specify support for one or more payment methods supported by the Google Pay API.

A tokenizationSpecification is not required to determine a viewer's readiness to pay. Provide all required parameters properties for each supported PaymentMethod.

existingPaymentMethodRequired boolean optional

If set to true then the IsReadyToPayResponse object will include an additional property describing the visitor's readiness to pay with one or more payment methods specified in allowedPaymentMethods.

Example

Support payment cards and Android device tokens from all supported card networks.

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
      }
    }
  ]
}

PaymentDataRequest

Configure your site's support for the Google Pay API.

Property Type Necessity Description
apiVersion number required Major API version. For this specification's version this value should be 2.
apiVersionMinor number required Minor API version. For this specification's version this value should be 0.
merchantInfo MerchantInfo required Information about the merchant requesting payment data.
allowedPaymentMethods PaymentMethod[] required Specify support for one or more payment methods supported by the Google Pay API.
transactionInfo TransactionInfo required Details about the transaction to be authorized including total price and price status.
emailRequired boolean optional Set to true to request an email address.
shippingAddressRequired boolean optional Set to true to request a full shipping address.
shippingAddressParameters ShippingAddressParameters optional If shippingAddressRequired set to true, specify shipping address restrictions.

Example

Support payment cards and Android device tokens from all supported card networks, tokenized through an example gateway. Request a payment method to charge a final amount of 12.34 United States dollars.

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "merchantInfo": {
    "merchantName": "Example Merchant"
  },
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
      },
      "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "example",
          "gatewayMerchantId": "exampleGatewayMerchantId"
        }
      }
    }
  ],
  "transactionInfo": {
    "totalPriceStatus": "FINAL",
    "totalPrice": "12.34",
    "currencyCode": "USD"
  }
}

MerchantInfo

Information about the merchant requesting payment data.

Property Type Necessity Description
merchantId string required A Google merchant identifier issued after your website is approved by Google. Required when PaymentsClient is initialized with an environment property of PRODUCTION. See Integration checklist for more information about the approval process and obtaining a Google merchant identifier.
merchantName string optional A user-visible merchant name encoded as UTF-8. This name may be shown to the user in the Google Pay payment sheet to describe the merchant requesting payment data.

Example

An example merchant name.

{
  "merchantName": "Example Merchant"
}

PaymentMethod

One or more payment methods supported by the Google Pay API and accepted by your website.

Property Type Necessity Description
type string required A short identifier for the supported payment method. Currently only CARD is supported.
parameters object required Parameters required to configure the provided payment method type. See CardParameters for more information about expected values for the CARD payment method.
tokenizationSpecification PaymentMethodTokenizationSpecification optional

Configure an account or decryption provider to receive payment information.

This property is required for the CARD payment method.

This property has no effect if included as part of an IsReadyToPayRequest.

Example

Support payment cards and Android device tokens from all supported card networks. Tokenize through an example gateway.

{
  "type": "CARD",
  "parameters": {
    "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
    "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
  },
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "example",
      "gatewayMerchantId": "exampleGatewayMerchantId"
    }
  }
}

PaymentMethodTokenizationSpecification

Configure an account to receive chargeable payment information.

Property Type Necessity Description
type string required A payment method tokenization type supported for the given PaymentMethod. For CARD payment method use PAYMENT_GATEWAY or DIRECT.
parameters object required Parameters specific to the selected payment method tokenization type.

Gateway

Set type to PAYMENT_GATEWAY to retrieve payment and customer information from a payment gateway supported by the Google Pay API. Define parameters properties as described by your gateway; typical properties include the gateway's identifier issued by Google and your gateway account ID provided by your gateway.

Example
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "example",
    "gatewayMerchantId": "exampleGatewayMerchantId"
  }
}
ACI
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "aciworldwide",
    "gatewayMerchantId": "YOUR_ENTITY_ID"
  }
}
Adyen
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "adyen",
    "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME"
  }
}
Braintree
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "braintree",
    "braintree:apiVersion": "v1",
    "braintree:sdkVersion": braintree.client.VERSION,
    "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID",
    "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY"
  }
}
Checkout.com
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "checkoutltd",
    "gatewayMerchantId": "YOUR_PUBLIC_KEY"
  }
}
CyberSource
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "cybersource",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"
  }
}
Datatrans
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "datatrans",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"
  }
}
EBANX
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "ebanx",
    "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY"
  }
}
First Data
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "firstdata",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"
  }
}
Global Payments
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "globalpayments",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"
  }
}
IMSolutions
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "imsolutions",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"
  }
}
Paysafe
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "paysafe",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"
  }
}
Przelewy24
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "przelewy24",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"
  }
}
RBKmoney
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "rbkmoney",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"
  }
}
Sberbank
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "sberbank",
    "gatewayMerchantId": "YOUR_ORGANIZATION_NAME"
  }
}
Stripe
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "stripe",
    "stripe:version": Stripe.version,
    "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"
  }
}
Vantiv
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "vantiv",
    "vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID",
    "vantiv:merchantOrderId": "YOUR_ORDER_ID",
    "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID",
    "vantiv:merchantReportGroup": "*web"
  }
}
Worldpay
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "worldpay",
    "gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID"
  }
}
Yandex
"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "yandexcheckout",
    "gatewayMerchantId": "YOUR_SHOP_ID"
  }
}

Direct

Set type to DIRECT to decrypt a response directly on your servers. This configuration has additional data security requirements from Google and additional PCI DSS compliance complexity.

Property Type Necessity Description
protocolVersion string required The version of the encryption / signature protocol expected in the response. Currently only ECv1 is supported. See Payment data cryptography for more information about available encryption and signature protocols.
publicKey string required Base64-encoded elliptic curve public key. See the encryption public key format section in our merchant cryptography documentation for more information.
Example

The example publicKey value is abbreviated for readability.

"tokenizationSpecification": {
  "type": "DIRECT",
  "parameters": {
    "protocolVersion": "ECv1",
    "publicKey": "BOdoXP1aiNp.....kh3JUhiSZKHYF2Y="
  }
}

CardParameters

Define the payment card types you accept. Google will filter a payer's available payment cards based on your configured options.

Property Type Necessity Description
allowedAuthMethods string[] required

Fields supported to authenticate a card transaction.

  • PAN_ONLY: this authentication method is associated with payment cards stored on file with the user's Google Account. Returned payment data includes personal account number (PAN) with expiration month and year.
  • CRYPTOGRAM_3DS: this authentication method is associated with cards stored as Android device tokens. Returned payment data includes a 3-D Secure (3DS) cryptogram generated on the device.
allowedCardNetworks string[] required

One or more card networks you support also supported by the Google Pay API.

  • AMEX
  • DISCOVER
  • JCB
  • MASTERCARD
  • VISA
allowPrepaidCards boolean optional Set to false if you don't support prepaid cards. Default: the prepaid card class is supported for the card networks specified.
billingAddressRequired boolean optional Set to true if you require a billing address. A billing address should only be requested if required to process the transaction as additional data requests can increase friction during the checkout process and can lead to a lower conversion rate.
billingAddressParameters BillingAddressParameters optional The expected fields returned if billingAddressRequired set to true.

Example

Support all available card networks and card authentication methods.

{
  "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
  "allowedCardNetworks": ["AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"]
}

BillingAddressParameters

Set additional fields to be returned for a requested billing address.

Property Type Necessity Description
format string optional

Billing address format required to complete the transaction.

  • MIN: name, country code, and postal code (default)
  • FULL: name, street address, locality, region, country code, and postal code
phoneNumberRequired boolean optional Set to true if a phone number is required to process the transaction.

Example

Request a minimal version of the billing address, the current default value of the property.

{
  "format": "MIN"
}

ShippingAddressParameters

Set shipping restrictions. If not specified, all shipping addresses are allowed.

Property Type Necessity Description
allowedCountryCodes string[] optional ISO 3166-1 alpha-2 country code values of the countries to which shipping is allowed.
phoneNumberRequired boolean optional Set to true if a phone number is required for the provided shipping address.

Example

Request a shipping address in the United States.

{
  "allowedCountryCodes": ["US"]
}

TransactionInfo

Describe a transaction to determine a payer's ability to pay or to present in a payment authorization dialog.

Property Type Necessity Description
totalPriceStatus string required

The status of the total price used:

  • NOT_CURRENTLY_KNOWN: used for a capability check
  • ESTIMATED: total price may adjust based on the details of the response, such as sales tax collected based on a billing address
  • FINAL: total price will not change from the amount presented to the shopper
totalPrice string optional

Total monetary value of the transaction with an optional decimal precision of two decimal places. This field is required unless totalPriceStatus is set to NOT_CURRENTLY_KNOWN.

The format of the string should follow the regex format: ^[0-9]+(\.[0-9][0-9])?$

currencyCode string optional ISO 4217 alphabetic currency code. This field is required unless totalPriceStatus is set to NOT_CURRENTLY_KNOWN.

Example

A final price in United States dollars.

{
  "totalPriceStatus": "FINAL",
  "totalPrice": "12.34",
  "currencyCode": "USD"
}

ButtonOptions

Configure a Google Pay payment button. See Brand guidelines for more information about button types, colors, and display requirements.

Property Type Necessity Description
onClick function
or
Object
required An event listener callback to be called when a click event is delivered to the <button> target.
buttonColor string optional
  • default: a Google-selected default value. Currently black but may change over time (default)
  • black: a black button suitable for use on white or light backgrounds
  • white: a white button suitable for use on colorful backgrounds
buttonType string optional
  • long: "Buy with Google Pay" button (default). A translated button label may appear if a language specified in the viewer's browser matches an available language
  • short: Google Pay payment button without the "Buy with" text

Example

Generate a Google Pay payment button with a click event handler and default display options.

{
  onClick: onGooglePaymentButtonClicked
}

Response objects

IsReadyToPayResponse

Information about a website visitor's ability to provide payment information to the requesting site.

Property Type Always exists Description
result boolean yes The current visitor is able to provide payment information to the requesting site. A visitor's ability to pay may be tied to the capabilities of the current web browser to display required components for the specified payment methods including logging in to a Google Account and providing a payment method.
paymentMethodPresent boolean no

If true, the visitor has one or more payment methods as specified in the allowedPaymentMethods property of the provided IsReadyToPayRequest.

Exists only when existingPaymentMethodRequired was set to true in IsReadyToPayRequest.

If PaymentsClient is initialized with an environment property of TEST a payment method will be considered always present.

Example

The current visitor is able to provide payment information to the requesting site.

{
  "result": true
}

PaymentData

A response object returned by Google after a payer approves payment.

Property Type Always exists Description
apiVersion number yes Major API version. The value in the response will match the value provided in PaymentDataRequest.
apiVersionMinor number yes Minor API version. The value in the response will match the value provided in PaymentDataRequest.
paymentMethodData PaymentMethodData yes Data about the selected payment method.
email string no Email address, if emailRequired was set to true in the PaymentDataRequest.
shippingAddress Address no Shipping address, if shippingAddressRequired was set to true in the PaymentDataRequest.

Example

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "paymentMethodData": {
    "type": "CARD",
    "description": "Visa •••• 1234",
    "info": {
      "cardNetwork": "VISA",
      "cardDetails": "1234"
    },
    "tokenizationData": {
      "type": "PAYMENT_GATEWAY",
      "token": "examplePaymentMethodToken"
    }
  }
}

PaymentMethodData

Data for a payment method.

Property Type Always exists Description
type string yes PaymentMethod type selected in the Google Pay payment sheet.
description string yes

User-facing message to describe the payment method funding this transaction.

info object yes The value of this property depends on the payment method type returned. For CARD see CardInfo.
tokenizationData PaymentMethodTokenizationData yes Payment tokenization data for the selected payment method.

Example

{
  "type": "CARD",
  "description": "Visa •••• 1234",
  "info": {
    "cardNetwork": "VISA",
    "cardDetails": "1234"
  },
  "tokenizationData": {
    "type": "PAYMENT_GATEWAY",
    "token": "examplePaymentMethodToken"
  }
}

CardInfo

Information about the selected payment card.

Property Type Always exists Description
cardDetails string yes The details about the card. This value is commonly the last four digits of the selected payment account number.
cardNetwork string yes

The payment card network of the selected payment. Returned values match the formatting of allowedCardNetworks in CardParameters.

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 the description property of PaymentMethodData instead.

billingAddress Address no The billing address associated with the provided payment method, if billingAddressRequired was set to true in CardParameters.

Example

{
  "cardNetwork": "VISA",
  "cardDetails": "1234"
}

PaymentMethodTokenizationData

Tokenization data for the payment method.

Property Type Always exists Description
type string yes The type of tokenization to be applied to the selected payment method. This value will match the type set in PaymentMethodTokenizationSpecification.
token string no

The generated payment method token.

Example

{
  "type": "PAYMENT_GATEWAY",
  "token": "examplePaymentMethodToken"
}

Address

Information about a requested postal address. All properties are strings.

A MIN address format may be returned if billingAddressFormat is set to MIN. A shipping address is returned in the FULL address format. All properties in a MIN formatted response exist in a FULL formatted response.

Property Address format Description
name MIN The full name of the addressee.
postalCode MIN The postal or ZIP code.
countryCode MIN ISO 3166-1 alpha-2 country code.
phoneNumber MIN A telephone number, if phoneNumberRequired was set to true in the PaymentDataRequest.
companyName FULL The company name of the addressee.
address1 FULL The first line of the address.
address2 FULL The second line of the address.
address3 FULL The third line of the address.
locality FULL City, town, neighborhood, or suburb.
administrativeArea FULL A country subdivision (e.g. state or province).
sortingCode FULL The sorting code.

Example

{
  "name": "John Doe",
  "address1": "c/o Google LLC",
  "address2": "1600 Amphitheatre Pkwy",
  "address3": "Building 40",
  "locality": "Mountain View",
  "administrativeArea": "CA",
  "countryCode": "US",
  "sortingCode": ""
}

Errors

PaymentsError

Errors returned by client JavaScript methods.

Property Type Description
statusCode string Short code describing the type of error.
statusMessage string Developer-facing message describing the error encountered and possible steps to correct.

Common errors

Errors you may encounter across all JavaScript methods.

Status Code Description
BUYER_ACCOUNT_ERROR The current Google user is unable to provide payment information.
DEVELOPER_ERROR A passed parameter was improperly formatted. An error message may appear in the browser console for all configured environments.
INTERNAL_ERROR General server error.

Оставить отзыв о...

Текущей странице
Google Pay API