Google Pay (REST API)

On this page:

Overview

This guide describes the steps to integrate Google Pay as a Nuvei APM (alternative payment method) into your payment flow using the Nuvei Server-to-Server REST API platform.

Coming Soon!

3D-Secure authentication support for Google Pay is scheduled for release in mid-July.

Setting up the Google Pay UI
Google Pay Implementations

Follow the steps to integrate the relevant implementation/s described below:

  • Payment with GooglePay Token
    This allows you to send the encrypted GooglePay Token in a /payment request.
  • Payment with Decrypted GooglePay Token
    You can decrypt the GooglePay Token. If the decrypted values contain a cavv value, then send the extracted payment details in an externalMPI block in a /payment request.
  • Recurring Payments
    This allows you to perform both Initial Recurring Payments and Subsequent Recurring Payments using the encrypted GooglePay Token.

Google Pay also supports refunds.

Prerequisites and Notes
  • This guide assumes you have completed all account set up prerequisites, and are ready to integrate the Google Pay APM payment method into your payment flow.
  • Use these gateway credentials in requests:
    • For the test (sandbox) environment:  gatewayMerchantId: "googletest"
    • For the production environment:  gatewayMerchantId: "nuveidigital"
  • The Google Pay Web environment must be set up according to the Google Pay guidelines:
  • The Google account used for testing should be linked to a relevant test card:
    • Google Pay provides test cards, see Google Pay Test Card Suite for details.
    • Alternatively, you can use one of the test cards listed in the Testing Cards topic.
      Test credentials and testing scenarios can be provided by Nuvei if necessary.
      You can contact Nuvei Support for any assistance.
  • Google Pay supports recurring payments only if you (the merchant) conforms to the following policies:
    1. The Merchant must comply with the network rules, especially the merchant-initiated transactions (MIT) rules.
    2. The Merchant must disclose the “Terms of payment” within the Merchant’s “buyflow”, and the customer must accept the “Terms of payment”.

Including a userTokenId (unique customer identifier in the merchant system) in the /payment request:

  • Allows Nuvei to create a UPO (user payment option) record to store the customer payment method details.
  • The system returns an encrypted userPaymentOptionId which can be used in future transactions to represent the customer payment method.

If you do not wish to use Nuvei UPOs, then contact the Nuvei Integration Team to configure your merchant account accordingly.

Google Pay as an “External token provider”

An external token provider is a type of entity in the payment industry with its own flow (for example: Apple Pay, Google Pay, Visa Checkout).
These providers typically collect the customer payment method and transaction details.

Set up the Google Pay UI

1. Authentication

Perform the standard authentication by sending a /getSessionToken request by following the steps, in the Step 1: Authentication topic.

2. The Google Pay UI Button

  1. Create the Google Pay UI button according to the instructions in the Google Pay for Web Payments Brand Guidelines Guide.
  2. In your payment page, define the tokenizationSpecification constant as shown below.
    (When the customer clicks the Google Pay button, this parameter identifies your gateway and your site’s gateway merchant identifier.)
    Example tokenizationSpecification Constant in an /initPayment Request
    const tokenizationSpecification = {
  type: "PAYMENT_GATEWAY",
  parameters: {
    "gateway": "nuveidigital",
    "gatewayMerchantId": "googletest", //'googletest' for test or 'nuveidigital' for production
  }
};

3. Collect the Card Details

Pressing the Google Pay button collects your customer’s card details and returns them to you in the form of an encrypted Google Pay token.

  1. The customer triggers the Google Pay payment flow by clicking the Google Pay button.

    At this point, your customer may be asked to log in to their Google Pay account.

  2. Google Pay displays all the cards associated with the customer’s Google account, or asks the customer to “Add new credit or debit card” details.
  3. The customer selects a payment method and Google Pay returns the encrypted Google Pay token (containing the paymentMethod block in JSON format).

Payment with GooglePay Token

Perform these steps to process a Google Pay payment:

