# Google Pay source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/google-pay/index.md Google Pay is a mobile payment and digital wallet service by Google that enables seamless online checkout experiences for payers. It can be used in Android apps and on the mobile web, with payment methods saved to a Google account or Android device. Google Pay is a supported digital wallet in the Mastercard Gateway. This topic includes step-by-step integration steps for Google Pay. For more information about digital wallets and their payment flow, see [Digital Wallets](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/index.md). Warning: Google Pay is supported from API version 47 and later. The following methods are supported: | Integration Methods | Payment Methods | Operations | Card Brands Supported | |------------------------------------|----------------------------|------------------------------------|-------------------------------------| | * Direct payment * Hosted Checkout | * Credit card * Debit card | * AUTHORIZE * PAY * UPDATE SESSION | * Mastercard * VISA * AMEX * Jaywan | To view examples of API requests for digital wallet payments, download the [Postman collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api). ## Google Pay integration options {#google-pay-integration-options} The following integration options are supported: | Hosted Checkout | Direct Payment | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | * Allows you to collect payment details from your payer through an interaction that the gateway hosts and displays. * From DirectAPI version 72 and later, Google Pay is automatically offered on the hosted payment page when your payment service provider has enabled and configured you for this payment method. | * Allows you to offer the Google Pay payment method on your own checkout page | ### Prerequisites {#prerequisites} To accept Google Pay payments: * Sign up with Google and create your merchant ID required for the [Direct Payment](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/index.md) integration method. * Your merchant profile must be enabled by your payment service provider on the gateway for Device Payments. * If you want the gateway to perform the decryption of the payment token, your merchant profile on the gateway must have the "Enable Decryption of Google Pay Device Payments" privilege required for the [Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-checkout/integrate-google-pay-in-hosted-checkout/index.md) integration method, it is optional for Direct Payment. * If you are using a white-labeled domain, contact your payment service provider to ensure it is enabled for Google Pay. * If you are decrypting the payment token, ensure to get your integration approved by Google. Follow the instructions provided by Google for [Android or Web](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist). ## Adding support for Google Pay to your integration {#adding-support-for-google-pay-to-your-integration} You can integrate Google Pay into your mobile app or the checkout page of your web site using [Direct Payment](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/direct-payment/index.md). If you are using the Hosted Checkout integration method, no additional integration steps are required. Warning: Use Google Pay's integration checklist like the [Android integration checklist](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist) or the [Web integration checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist), to ensure you complete all the required steps. If you want to decrypt the payment token on your server, see [Decrypting the Payment Token](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/google-pay/index.md#decrypting-the-payment-token). 1. On payment confirmation, provide the following fields in the `tokenizationSpecification` object of the Google Pay API: * `type` Tokenization type. Set this to `PAYMENT_GATEWAY`. * `gateway` Gateway identifier. Set this to `mpgs`. You need to specify the Mastercard Gateway as your payment service provider in your app to allow the payment token generated by Google to be encrypted using the gateway's public key. * `gatewayMerchantId` Merchant's gateway ID. A unique merchant ID that the gateway can use to verify and identify the merchant when decrypting the payment token. This merchant ID 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 are provided with a payload that contains an encrypted payment token signed by Google. The payment token is issued for either a digital wallet payment or a card payment. Warning: You can specify whether you want the Google Pay API to return Funding Primary account numbers (FPANs) or Device Primary account numbers (DPANs). This can be useful if your acquirer does not support digital wallet 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. If needed, authenticate the payer by providing the following fields in the [INITIATE AUTHENTICATION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) request. * `order.walletProvider = GOOGLE_PAY` Google Pay digital wallet provider. * `sourceOfFunds.provided.card.devicePayment.paymentToken` Encrypted payment token obtained from the Google Pay SDK. The gateway decrypts the payment token, and if it contains an FPAN, the INITIATE AUTHENTICATION request proceeds. If the payment token contains a DPAN, the request is rejected since EMV 3-D Secure authentication is not supported for DPANs. For more information about how to integrate to the gateway using EMV 3-D Secure, see [EMV 3-D Secure Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md). Warning: The gateway supports EMV 3-D Secure authentication with Google Pay from API version 53 and later. 3. Provide the following fields in the [AUTHORIZE](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction),[PAY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction), or [UPDATE SESSION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) request: * `order.walletProvider = GOOGLE_PAY` Google Pay digital wallet provider. * `order.amount` Total amount for the order. The value you provide must be the final amount of the order including shipping and other additional amounts. * `order.currency` Currency of the order. * `sourceOfFunds.provided.card.devicePayment.paymentToken` Encrypted payment token obtained from the Google Pay SDK. The gateway verifies 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 and the merchant's gateway ID in the payment token, and processes the transaction using the decrypted data. ### AUTHORIZE request example for decryption in gateway {#authorize-request-example-for-decryption-in-gateway} | HTTP Method | URL | |-------------|-------------------------------------------------------------------------------------------------------| | PUT | {{host}}/api/rest/version//merchant/\/order/\/transaction/\ | ```json { "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" } } ``` In addition to the standard fields, the following response fields are returned for a successful authorization using the payment token, if the issuer successfully maps the DPAN to the FPAN: * If the payload contains a DPAN for digital wallet payments: * `sourceOfFunds.provided.card.encryption = DEVICE` Encrypted by a payer's device such as a mobile phone. * `sourceOfFunds.provided.card.deviceSpecificNumber` 6.4 masked DPAN. * `sourceOfFunds.provided.card.deviceSpecificExpiry.month` Expiry month of the DPAN. * `sourceOfFunds.provided.card.deviceSpecificExpiry.year` Expiry year of the DPAN. * `sourceOfFunds.provided.card.number` Masked FPAN, usually 0.4 masked, were available from the acquirer. * `sourceOfFunds.provided.card.expiry.month` Expiry month of the FPAN, were available from the acquirer. * `sourceOfFunds.provided.card.expiry.year` Expiry year of the FPAN, were available from the acquirer. * `sourceOfFunds.provided.card.devicePayment.cryptogramFormat` Format of the cryptogram provided for the digital wallet payment. * If the payload contains an FPAN for Google Pay digital wallet payments: * `sourceOfFunds.provided.card.encryption = DIGITAL_WALLET` Encrypted by a payer's digital wallet. * `sourceOfFunds.provided.card.number` Masked FPAN, usually 0.4 masked, were available from the acquirer. * `sourceOfFunds.provided.card.expiry.month` Expiry month of the FPAN, were available from the acquirer. * `sourceOfFunds.provided.card.expiry.year` Expiry year of the FPAN, were available from the acquirer. If you request for an unmasked PAN to be returned in the transaction response, the gateway returns an unmasked DPAN and FPAN depending on the acquirer support. Warning: If you want to return unmasked card numbers, you must have the requisite privilege, set the `responseControls.sensitiveData` field to UNMASK, and authenticate your call to the API using certificate authentication. ### Example response {#example-response} ```json { "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" } ``` ```json { "authorizationResponse": { "cardLevelIndicator": "88", "commercialCard": "888", "commercialCardIndicator": "3", "marketSpecificData": "8", "posData": "1025104006600", "posEntryMode": "812", "processingCode": "003000", "responseCode": "00", "returnAci": "8", "stan": "266773", "transactionIdentifier": "123456789012345", "validationCode": "6789" }, "gatewayEntryPoint": "WEB_SERVICES_API", "merchant": "TESTLOVECRAFTS2I", "order": { "amount": 756.96, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "certainty": "ESTIMATED", "chargeback": { "amount": 0, "currency": "USD" }, "creationTime": "2024-04-26T17:22:25.067Z", "currency": "USD", "id": "690869250", "lastUpdatedTime": "2024-04-26T17:22:27.202Z", "merchantAmount": 756.96, "merchantCategoryCode": "1234", "merchantCurrency": "USD", "status": "AUTHORIZED", "totalAuthorizedAmount": 756.96, "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": "VISA", "encryption": "DIGITAL_WALLET", "expiry": { "month": "1", "year": "39" }, "fundingMethod": "CREDIT", "issuer": "COMMONWEALTH BANK OF AUSTRALIA", "number": "453224xxxxxx4180", "scheme": "VISA", "storedOnFile": "STORED" } }, "type": "CARD" }, "timeOfLastUpdate": "2024-04-26T17:22:27.202Z", "timeOfRecord": "2024-04-26T17:22:25.160Z", "transaction": { "acquirer": { "batch": 20240426, "date": "0426", "id": "CBA_S2I", "merchantId": "123456", "transactionId": "123456789012345" }, "amount": 756.96, "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT", "authorizationCode": "266773", "currency": "USD", "id": "558397991", "receipt": "411717266773", "source": "INTERNET", "stan": "266773", "terminal": "CBAS2I02", "type": "AUTHORIZATION" }, "version": "81" } ``` ### Decrypting the payment token {#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 must store the encryption credentials and execute the decryption. Follow these steps to decrypt the payment token: 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. For more information on the decryption steps, see [Payment data cryptography for merchants](https://developers.google.com/pay/api/android/guides/resources/payment-data-cryptography). 3. If the decrypted payment token contains an FPAN, you can choose to authenticate the payer first before performing the transaction: a. To authenticate the payer, provide the following fields in the INITIATE AUTHENTICATION request. * `order.walletProvider = GOOGLE_PAY` Google Pay digital wallet provider. * `sourceOfFunds.provided.card.number` Refer the following table. For more information about how to authenticate the payer using EMV 3-D Secure, see [EMV 3-D Secure Authentication](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md). b. Provide the payment data keys from the decrypted token in the corresponding transaction fields in the AUTHORIZE, PAY, or UPDATE SESSION request. Refer the following table. **Table: Payment data keys and the corresponding API request fields with FPAN** | Google Pay JSON Key | Corresponding API Request Field | Description | |---------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | pan | `sourceOfFunds.provided.card.number` | 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 Pay account. Warning: For card payments, capturing Card Security Code (CSC) is currently not supported by the Google Pay API. | | expirationMonth | `sourceOfFunds.provided.card.expiry.month` | Expiration month of the pan. | | expirationYear | `sourceOfFunds.provided.card.expiry.year` | Expiration year of the pan. | 4. If the decrypted payment token contains a DPAN, provide the payment data keys from the decrypted token in the corresponding transaction fields in the AUTHORIZE, PAY, or UPDATE SESSION request. Warning: Do not attempt EMV 3-D Secure authentication if the payment token contains a DPAN. The gateway rejects the request as DPANs are not supported on EMV 3-D Secure authentication.
**Table: Payment data keys and the corresponding API request fields with DPAN** | Google Pay JSON Key | Corresponding API Request Field | Description | |---------------------|---------------------------------------------------------------------|----------------------------------------------------| | pan | `sourceOfFunds.provided.card.number` | DPAN of the card that funded this transaction. | | expirationMonth | `sourceOfFunds.provided.card.expiry.month` | Expiration month of the pan. | | expirationYear | `sourceOfFunds.provided.card.expiry.year` | Expiration year of the pan. | | authMethod | `sourceOfFunds.provided.card.devicePayment.cryptogramFormat` | Cryptogram format. Set this to EMV 3-D Secure. | | cryptogram | `sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram` | Cryptogram in EMV 3-D Secure format. | | eciIndicator | `sourceOfFunds.provided.card.devicePayment.eciIndicator` | Electronic Commerce Indicator (ECI), if available. | 5. In addition to the above sourceOfFunds fields, provide the following fields in the AUTHORIZE, PAY, or UPDATE SESSION request and submit it to the gateway: * `transaction.source = INTERNET` Channel through which you received authorization for the payment for this order. The value INTERNET indicates that the payer initiated the payment online. * `order.walletProvider = GOOGLE_PAY` Google Pay digital wallet provider. * `device.mobilePhoneModel (optional)` Identifier of the mobile device used to initiate the payment. * `posTerminal.location` Physical location of the device in relation to your business premises. The possible values are `PAYER_TERMINAL_OFF_PREMISES` or `PAYER_TERMINAL_ON_PREMISES`. If you do not provide any value, `PAYER_TERMINAL_OFF_PREMISES` is used. * `sourceOfFunds.type = CARD` * `sourceOfFunds.provided.card.nameOnCard` Cardholder's name (optional).\` * `order.currency` ISO 4217 currency code for the transaction. * `order.amount` Order amount. ### AUTHORIZE request example for decryption in your server {#authorize-request-example-for-decryption-in-your-server} ```json { "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" } } ``` The response is similar regardless of whether the decryption happens in the gateway or your server. ## Testing your Google Pay integration {#testing-your-google-pay-integration} Follow these steps to test your Google Pay integration if you decrypt the payment token: 1. 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, see \*[Test with sample tokens](https://developers.google.com/pay/api/android/guides/resources/sample-tokens#mastercard). * If you are testing a digital wallet payment for card saved to your Android device, use a supported DPAN from the table. **Table: Supported DPANs** | Scheme | DPAN | Expiration date | |------------------|------------------|-----------------| | Visa | 4895370012003478 | 12/2028 | | American Express | 370295136149943 | 12/2028 | * If you are testing a card payment for card saved to your Google Pay account, use the supported FPAN from the table. **Table: Supported FPAN** | Scheme | FPAN | Expiration date | |--------|------------------|-----------------| | Visa | 4111111111111111 | 12/2028 | 2. Get your integration approved by Google. Follow the instructions supplied by Google: [Android integration checklist](https://developers.google.com/pay/api/android/guides/test-and-deploy/integration-checklist) or [Web integration checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist). 3. When your integration is approved by Google, perform final production verification testing before going live. To test your Google Pay integration if the gateway decrypts the payment token, use your production merchant ID in the API requests. The test merchant ID is unable to decrypt payment tokens. If the `response.gatewayCode` field indicates that the transactions are APPROVED or DECLINED, the gateway was able to process your test transactions successfully. For testing the Google Pay Integration in MTF/TEST environments, see the [Test cards suite](https://developers.google.com/pay/api/web/guides/resources/test-card-suite). ### Testing Google Pay integration with gateway test data {#testing-google-pay-integration-with-gateway-test-data} You can test your integration with the gateway in production using your test merchant profile with a valid [test card](https://developers.google.com/pay/api/android/guides/resources/test-card-suite#mock-testing) and provide the order amount value as provided in the following table to get the expected simulated response. | Order amount | Response | |--------------|---------------------| | 5656 | Approved | | 5757 | Declined | | 5858 | TIMED_OUT | | 5959 | UNSPECIFIED_FAILURE | | 6161 | Partially Approved | | 6262 | System Error | | 6363 | UNKNOWN | Configure your app to use a Google Pay Sandbox environment with your gateway test merchant profile. When the payer selects a card in Google Pay, the app generates a payment token in test mode. If the transactions are either APPROVED, DECLINED, or any other responses as per the order amount simulation, or based on the supported FPAN as provided by Google, then the gateway can process your test transactions successfully. ## Google Pay with the Mobile SDK {#google-pay-with-the-mobile-sdk} The Mobile SDK helps you develop a mobile app that accepts Google Pay payments through the gateway. The gateway offers support for Google Pay through the Mobile SDK. Click [here](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/mobile-integration/integrate-mobile-payments/mc-gw-andriod-sdk/index.md) for the Mobile SDK integration guidelines for the Android platform.