Google Pay Payments

Google Pay™ is a mobile payment and digital wallet service by Google that enables seamless online checkout experiences for payers, in Android apps and on the mobile web, using payment methods saved to a Google account or Android device. Google Pay is a supported device payment in the Mastercard Payment Gateway.

This page describes the processing specific to Google Pay device payments. It's recommended that you read the integration guidelines for device payments, before building your Google Pay integration.

The Mastercard Payment Gateway offers Google Pay from API v47 onwards.

Prerequisites

To accept Google Pay payments:

  • You must sign up with Google and create your merchant ID (required for Direct Payment).
  • Your merchant profile on the gateway must be enabled for "Device Payments" by your payment service provider.
  • If you want the gateway to perform the decryption of the payment token, your merchant profile on the gateway must have "Enable Decryption of Google Pay Device Payments" permission (required for Hosted Checkout integrations, optional for Direct Payment).
  • If you are using a white-labeled domain, please reach out to your payment service provider to ensure it is enabled for Google Pay.

Google Pay Integration

Google Pay via Hosted Checkout

Hosted Checkout integration allows you to collect payment details from your payer through an interaction that the gateway hosts and displays.

From the API version 72 onward, Google Pay is automatically available as a payment method once your your payment service provider enables and configures you for this payment method.

Google Pay via Direct Payment

Direct Payment integration allows you to offer Google pay payment method on your own checkout page.

Google Pay is supported from API version 47 onward.

Adding Support for Google Pay to your Integration

You can integrate Google Pay into your mobile app or the checkout page of your website using Direct Payment.

    If you want to take the responsibility of decrypting the payment token on your server, see Decrypting the Payment Token.

  1. On payment confirmation, provide the following parameters in the tokenizationSpecification object of the Google Pay API:

    • tokenization type (type): Set this to PAYMENT_GATEWAY
    • gateway identifier (gateway): Set this to mpgs
    • merchant's gateway identifier (gatewayMerchantId): A unique merchant identifier that the gateway can use to verify and identify the merchant when decrypting the payment token. This merchant identifier must be the same as your merchantId submitted on your gateway's API request.

    On completion of the payer's interaction with the Google Pay user interface, you will be provided with a payload that contains an encrypted payment token signed by Google. The payment token will be issued for either a device payment or a card payment.

    You can specify whether you want the Google Pay API to return FPANs or DPANs. This might be useful if your acquirer does not support device payments, in which case you can limit support to FPANs by setting allowedAuthMethods to PAN_ONLY in the allowedPaymentMethods object of the Google Pay API.
  2. (Optional) Authenticate the payer: Provide the following fields in the 3DS Check Enrollment request.

    • order.walletProvider=GOOGLE_PAY
    • sourceOfFunds.provided.card.devicePayment.paymentToken: The encrypted payment token obtained from the Google Pay SDK.

    The gateway will decrypt the payment token, and if it contains an FPAN then 3DS Check Enrollment request will proceed. If the payment token contains a DPAN, the request is rejected (3DS authentication is not supported for DPANs). For more information on how to integrate to the gateway using 3DS, see 3D Secure Authentication.

    The Mastercard Payment Gateway offers 3DS payer authentication on Google Pay from API v53 onwards.
  3. Provide the following fields in the Authorize/Pay or an Update Session request.
    • order.walletProvider=GOOGLE_PAY
    • order.amount: The value you provide must be the final amount of the order (including shipping and other additional amounts).
    • order.currency
    • sourceOfFunds.provided.card.devicePayment.paymentToken: The encrypted payment token obtained from the Google Pay SDK.

    sourceOfFunds.provided.card.devicePayment.paymentToken [REST][NVP]

  4. The gateway will verify the signature on the payment token to ensure it has been signed by Google. After verification, the gateway decrypts the payment token for you, validates the gateway identifier, the merchant's gateway identifier in the payment token, and processes the transaction using the decrypted data.

    In addition to the standard fields, the following response fields are returned for a successful authorization using the payment token.

    If the payload contained a DPAN (for device payments):

    • sourceOfFunds.provided.card.encryption=DEVICE
    • sourceOfFunds.provided.card.deviceSpecificNumber: The DPAN in masked format.
    • sourceOfFunds.provided.card.deviceSpecificExpiry.month
    • sourceOfFunds.provided.card.deviceSpecificExpiry.year
    • sourceOfFunds.provided.card.number: The FPAN in masked format.
    • sourceOfFunds.provided.card.expiry.month
    • sourceOfFunds.provided.card.expiry.year
    • sourceOfFunds.provided.card.devicePayment.cryptogramFormat

    If the payload contained an FPAN (for Google Pay digital wallet payments):

    • sourceOfFunds.provided.card.encryption=DIGITAL_WALLET
    • sourceOfFunds.provided.card.number: The FPAN in masked format.
    • sourceOfFunds.provided.card.expiry.month
    • sourceOfFunds.provided.card.expiry.year