Send a /payment request with its mandatory parameters and include these additional parameters:

  • "userTokenId":"<unique customer identifier in merchant system - required for UPO creation>"
  • paymentOption.card.externalToken.”externalTokenProvider": "GooglePay"
  • paymentOption.card.externalToken."mobileToken": "<encrypted GooglePay Token converted to a string>"

    Format the mobileToken value as a string:

    1. Retrieve the paymentMethod block (returned in JSON format by Google Pay, in the previous step) from the response console panel of your payment page.
    2. Convert the “entire” encrypted paymentMethod block into a string (“JSON to String”).
Example /payment Request with GooglePay Token
{
  "sessionToken": "<sessionToken from getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "amount": "200",
  "currency": "USD",
  "userTokenId": "<unique customer identifier in merchant system - required for UPO creation>",
  "paymentOption": {
    "card": {
      "externalToken": {
        "externalTokenProvider": "GooglePay",
        "mobileToken": "<encrypted GooglePay Token converted to a string>" 
      }
    }
  },
  "billingAddress":{
    "email": "john.smith@email.com",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress": "127.0.0.1"
  },
  "userDetails": {
    "country": "US"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"  
}
Example /payment Response with GooglePay Token
{
    "reason": "",
    "authCode": "0E5E04",
    "orderId": "36726421",
    "transactionStatus": "APPROVED",
    "clientRequestId": "V8UE4312Y",
    "customData": "Custom Data for C-Panel Reports",
    "internalRequestId": 19054731,
    "version": "1.0",
    "transactionId": "2110000000005034514",
    "merchantSiteId": "126006",
    "transactionType": "Sale",
    "gwExtendedErrorCode": 0,
    "gwErrorCode": 0,
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode": 0,
    "paymentOption": {
        "userPaymentOptionId": "8107431",
        "card": {
            "issuerBankName": "Legence Bank",
            "ccCardNumber": "4****1112",
            "externalTokenProvider": "GooglePay",
            "bin": "417577",
            "avsCode": "",
            "threeD": {},
            "ccExpMonth": "08",
            "ccExpYear": "25",
            "isPrepaid": "false",
            "acquirerId": "18",
            "cardBrand": "VISA",
            "cvv2Reply": "",
            "last4Digits": "1112"
        }
    },
    "sessionToken": "f3b77f95-d126-40bc-b1a9-2cf24fff811d",
    "userTokenId": "9XL74BK99KBW",
    "externalTransactionId": "",
    "fraudDetails": {
        "score": "0",
        "system": {
            "systemId": "1",
            "decision": "None"
        },
        "finalDecision": "Accept"
    },
    "status": "SUCCESS"
}

Payment with Decrypted GooglePay Token

This is used when you want to decrypt the GooglePay Token yourself, and then send the extracted payment details in an externalMPI block in a /payment request.

Perform these steps to process a Google Pay payment:

  1. Decrypt the GooglePay Token.
    • If the values decrypted from the GooglePay Token contain a cavv value, then continue to the next step.
    • Note, if the values decrypted from the GooglePay Token do not contain a cavv value, then you can send the extracted payment details using a regular “non-GooglePay” payment flow, for example:
  2. Call the /payment REST API request with its mandatory parameters and include the following (as shown below):
    • paymentOption.card."brand"
    • paymentOption.card."last4Digits"
    • The externalMpi block containing relevant data extracted from the decrypted token.

      Note, paymentOption.card.threeD.externalMpi."eci" is optional.

    • Any other relevant data received on your server.
    • "userTokenId":"<unique customer identifier in merchant system - required for UPO creation>"
    Example /payment Request with Decrypted GooglePay Token
    {
  "sessionToken": "<sessionToken from getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system - required for UPO creation>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "currency": "EUR",
  "amount": "35",
  "paymentOption": {
    "card": {
      "cardNumber": "4390189522010496",
      "cardHolderName": "FL-BRW1",
      "expirationMonth": "12",
      "expirationYear": "25",
      "brand": "VISA",
      "last4Digits": "4567",
      "threeD": {
        "externalMpi": {
          "externalTokenProvider": "GooglePay",
          "eci": "2",
          "cavv": "ejJRWG9SWWRpU2I1M21DelozSXU="
        }
      }
    }
  },
  "billingAddress": {
    "email": "john.smith@email.com",
    "country": "BR"
  },
  "deviceDetails": {
    "ipAddress": "127.0.0.1"
  },
  "userDetails": {
    "country": "US"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
    Example /payment Response from Decrypted GooglePay Token
    {
  "reason": "",
  "authCode": "027203",
  "orderId": "36876651",
  "transactionStatus": "APPROVED",
  "clientRequestId": "PFYU0A4FK",
  "internalRequestId": 19297641,
  "version": "1.0",
  "transactionId": "2110000000005327976",
  "merchantSiteId": "126006",
  "transactionType": "Sale",
  "gwExtendedErrorCode": 0,
  "gwErrorCode": 0,
  "externalSchemeTransactionId": "0302026300910298",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "paymentOption": {
    "userPaymentOptionId": "8128691",
    "card": {
      "issuerBankName": "Banco Mercantil do Brasil S.A.",
      "ccCardNumber": "4****0496",
      "bin": "439018",
      "avsCode": "G",
      "threeD": {},
      "cardType": "Credit",
      "ccExpMonth": "12",
      "ccExpYear": "25",
      "issuerCountry": "BR",
      "isPrepaid": "false",
      "acquirerId": "103",
      "cardBrand": "VISA",
      "cvv2Reply": "",
      "last4Digits": "0496"
    }
  },
  "sessionToken": "50bfe77a-5b0b-498c-b9fc-c6523763715c",
  "userTokenId": "D3UERI4KDQK7",
  "externalTransactionId": "",
  "fraudDetails": {
    "score": "0",
    "system": {
      "systemId": "1",
      "decision": "None"
    },
    "finalDecision": "Accept"
  },
  "status": "SUCCESS"
}

Recurring Payments

Follow these steps to integrate Google Pay recurring payments into your payment flow.
Recurring payments involves two types of payments:

  • The Initial recurring payment
  • One or more Subsequent recurring payments

Follow these steps in the sections below to integrate Google Pay recurring payments into your payment flow.

Complete the payment using the relevant flow:

For Initial Recurring Payments

Including a userTokenId (unique customer identifier in the merchant system) in the /payment request:

  • Allows Nuvei to create a UPO (user payment option) record to store the customer payment method details.
  • The system returns an encrypted userPaymentOptionId which can be used in future transactions to represent the customer payment method.

If you do not wish to use Nuvei UPOs, then contact the Nuvei Integration Team to configure your merchant account accordingly.

Send a /payment request with its mandatory parameters and include these additional parameters:

  • "isRebilling": "0"
  • "userTokenId":"<unique customer identifier in merchant system - required for UPO creation>"
  • paymentOption.card.externalToken.”externalTokenProvider": "GooglePay"
  • paymentOption.card.externalToken."mobileToken": "<encrypted GooglePay Token converted to a string>"

    Format the mobileToken value as a string:

    1. Retrieve the paymentMethod block (returned in JSON format by Google Pay, in the previous step) from the response console panel of your payment page.
    2. Convert the “entire” encrypted paymentMethod block into a string (“JSON to String”).
Example /payment Request Initial Recurring Payments
{
  "sessionToken": "<sessionToken from getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "amount": "200",
  "currency": "USD",
  "userTokenId": "<unique customer identifier in merchant system - required for UPO creation>",
  "isRebilling": "0",
  "paymentOption": {
    "card": {
      "externalToken": {
        "externalTokenProvider": "GooglePay",
        "mobileToken": "<string of the GooglePayToken>" 
      }
    }
  },
  "billingAddress":{
    "email": "john.smith@email.com",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress": "127.0.0.1"
  },
  "userDetails": {
    "country": "US"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"  
}
Example /payment Response for Initial Recurring Payments
{
    "reason": "",
    "authCode": "0E5E04",
    "orderId": "36726421",
    "transactionStatus": "APPROVED",
    "clientRequestId": "V8UE4312Y",
    "customData": "Custom Data for C-Panel Reports",
    "internalRequestId": 19054731,
    "version": "1.0",
    "transactionId": "2110000000005034514",
    "merchantSiteId": "126006",
    "transactionType": "Sale",
    "gwExtendedErrorCode": 0,
    "gwErrorCode": 0,
    "merchantId": "2502136204546424962",
    "clientUniqueId": "695701003",
    "errCode": 0,
    "paymentOption": {
        "userPaymentOptionId": "8107431",
        "card": {
            "issuerBankName": "Legence Bank",
            "ccCardNumber": "4****1112",
            "externalTokenProvider": "GooglePay",
            "bin": "417577",
            "avsCode": "",
            "threeD": {},
            "ccExpMonth": "08",
            "ccExpYear": "25",
            "isPrepaid": "false",
            "acquirerId": "18",
            "cardBrand": "VISA",
            "cvv2Reply": "",
            "last4Digits": "1112"
        }
    },
    "sessionToken": "f3b77f95-d126-40bc-b1a9-2cf24fff811d",
    "userTokenId": "9XL74BK99KBW",
    "externalTransactionId": "",
    "fraudDetails": {
        "score": "0",
        "system": {
            "systemId": "1",
            "decision": "None"
        },
        "finalDecision": "Accept"
    },
    "status": "SUCCESS"
}

For Subsequent Recurring Payments

To complete the payment flow for subsequent recurring payments, send the /payment requests with their mandatory parameters and include these additional parameters:

  • "userTokenId": "<unique customer identifier in merchant system - required for UPO creation>"
  • "isRebilling": "1"
  • "relatedTransactionId": "<transactionId from the original customer-initiated transaction>"
  • paymentOption."userPaymentOptionId": "<userPaymentOptionId returned by the initial recurring payment request>"
    This represents the original payment method selected by the customer, and links subsequent payments to the initial recurring payment.
Example /payment Request for a Subsequent Recurring Payment
{
  "sessionToken": "<sessionToken from getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "amount": "200",
  "currency": "USD",
  "userTokenId": "<unique customer identifier in merchant system - required for UPO creation>",
  "isRebilling": "1",
  "relatedTransactionId": "<transactionId from the original customer-initiated transaction>",
  "paymentOption": {
    "userPaymentOptionId": "<userPaymentOptionId returned by the initial recurring payment request>"
  },
  "billingAddress":{
    "email": "john.smith@email.com",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress": "127.0.0.1"
  },
  "userDetails": {
    "country": "US"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"  
}
Example /payment Response for a Subsequent Recurring Payment
{
  "reason":"",
  "authCode":"042323",
  "orderId":"36733441",
  "transactionStatus":"APPROVED",
  "clientRequestId":"6X71VHFI7",
  "customData":"Custom Data for C-Panel Reports",
  "internalRequestId":19061291,
  "version":"1.0",
  "transactionId":"2110000000005045501",
  "merchantSiteId":"126006",
  "transactionType":"Sale",
  "gwExtendedErrorCode":0,
  "gwErrorCode":0,
  "merchantId":"2502136204546424962",
  "clientUniqueId":"695701003",
  "errCode":0,
  "paymentOption":{
    "userPaymentOptionId":"8102691",
    "card":{
      "issuerBankName":"Legence Bank",
      "ccCardNumber":"4****1112",
      "bin":"401200",
      "avsCode":"G",
      "threeD":{},
      "cardType":"Credit",
      "ccExpMonth":"08",
      "ccExpYear":"25",
      "issuerCountry":"US",
      "isPrepaid":"false",
      "acquirerId":"103",
      "cardBrand":"VISA",
      "cvv2Reply":"",
      "last4Digits":"1112"
    }
  },
  "sessionToken":"1652b07c-e71e-470c-82be-0ce9c2c4a864",
  "userTokenId":"790RAMSZPG7H",
  "externalTransactionId":"",
  "fraudDetails":{
    "score":"0",
    "system":{
      "systemId":"1",
      "decision":"None"
    },
    "finalDecision":"Accept"
  },
  "status":"SUCCESS"
}