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

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 3DS 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/53/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP Method PUT
{
  "order": {
            "amount" : "1500",
            "currency": "USD",
            "walletProvider" :"GOOGLE_PAY"
  },
  "sourceOfFunds" : {
            "type":"CARD",
            "provided" : {
                          "card" : {
                                   "devicePayment" : {
                                                      "paymentToken" :"{\"signature\":\"MEUCIQDKY09Go6FZfUSOrajPdergu168PxUSDaPREvIrRhL5uQIgUcmfkj0J7m0Wvm754J1w96gb4omr+6uHp0Vx0N0zohI\u003d\",\"protocolVersion\":\"ECv1\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"InvalidPaymentToken\\\",\\\"ephemeralPublicKey\\\":\\\"BIORkAVmRAIWBnkUO03h67KQIymso87A6a1tM44aoMPWpjR+BDZOBAdt0NJUzw8o4oso7//uVljdgGzqDXQSKFE\\\\u003d\\\",\\\"tag\\\":\\\"DnzCuRaKwtLiMAgdzR5Y9Z52D1WI3FrprNmYWFSRqZo\\\\u003d\\\"}\"}"
                                                }
                                }
                }
  },
  "apiOperation": "PAY"
}}

 
Example Response
{
    "authorizationResponse": {
        "posData": "1605S0100130",
        "transactionIdentifier": "AmexTidTest"
    },
    "gatewayEntryPoint": "WEB_SERVICES_API",
    "merchant": "TESTWTF38659838",
    "order": {
        "amount": 1500,
        "chargeback": {
            "amount": 0,
            "currency": "USD"
        },
        "creationTime": "2018-06-20T00:09:58.021Z",
        "currency": "USD",
        "fundingStatus": "NOT_SUPPORTED",
        "id": "34097",
        "merchantCategoryCode": "1234",
        "status": "CAPTURED",
        "totalAuthorizedAmount": 1500,
        "totalCapturedAmount": 1500,
        "totalRefundedAmount": 0,
        "walletProvider": "GOOGLE_PAY"
    },
    "response": {
        "acquirerCode": "00",
        "gatewayCode": "APPROVED",
        "gatewayRecommendation": "PROCEED"
    },
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "AMEX",
                "devicePayment": {
                    "cryptogramFormat": "3DSECURE"
                },
                "deviceSpecificExpiry": {
                    "month": "5",
                    "year": "21"
                },
                "deviceSpecificNumber": "345678xxxxx4564",
                "encryption": "DEVICE",
                "expiry": {
                    "month": "5",
                    "year": "21"
                },
                "fundingMethod": "UNKNOWN",
                "number": "xxxxxxxxxxxxxxx",
                "scheme": "AMEX"
            }
        },
        "type": "CARD"
    },
    "timeOfRecord": "2018-06-20T00:09:58.021Z",
    "transaction": {
        "acquirer": {
            "batch": 1,
            "id": "SYSTEST_ACQ1",
            "merchantId": "123456"
        },
        "amount": 1500,
        "authorizationCode": "113111",
        "currency": "USD",
        "frequency": "SINGLE",
        "funding": {
            "status": "NOT_SUPPORTED"
        },
        "id": "A",
        "receipt": "1806206",
        "source": "INTERNET",
        "terminal": "11111",
        "type": "PAYMENT"
    },
    "version": "50"
}

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.
      3DSecure.onlinePaymentCryptogram
      Cryptogram in 3DSecure format.
      eciIndicator sourceOfFunds.provided.card.devicePayment.
      3DSecure.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 3DS 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
    • transaction.frequency=SINGLE
    • 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": "USD",
        "walletProvider":"GOOGLE_PAY"
    },
    "sourceOfFunds": {
        "provided": {
            "card": {
                "expiry": {
                    "month": "05",
                    "year": "21"
                },
                "number": "5123450000000008",
                "devicePayment":{
                    "cryptogramFormat":"3DSECURE",
                    "3DSecure":{
                        "onlinePaymentCryptogram":"IA/8pdiWftSsxpFT6wABoDABhgA=",
                        "eciIndicator":"20"
                    }
                }
            }
            
        },
        "type": "CARD"
    },
    "device": {
        "ani":"12341234"
    },
    "transaction": {
               "frequency": "SINGLE",
               "source": "INTERNET"
    } 
}
Example Response
{
  "authorizationResponse": {
    "posData": "10091Z500010",
    "transactionIdentifier": "000000285377253"
  },
  "customer": {
    "phone": "12341234"
  },
  "device": {
    "ani": "12341234"
  },
  "gatewayEntryPoint": "WEB_SERVICES_API",
  "lineOfBusiness": "All",
  "merchant": "TEST_MERCHANT",
  "order": {
    "amount": 30.1,
    "creationTime": "2016-11-09T23:20:58.675Z",
    "currency": "USD",
    "id": "C999903",
    "status": "AUTHORIZED",
    "totalAuthorizedAmount": 30.1,
    "totalCapturedAmount": 0,
    "totalRefundedAmount": 0,
    "walletProvider": "GOOGLE_PAY"
  },
  "posTerminal": {
    "location": "PAYER_TERMINAL_OFF_PREMISES"
  },
  "response": {
    "acquirerCode": "000",
    "cardholderVerification": {
      "avs": {
        "acquirerCode": "U",
        "gatewayCode": "NOT_AVAILABLE"
      },
      "detailedVerification": [
        {
          "gatewayCode": "NOT_MATCHED",
          "type": "BILLING_PHONE"
        },
        {
          "gatewayCode": "NOT_PROVIDED",
          "type": "BILLING_POSTCODE_ZIP"
        },
        {
          "gatewayCode": "NOT_PROVIDED",
          "type": "BILLING_STREET_ADDRESS"
        },
        {
          "gatewayCode": "NOT_PROVIDED",
          "type": "CARDHOLDER_NAME"
        },
        {
          "gatewayCode": "NOT_PROVIDED",
          "type": "CUSTOMER_EMAIL"
        }
      ]
    },
    "gatewayCode": "APPROVED"
  },
  "result": "SUCCESS",
  "sourceOfFunds": {
    "provided": {
      "card": {
        "brand": "MASTERCARD",
        "deviceSpecificExpiry": {
            "month": "05",
            "year": "21"
        },
        "deviceSpecificNumber": "512345xxxxxx0008",
        "expiry": {
          "month": "05",
          "year": "28"
        },
        "fundingMethod": "UNKNOWN",
        "devicePayment": {
          "cryptogramFormat": "3DSECURE"
        },
        "number": "xxxxxxxxxxxx0023",
        "scheme": "MASTERCARD"
      }
    },
    "type": "CARD"
  },
  "timeOfRecord": "2016-11-09T23:20:58.675Z",
  "transaction": {
    "acquirer": {
      "batch": 3,
      "id": "TESTACQUIRER",
      "merchantId": "6465720084"
    },
    "amount": 30.1,
    "authorizationCode": "377253",
    "currency": "USD",
    "frequency": "SINGLE",
    "id": "1",
    "receipt": "001611092532",
    "source": "INTERNET",
    "terminal": "12333",
    "type": "AUTHORIZATION"
  },
  "version": "44"
}

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.

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

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

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

Scheme
FPAN
Expiry Date
Visa 4111111111111111 12/2022

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

If gateway decrypts the payment token, your app needs to specify the gateway ("mpgs") as the 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 © 2019 Mastercard