It's recommended that you use Google Pay's integration checklist (Android/Web) to ensure you have completed all the required steps.
Example Request

Here's a sample Authorization Request in REST where payment token is decrypted by the gateway.

URL 'https://na.gateway.mastercard.com/api/rest/version/71/merchant/MADA_DMS_AU/order/810663616/transaction/911988788'
HTTP Method PUT
Header 'Authorization: Basic bWVyY2hhbnQuTUFEQV9ETVNfQVU6M2RjYTQ2YTU1ODYwNDlmMjhhM2FmZGJmZDEwMGNmNWQ=' 
 '{
     "apiOperation": "AUTHORIZE",
     "order": {
         "amount": "30.10",
         "currency": "USD",
         "walletProvider": "GOOGLE_PAY"
     },
     "sourceOfFunds": {
         "provided": {
             "card": {
                 "devicePayment": {
                      "paymentToken"{\n  \"protocolVersion\" : \"ECv1\",\n  \"signature\" : \"MEYCIQCiSE4dCSwpXwJLo1lKYOZNmFyL...\",\n  \"signedMessage\" : \"{\\\"encryptedMessage\\\":\\\"gTVbbw8Nsv4kTulngmSVsZijvS5x7sAM9UZiqyaKfjkqxxJ1pkqRvhWBFc4FnEiMm2rjUPlX55e0dUqI00iQwAfePuhrna...\\\",\\\"ephemeralPublicKey\\\":\\\"BKoBQYjYIEYgw9nzA+0Q06FD77ZhrOXQh9yNUX0LasjL2W9eMvWZ0pCGGRzPKZLCtk...\\\",\\\"tag\\\":\\\"fnZGEbpCkXzKU3xhS5u1E3c6OoB6RzkHbhHx58...\\\"}\"\n}" //This is only a sample token and will not pass validation. You should substitute this with an actual payment token returned from Google Pay.
//The gateway considers this value to be a string, NOT JSON itself. The parenthesis are a part of the string.
                 }
             }
         },
         "type": "CARD"
     },
     "device": {
         "ani": "12341234"
     },
     "transaction": {
         "source": "INTERNET"
     }
 }'
Example Response

  {
      "authorizationResponse": {
          "commercialCard": "123",
          "commercialCardIndicator": "1",
          "date": "0314",
          "financialNetworkCode": "MCC",
          "posData": "1025104006600",
          "posEntryMode": "812",
          "processingCode": "003000",
          "responseCode": "00",
          "stan": "45467",
          "time": "105002",
          "transactionIdentifier": "906660122",
          "transactionIntegrityClass": "A1"
      },
      "device": {
          "ani": "12341234"
      },
      "gatewayEntryPoint": "WEB_SERVICES_API",
      "merchant": "MADA_DMS_AU",
      "order": {
          "amount": 30.10,
          "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
          "certainty": "FINAL",
          "chargeback": {
              "amount": 0,
              "currency": "USD"
          },
          "creationTime": "2023-03-14T10:50:01.524Z",
          "currency": "USD",
          "id": "810663616",
          "lastUpdatedTime": "2023-03-14T10:50:02.092Z",
          "merchantAmount": 30.10,
          "merchantCategoryCode": "1234",
          "merchantCurrency": "USD",
          "status": "AUTHORIZED",
          "totalAuthorizedAmount": 30.10,
          "totalCapturedAmount": 0.00,
          "totalDisbursedAmount": 0.00,
          "totalRefundedAmount": 0.00,
          "walletProvider": "GOOGLE_PAY"
      },
      "response": {
          "acquirerCode": "00",
          "acquirerMessage": "Approved",
          "gatewayCode": "APPROVED",
          "gatewayRecommendation": "NO_ACTION"
      },
      "result": "SUCCESS",
      "sourceOfFunds": {
          "provided": {
              "card": {
                  "brand": "MASTERCARD",
                  "devicePayment": {
                      "cryptogramFormat": "3DSECURE"
                  },
                  "deviceSpecificExpiry": {
                      "month": "1",
                      "year": "39"
                  },
                  "deviceSpecificNumber": "512345xxxxxx0008",
                  "fundingMethod": "UNKNOWN",
                  "number": "xxxxxxxxxxxxxxxx",
                  "scheme": "MASTERCARD",
                  "storedOnFile": "NOT_STORED"
              }
          },
          "type": "CARD"
      },
      "timeOfLastUpdate": "2023-03-14T10:50:02.092Z",
      "timeOfRecord": "2023-03-14T10:50:01.625Z",
      "transaction": {
          "acquirer": {
              "batch": 20230314,
              "date": "0314",
              "id": "SYSTEST_ACQ_S2I",
              "merchantId": "12345678",
              "transactionId": "906660122"
          },
          "amount": 30.10,
          "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
          "authorizationCode": "112233",
          "currency": "USD",
          "id": "911988788",
          "receipt": "307310045467",
          "source": "INTERNET",
          "stan": "45467",
          "terminal": "1111",
          "type": "AUTHORIZATION"
      },
      "version": "71"
  }

Decrypting the Payment Token

You can choose to decrypt the payment token on your server instead of providing the payment token for decryption to the gateway. In this case, you will need to take responsibility for storing the encryption credentials and executing the decryption.

  1. On payment confirmation, submit the encrypted payment token returned by Google Pay to your server.
  2. Decrypt the payment token on your server using your private key. See decryption steps here.
  3. Provide the payment data keys from the decrypted token in the corresponding transaction fields on the Authorize/Pay request or the Update Session request.

    • If the decrypted payment token contains a DPAN, provide these fields:

      Do not attempt 3DS payer authentication if the payment token contains a DPAN. The gateway will reject the request as DPANs are not supported on 3DS authentication.
      Google Pay JSON Key
      Corresponding API Request Field
      Description
      pan sourceOfFunds.provided.card.number The device-specific primary account number (DPAN) of the card that funded this transaction.
      expirationMonth sourceOfFunds.provided.card.expiry.month The expiration month of the pan.
      expirationYear sourceOfFunds.provided.card.expiry.year The expiration year of the pan.
      authMethod sourceOfFunds.provided.card.
      devicePayment.cryptogramFormat      		 The cryptogram format. Set this to 3DSECURE.
      cryptogram sourceOfFunds.provided.card.devicePayment.
      onlinePaymentCryptogram      		 Cryptogram in 3DSecure format.
      eciIndicator sourceOfFunds.provided.card.devicePayment.
      eciIndicator      		 Provide the electronic commerce indicator (ECI), if available.
        sourceOfFunds.provided.card.nameOnCard (Optional)The cardholder's name.
        order.currency The ISO 4217 currency code for the transaction.
        order.amount The order amount.

      sourceOfFunds.provided.card.devicePayment [REST][NVP]

    • If the decrypted payment token contains an FPAN, you can choose to authenticate the payer first before performing the transaction. To authenticate the payer, provide the following fields in the 3DS Check Enrollment request.

      • order.walletProvider=GOOGLE_PAY
      • sourceOfFunds.provided.card.number: See table below.

      For more information on how to integrate to the gateway using 3DS, see 3D Secure Authentication.

      Google Pay JSON Key
      Corresponding API Request Field
      Description
      pan sourceOfFunds.provided.card.number The card number (FPAN) of the card that funded this transaction. The payload contains an FPAN when the payer chooses to pay using a card saved to their Google Play account.
      Note that for card payments, capturing CSC is currently not supported by the Google Pay API.
      expirationMonth sourceOfFunds.provided.card.expiry.month The expiration month of the pan.
      expirationYear sourceOfFunds.provided.card.expiry.year The expiration year of the pan.
        sourceOfFunds.provided.card.nameOnCard (Optional)The cardholder's name.
        order.currency The ISO 4217 currency code for the transaction.
        order.amount The order amount.
  4. In addition to the above fields, include these in the Authorize/Pay or Update Session request and submit it to the gateway.

    • transaction.source=INTERNET
    • order.walletProvider=GOOGLE_PAY
    • device.mobilePhoneModel: (optional) The identifier of the mobile device used to initiate the payment.
    • posTerminal.location: You can specify PAYER_TERMINAL_OFF_PREMISES or PAYER_TERMINAL_ON_PREMISES. If you do not provide a value, PAYER_TERMINAL_OFF_PREMISES is used.
Example Request

Here's a sample Authorization Request in REST where the values from the decrypted payment token are provided to the gateway.

  {
    "apiOperation": "AUTHORIZE",
    "order": {
        "amount": "30.10",
        "currency": "INR",
        "walletProvider": "GOOGLE_PAY"
    },
    "sourceOfFunds": {
        "provided": {
            "card": {
                "expiry": {
                    "month": "01",
                    "year": "39"
                },
                "number": "5123450000000008",
                "devicePayment": {
                    "cryptogramFormat": "3DSECURE",
                    : {
                        "onlinePaymentCryptogram": "IA/8pdiWftSsxpFT6wABoDABhgA=",
                        "eciIndicator": "20"
                    }
                }
            }
        },
        "type": "CARD"
    },
    "device": {
        "ani": "12341234"
    },
    "transaction": {
        "source": "INTERNET"
    }
}
Example Response
  {
    "authorizationResponse": {
        "commercialCard": "123",
        "commercialCardIndicator": "1",
        "date": "0330",
        "financialNetworkCode": "MCC",
        "posData": "1025104006600",
        "posEntryMode": "812",
        "processingCode": "003000",
        "responseCode": "00",
        "stan": "290026",
        "time": "220509",
        "transactionIdentifier": "865442937",
        "transactionIntegrityClass": "A1"
    },
    "device": {
        "ani": "12341234"
    },
    "gatewayEntryPoint": "WEB_SERVICES_API",
    "merchant": "LOVECRAFTS2I",
    "order": {
        "amount": 30.10,
        "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
        "certainty": "ESTIMATED",
        "chargeback": {
            "amount": 0,
            "currency": "INR"
        },
        "creationTime": "2022-03-30T22:05:09.395Z",
        "currency": "INR",
        "id": "09765d59-cdd8-432c-96c9-d6ae91588251",
        "lastUpdatedTime": "2022-03-30T22:05:09.857Z",
        "merchantAmount": 30.10,
        "merchantCategoryCode": "1234",
        "merchantCurrency": "INR",
        "status": "AUTHORIZED",
        "totalAuthorizedAmount": 30.10,
        "totalCapturedAmount": 0.00,
        "totalDisbursedAmount": 0.00,
        "totalRefundedAmount": 0.00,
        "walletProvider": "GOOGLE_PAY"
    },
    "response": {
        "acquirerCode": "00",
        "acquirerMessage": "Approved",
        "gatewayCode": "APPROVED"
    },
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "MASTERCARD",
                "devicePayment": {
                    "cryptogramFormat": "3DSECURE"
                },
                "deviceSpecificExpiry": {
                    "month": "1",
                    "year": "39"
                },
                "deviceSpecificNumber": "512345xxxxxx0008",
                "fundingMethod": "UNKNOWN",
                "number": "xxxxxxxxxxxxxxxx",
                "scheme": "MASTERCARD",
                "storedOnFile": "NOT_STORED"
            }
        },
        "type": "CARD"
    },
    "timeOfLastUpdate": "2022-03-30T22:05:09.857Z",
    "timeOfRecord": "2022-03-30T22:05:09.410Z",
    "transaction": {
        "acquirer": {
            "batch": 20220330,
            "date": "0330",
            "id": "SYSTEST_ACQ_S2I",
            "merchantId": "123463",
            "transactionId": "865442937"
        },
        "amount": 30.10,
        "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
        "authorizationCode": "112233",
        "currency": "INR",
        "id": "1",
        "receipt": "208922290026",
        "source": "INTERNET",
        "stan": "290026",
        "terminal": "CBAS2I02",
        "type": "AUTHORIZATION"
    },
    "version": "71"
}

Testing Google Pay Integration

If you are decrypting the payment token, you must get your integration approved by Google. Follow the instructions supplied by Google here: Android/Web.

However, before submitting your integration for approval to Google, you must complete some test transactions. You can test your integration with the gateway in production using your test merchant profile and a supported DPAN or an FPAN. For more information, refer to Test with sample tokens.

If you are testing for a device payment (card saved to your Android device), use a supported DPAN from the following table.

Scheme
DPAN
 Expiry Date
Visa 4895370012003478 12/2027
American Express 370295136149943 12/2027

If you are testing for a card payment (card saved to your Google Play account), use the supported FPAN from the following table.

Scheme
FPAN
 Expiry Date
Visa 4111111111111111 12/2027

Once your integration is approved by Google, you must perform final production verification testing before going live.

If the gateway decrypts the payment token, your app needs to specify the gateway ("mpgs") as your payment service provider. This information is needed to allow the payment token generated by Google to be encrypted using the gateway's public key.

To perform test transactions, you must use your gateway production Merchant ID in production — the test gateway Merchant ID is unable to decrypt payment tokens.

If the transactions are either APPROVED or DECLINED then the gateway was able to process your test transactions successfully.

Google Pay via Mobile SDK

The Mobile SDK assists you to develop a mobile application (app) that will accept digital payments via the Mastercard Payment Gateway. The gateway offers support for Google Pay via the Mobile SDK. Click here for the Mobile SDK integration guidelines for the Android platform.

Copyright © 2023 Mastercard