On this page:

Overview
Set Up the Google Pay UI
Nuvei Decrypts Token
Merchant Decrypts Token
Payout (Withdrawal) Flow
Recurring Payments
- For Initial Recurring Payments
- For Subsequent Recurring Payments
Appendices
- brand Values

Overview

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

The integration steps described below are for Beta Testing purposes.
Please contact a Nuvei Integration Specialist for assistance.

Google Pay Integrations

Nuvei supports both 3D-Secure and Non-3D-Secure integrations.

To use the 3D-Secure integration, contact the Nuvei Integration Team to enable Google Pay 3D processing in your merchant account.

Setting Up the Google Pay UI

Setting up the Google Pay UI is the first step of all the implementations.

Nuvei supports these integrations:

Payments
- Payments – Nuvei Decrypts the Token
  You can send the Google Pay token “as-is” in the following types of /payment requests, and “behind the scenes”, Nuvei decrypts and uses the relevant data extracted from the token:
  - Non-3DS Payments
    This allows you to send the Google Pay token in a /payment request (without 3DS).
  - 3DS Payments
    Performs 3D authentication on the card using Nuvei (in addition to the Google Pay authentication).
- Payments – Merchant Decrypts the Token
  You can decrypt the Google Pay token, and then use the relevant data extracted from the token to send the following types of /payment requests:
  - Non-3DS Payments
    This allows you to send a /payment request without performing any additional 3DS authentication on the card.
  - External 3DS Provider
    If you use an external (third-party) 3DS provider to perform additional 3D card authentication, then you can include the 3DS authentication data provided by them, in the /payment request.
  - Nuvei as the 3DS Provider
    This allows you to send the relevant data extracted from the Google Pay token a /payment request, as well as perform 3D authentication on the card using Nuvei (in addition to the Google Pay authentication).
Recurring Payments
You can perform both Initial Recurring Payments and Subsequent Recurring Payments using the encrypted Google Pay token.

Google Pay also supports .

Prerequisites and Notes

This guide assumes you have completed all account setup prerequisites, and are ready to integrate Google Pay 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:
- Google Pay Web Developer Documentation
- Google Pay Brand Promoting Guidelines
  For your domain to be verified with Google, the merchant must send Nuvei’s Integration Team screenshots (like the one shown below) of your payment flow along with your domain URL:
- Google Pay Test Card Suite
- Google Pay Web Integration Checklist
  
  Only some information in the pages listed are relevant to Nuvei integration. Other information is relevant only for merchants performing a direct Google Pay integration, without Nuvei.

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.
The first time a card is used in the Google Pay system, Google Pay performs a 3DS authentication and stores the 3DS values from the successful Google Pay authentication in a Google Pay token.
Google Pay supports recurring payments only if you (the merchant) conform 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 Google Pay and Apple Pay).
These providers typically:

Collect the customer payment method and transaction details.
In some cases, they perform 3D-Secure authentication and provide the 3D-Secure authentication values.

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

Create the Google Pay UI button according to the instructions in the Google Pay for Web Payments Brand Guidelines Guide.
On your payment page, define the tokenizationSpecification constant as shown below.
(When the customer presses the Google Pay button, this parameter identifies your gateway and your site’s gateway merchant identifier.)

Example tokenizationSpecification 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 as an encrypted Google Pay token.

The customer triggers the Google Pay payment flow by pressing the Google Pay button.
At this point, your customer may be asked to log in to their Google Pay account.
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.
The customer selects a payment method and Google Pay returns the encrypted Google Pay token (containing the paymentMethod class in JSON format).

Press here to see more information regarding payment data cryptography.

Nuvei Decrypts Token

Use this integration when you manage the Google Pay Button yourself in your own payment flow, and now you want to send a payment request.

The Google Pay token contains Google Pay authentication values from a successful Google Pay authentication. You can send the Google Pay token “as-is” in a /payment request, and “behind the scenes”, Nuvei decrypts and uses the relevant data contained in the token.

Perform these steps:

1. Initialize the Payment

The /initPayment request determines if the card supports 3D-Secure and initializes the payment in the Nuvei system.

Send an /initPayment request with its mandatory parameters and include these additional parameters:

userTokenId
paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
paymentOption.card.externalToken.mobileToken
Format the mobileToken value as a string:
1. Retrieve the paymentMethod class (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 class into a string (“JSON to String”).
paymentOption.card.threeD."methodNotificationUrl"
Including this is required for 3D-Secure v2 Web Browser Fingerprinting. (The issuer uses this URL to return fingerprinting notifications.)

Example `/initPayment` Request

{
  "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>"
      },
      "threeD": {        
        "methodNotificationUrl": "<methodNotificationURL>"
      }
    }
  },
  "billingAddress": {
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  }
}

Example `/initPayment` Response with `v2supported`: “true”

{
  "reason": "",
  "orderId": "33704071",
  "transactionStatus": "APPROVED",
  "customData": "merchant custom data",
  "internalRequestId": 10036001,
  "version": "1.0",
  "transactionId": "2110000000000587378",
  "merchantSiteId": "142033",
  "transactionType": "InitAuth3D",
  "gwExtendedErrorCode": 0,
  "gwErrorCode": 0,
  "merchantId": "427583496191624621",
  "clientUniqueId": "12345",
  "errCode": 0,
  "paymentOption": {
    "card": {
      "ccCardNumber": "5****5761",
      "bin": "511142",
      "ccExpMonth": "12",
      "ccExpYear": "25",
      "last4Digits": "5761",
      "threeD": {
        "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
        "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
        "v2supported": "true",
        "version": "2.1.0",
        "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
        "directoryServerId": "A000000003",
        "directoryServerPublicKey": "MIIFrjCCBJagAwIBAgIQB2rJm.."
      }
    }
  },
  "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
  "userTokenId": "230811147",
  "cardAuthMethod": "PAN_ONLY",
  "status": "SUCCESS"
}

cardAuthMethod was added to indicate the card authentication method (DPAN or PAN_ONLY) returned in the response.

Example `/initPayment` Response with `v2supported`: “false”

{
  "reason":"",
  "clientRequestId":"E3YD6LSZD",
  "internalRequestId":19125711,
  "version":"1.0",
  "merchantSiteId":"126006",
  "merchantId":"2502136204546424962",
  "clientUniqueId":"695701003",
  "errCode":0,
  "paymentOption":{
    "card":{
      "threeD":{
        "v2supported":"false"
      }
    }
  },
  "sessionToken":"3056e85e-6272-4c1c-999a-0519def10020",
  "userTokenId":"OHJD9R9CNLCF",
  "status":"SUCCESS"
}

2. Handling `/initPayment`

The /initPayment response determines the next step:

paymentOption.card.threeD.v2supported: “false”
This means the card does not support 3DS at all.
Process the payment in the 3.1 Payments – Non-3DS flow.
paymentOption.card.threeD.v2supported: “true”
Process the payment in the 3.2 Payments – 3DS-v2 flow.

3. Processing a Payment

Perform the relevant payment processing flow (as determined in the previous step – Handling /initPayment):

3.1 Non-3DS Payments
3.2 3DS v2 Payments

3.1 Non-3DS Payments

This allows you to send the Google Pay token in a /payment request without sending any 3DS values.

Call the /payment REST API request with its mandatory parameters. Include the data received on your server, in the externalToken class with these parameters:

paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
paymentOption.card.externalToken.mobileToken
Format the mobileToken value as a string:
1. Retrieve the paymentMethod class (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 class into a string (“JSON to String”).
userTokenId

Example `/payment` Request for Non-3DS

{
  "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": "[email protected]",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"  
}

Example `/payment` Response for Non-3DS

{
    "reason": "",
    "authCode": "0E5E04",
    "orderId": "36726421",
    "transactionStatus": "APPROVED",
    "clientRequestId": "V8UE4312Y",
    "customData": "Custom Data for Control 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"
}

3.2 3DS-v2 Payments

This allows you to perform 3D authentication on the card using Nuvei (in addition to the Google Pay authentication).

The remaining steps to process a 3D-Secure v2 payment for a Google Pay payment, are almost identical to the standard server-to-server REST payment flow.
Perform the following standard REST payment flow steps by pressing the link to see the steps, and perform the steps together with any changes indicated below:

3D-Secure Fingerprinting
Perform steps as-is (no changes).

3D-Secure v2 Payment Request
Perform the standard steps and include the relevant data from the 3D-Secure Fingerprinting, and the following parameters (as shown below):

userTokenId
relatedTransactionId
Instead of “actual card details“ or a paymentOption.userPaymentOptionId, substitute the following:
- paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
- paymentOption.card.externalToken.mobileToken
  Format the mobileToken value as a string:
  1. Retrieve the paymentMethod class (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 class into a string (“JSON to String”).
paymentOption.card.threeD class containing relevant data returned from the 3D-Secure Fingerprinting.
billingAddress and paymentOption classes that contain mandatory parameters.

Example `/payment` Request with 3D-Secure v2 Parameters

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "USD",
  "userTokenId": "<unique customer identifier in merchant system – required for UPO creation>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "relatedTransactionId": "<initPayment TransactionId>",
  "paymentOption": {
    "card": {
      "externalToken": {
        "externalTokenProvider": "GooglePay",
        "mobileToken": "<encrypted GooglePay Token converted to a string>"
      },
      "threeD": {
        "methodCompletionInd": "Y",
        "version": "2.1.0",
        "notificationURL": "<notificationURL>",
        "merchantURL": "<merchantURL>",
        "platformType": "02",
        "v2AdditionalParams": {
          "challengeWindowSize": "05"
        },
        "browserDetails": {
          "acceptHeader": "text/html,application/xhtml+xml",
          "ip": "192.168.1.11",
          "javaEnabled": "TRUE",
          "javaScriptEnabled": "TRUE",
          "language": "EN",
          "colorDepth": "48",
          "screenHeight": "400",
          "screenWidth": "600",
          "timeZone": "0",
          "userAgent": "Mozilla"
        }
      }
    }
  },
  "billingAddress": {
    "country": "US",
    "email": "[email protected]"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

3D-Secure Challenge
Conditional – Only when a challenge is required.

Final Payment Request
Conditional – Based on the outcome of the 3D-Secure Challenge, you may need to send a final Liability Shift /payment request:

Sending a final Liability Shift /payment Request

Complete the payment by sending a /payment request with its mandatory parameters and include these additional parameters:

userTokenId
relatedTransactionId
Instead of “actual card details“ or a paymentOption.userPaymentOptionId, substitute the following:
- paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
- paymentOption.card.externalToken.mobileToken
  Format the mobileToken value as a string:
  1. Retrieve the paymentMethod class (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 class into a string (“JSON to String”).

Example Liability Shift `/payment` Request (3D-Secure v2)

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantSiteId>",
  "merchantSiteId": "<your merchantId>",
  "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>",
  "relatedTransactionId": "<TransactionId of the first payment request>",
  "paymentOption": {
    "card": {
      "externalToken": {
        "externalTokenProvider": "GooglePay",
        "mobileToken": "<encrypted GooglePay Token converted to a string>"
      }
    },
    "billingAddress": {
      "country": "US",
      "email": "[email protected]"
    },
    "deviceDetails": {
      "ipAddress": "<customer's IP address>"
    },
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
  }
}

Liability Shift `/payment` (3D-Secure v2) Response

The response includes these parameters:

Returned from the external token provider:
- paymentOption.card.externalToken.eciProvider: “<value from GooglePay>“
Returned from the 3DS authentication process:
- paymentOption.card.threeD.externalMpi.eci: “<eci value>“
- paymentOption.card.threeD.externalMpi.cavv: “<cavv value>“

A Direct Merchant Notification (DMN) is sent to you containing the response details of the request:

Example Liability Shift `/payment` (3D-Secure v2) DMN

...'ppp_status=FAIL&Status=ERROR&ExErrCode=1289&ErrCode=-1100&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=Issuer+data+is+not+available%2C+please+try+again+later&ReasonCode=1289&PPP_TransactionID=37893001&userid=ZDMIYVPRAJCB&merchant_unique_id=695701003&customData=Custom+Data%21&productId=MAH3ST7266GM&first_name=Wxjtyskuuj&last_name=Pauwbeuyid&email=jhahn.jhnui%40srzaw.cb&currency=EUR&clientUniqueId=695701003&customField1=customField1-valueU&customField2=customField2-valueU&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=340689+Billing+Str.+Updated.&address2=&country=Germany&state=&city=Billing+City+Updated&zip=BNE+4895U&phone1=359888797070&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=CL-BRW1&cardNumber=5****0902&bin=535275&noCVV=&acquirerId=99&expMonth=12&expYear=25&Token=SABHAGUAUABuAFAAMAAwAGQAZAAwAEYAbgAyAEgAZwBoADYARgAlACgAUABFAF0ANgB0AHgAVgBSAHkANABbAHoAJQBTAFMAeQAsAEMAeABjAHQAcgBfADgAPgBnAE0AXABiAGwAMwA%3D&tokenId=1688429575&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=&shippingCity=Shipping+City+Updated&shippingAddress=33+Shipping+Str.+Updated.&shippingZip=SDC+33334U&shippingFirstName=Mlxdwieffa&shippingLastName=Uvnoirngbg&shippingPhone=359888576900&shippingCell=359887576903&shippingMail=gmwch.bphmv%40ducdb.qz&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=ERROR&merchantLocale=&unknownParameters=&payment_method=cc_card&ID=&merchant_id=2502136204546424962&responseTimeStamp=2022-08-01.07%3A57%3A52&buyButtonProductId=&webMasterId=9IFAQ4ARB0IX&appliedPromotions=&uniqueCC=RHZ4oBPNguWJuqKZFoGGpmzIDw0%3D&transactionType=Auth&externalEmail=&cardCompany=MasterCard&eci=2&user_token_id=ZDMIYVPRAJCB&userPaymentOptionId=8303261&TransactionID=2110000000006785046&externalAccountDescription=nameOnCard%3ACL-BRW1&finalFraudDecision=Accept&fraudScore=0&systemID=1&systemDecision=None&totalAmount=35.0&dynamicDescriptor=Cashier+API+U&item_name_1=Item+1U&item_number_1=&item_amount_1=35.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&houseNumber=&customCurrency=&externalToken_blockedCard=0&externalToken_cardAcquirerId=0&externalToken_cardAcquirerName=&externalToken_cardBin=0&externalToken_cardBrandId=0&externalToken_cardBrandName=&externalToken_cardExpiration=0&externalToken_cardLength=0&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=0&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=0&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=5&upoRegistrationDate=20220801&cavv=kHQxQjBDQTAyRDlDNEE0NzRFMTc%3D&shippingCounty=SCountyU&type=DEPOSIT&clientRequestId=16WH99KFX&relatedTransactionId=2110000000006785044&externalTokenProvider=GooglePay&threeDSVersion=2.1.0&isLiabilityOnIssuer=1&challengePreferenceReason=0&lastFourDigits=0902&responsechecksum=36291b228a50daceaeccfb5b563df484&advanceResponseChecksum=c3c6afdf8fdeb352839e28d262d3aec5',

Merchant Decrypts Token

The integration steps described below are for Beta Testing purposes.
Please contact a Nuvei Integration Specialist for assistance.

This integration is used when you manage the Google Pay Button by yourself in your own payment flow, and now you want to decrypt the Google Pay token, and then use the relevant data extracted from the token to send a /payment request.

You can decrypt the Google Pay token, which contains Google Pay authentication values from a successful Google Pay authentication.

Sometimes a Google Pay token does not contain a cryptogram parameter (for example, PAN_Only tokens, where Google Pay did not authenticate the card).
In that case, when calling a /payment request, paymentOption.card.externalToken.cryptogram is not required.

Decrypt the Google Pay token, and then use the relevant data extracted from the token to send the following types of /payment requests:

Non-3DS Payments
This allows you to send a /payment request (without 3DS).
External 3DS Provider
If you use an external (third-party) 3DS provider to perform additional 3D card authentication, then you can include the 3DS authentication data provided by them, in the /payment request.
Nuvei as the 3DS Provider
This allows you to send the relevant data extracted from the Google Pay token a /payment request, as well as perform 3D authentication on the card using Nuvei (in addition to the Google Pay authentication).

We have included a description of how the old “Merchant Decrypts Token” integration works. See the Appendix for details.

Non-3DS Payments

This allows you to send a /payment request without performing any additional 3DS authentication on the card.

Decrypt the Google Pay token yourself (according to Google Pay’s requirements), and send relevant extracted data by calling a /payment REST API request with its mandatory parameters, and include the following (as shown below):

userTokenId
paymentOption.card.cardNumber
paymentOption.card.expirationMonth
paymentOption.card.expirationYear
paymentOption.card.brand (press here to see possible values)
paymentOption.card.last4Digits
paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
paymentOption.card.externalToken.cryptogram: “<cryptogram from Google Pay>” (Conditional, only mandatory for DPAN flows)
paymentOption.card.externalToken.eciProvider: “<value from Google Pay>” (Optional)
Any other relevant data received on your server.

Example `/payment` Request with Decrypted Google Pay Token

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"200",
  "currency":"USD",
  "userTokenId":"<unique customer identifier in merchant system – required for UPO creation>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "card":{
      "cardNumber":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"GooglePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      }
    }
  },
  "billingAddress":{
    "email":"[email protected]",
    "country":"US"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "userDetails": {
    "country":"US"
  }, 
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example `/payment` Response for Non-3DS

{
    "reason": "",
    "authCode": "0E5E04",
    "orderId": "36726421",
    "transactionStatus": "APPROVED",
    "clientRequestId": "V8UE4312Y",
    "customData": "Custom Data for Control 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****0496",
            "externalTokenProvider": "GooglePay",
            "bin": "4390189",
            "avsCode": "",
            "threeD": {
            },
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "isPrepaid": "false",
            "acquirerId": "18",
            "cardBrand": "VISA",
            "cvv2Reply": "",
            "last4Digits": "0496"
        }
    },
    "sessionToken": "f3b77f95-d126-40bc-b1a9-2cf24fff811d",
    "userTokenId": "9XL74BK99KBW",
    "externalTransactionId": "",
    "fraudDetails": {
        "score": "0",
        "system": {
            "systemId": "1",
            "decision": "None"
        },
        "finalDecision": "Accept"
    },
    "status": "SUCCESS"
}

External 3DS Provider

If you use an external (third-party) 3DS provider to perform additional 3D card authentication, then you must include the 3DS authentication data provided by them, in the /payment request.

Decrypt the Google Pay token yourself (according to Google Pay’s requirements), and send the relevant extracted data by calling a /payment REST API request with its mandatory parameters, and include the following (as shown below):

userTokenId
paymentOption.card.cardNumber
paymentOption.card.expirationMonth
paymentOption.card.expirationYear
paymentOption.card.brand (press here to see possible values)
paymentOption.card.last4Digits
paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
paymentOption.card.externalToken.cryptogram: “<cryptogram from Google Pay>” (Conditional, only mandatory for DPAN flows)
paymentOption.card.externalToken.eciProvider: “<value from Google Pay>” (Optional)
paymentOption.card.threeD.externalMpi (class containing relevant data 3DS authentication data provided by the external (third-party) 3DS provider.)
paymentOption.card.threeD.externalMpi.eci
paymentOption.card.threeD.externalMpi.cavv
paymentOption.card.threeD.externalMpi.dsTransID
Any other relevant data received on your server.

Example `/payment` Request with Decrypted Google Pay Token

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"200",
  "currency":"USD",
  "userTokenId":"<unique customer identifier in merchant system – required for UPO creation>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "card":{
      "cardNumber":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"GooglePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      },
      "threeD":{
        "externalMpi":{
          "eci":"2",
          "cavv":"ejJRWG9SWWRpU2I1M21DelozSXU=",
          "dsTransID":"9e6c6e9b-b390-4b11-ada9-0a8f595e8600" 
        }
      }
    }
  },
  "billingAddress":{
    "email":"[email protected]",
    "country":"US"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "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"
}

Nuvei as the 3DS Provider

This allows you to decrypt the Google Pay token and send the relevant data extracted from the Google Pay token a /payment request, as well as perform 3D authentication on the card using Nuvei (in addition to the Google Pay authentication), as shown below:

1. Decrypt Google Pay Token

Decrypt the Google Pay token according to Google Pay’s requirements.

Sometimes a Google Pay token does not contain a cryptogram parameter (for example, PAN_Only tokens, where Google Pay did not authenticate the card).
In that case, when calling a /payment request, paymentOption.card.externalToken.cryptogram is not required.

2. Initialize the Payment

The /initPayment request determines if the card supports 3D-Secure and initializes the payment in the Nuvei system.

Send the relevant data extracted from the Google Pay token in an /initPayment request with its mandatory parameters, and include the following (as shown below):

userTokenId
paymentOption.card.cardNumber
paymentOption.card.expirationMonth
paymentOption.card.expirationYear
paymentOption.card.brand (press here to see possible values)
paymentOption.card.last4Digits
paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
paymentOption.card.externalToken.cryptogram: “<cryptogram from Google Pay>” (Conditional, only mandatory for DPAN flows)
paymentOption.card.externalToken.eciProvider: “<value from Google Pay>” (Optional)
paymentOption.card.threeD.methodNotificationUrl
Including this is required for 3D-Secure v2 Web Browser Fingerprinting. (The issuer uses this URL to return fingerprinting notifications.)
Any other relevant data received on your server.

Example `/initPayment` Request

{
  "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":{
      "cardNumber":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"GooglePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      },
      "threeD": {        
        "methodNotificationUrl": "<methodNotificationURL>"
      }
    }
  },
  "billingAddress": {
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  }
}

Example `/initPayment` Response with `v2supported`: “true”

{
  "reason": "",
  "orderId": "33704071",
  "transactionStatus": "APPROVED",
  "customData": "merchant custom data",
  "internalRequestId": 10036001,
  "version": "1.0",
  "transactionId": "2110000000000587378",
  "merchantSiteId": "142033",
  "transactionType": "InitAuth3D",
  "gwExtendedErrorCode": 0,
  "gwErrorCode": 0,
  "merchantId": "427583496191624621",
  "clientUniqueId": "12345",
  "errCode": 0,
  "paymentOption": {
    "card": {
      "issuerCountry": "US",
      "ccCardNumber": "4****0496",
      "bin": "439018",
      "threeD": {
        "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImVkNGZlNTkzLWUzMWUtNDEyMC05M2EwLTBkNDBhNzUxNzEzMSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
        "methodUrl": "https://srv-azr-acq2:4435/api/ThreeDSMethod/threeDSMethodURL",
        "v2supported": "true",
        "version": "2.2.0",
        "serverTransId": "ed4fe593-e31e-4120-93a0-0d40a7517131",
        "directoryServerId": "A000000003",
        "directoryServerPublicKey": "MIIFrjCCBJagAwIBAgIQB2rJm.."
      },
      "cardType": "Credit", 
      "ccExpMonth": "12",
      "ccExpYear": "25",
      "last4Digits": "0496"
    }
  },
  "sessionToken": "e524e7c5-9855-4ce9-b0f9-1045f34fd526",
  "userTokenId": "230811147",
  "status": "SUCCESS"
}

Example `/initPayment` Response with `v2supported`: “false”

{
  "reason": "",
  "clientRequestId": "E3YD6LSZD",
  "internalRequestId": 19125711,
  "version": "1.0",
  "merchantSiteId": "126006",
  "merchantId": "2502136204546424962",
  "clientUniqueId": "695701003",
  "errCode": 0,
  "paymentOption": {
    "card": {
      "threeD": {
        "v2supported": "false"
      }
    }
  },
  "sessionToken": "3056e85e-6272-4c1c-999a-0519def10020",
  "userTokenId": "OHJD9R9CNLCF",
  "status": "SUCCESS"
}

3. Handling `/initPayment`

The /initPayment response determines the next step:

paymentOption.card.threeD.v2supported: “false”
This means the card does not support 3DS at all.
Process the payment in the Non-3DS Payments flow (described above).
paymentOption.card.threeD.v2supported: “true”
Process the payment in the 4. Payments – 3DS-v2 flow.

4. 3DS v2 Payments

This allows you to perform 3D authentication on the card using Nuvei (in addition to the Google Pay authentication).

3D-Secure Fingerprinting
Perform steps as-is (no changes).

3D-Secure v2 Payment Request
Perform the standard steps and include the relevant data extracted from the Google Pay token and from the 3D-Secure Fingerprinting (as shown below):

userTokenId
relatedTransactionId
paymentOption.card.cardNumber
paymentOption.card.expirationMonth
paymentOption.card.expirationYear
paymentOption.card.brand (press here to see possible values)
paymentOption.card.last4Digits
paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
paymentOption.card.externalToken.cryptogram: “<cryptogram from Google Pay>” (Conditional, only mandatory for DPAN flows)
paymentOption.card.externalToken.eciProvider: “<value from Google Pay>” (Optional)
paymentOption.card.threeD class containing relevant data returned from the 3D-Secure Fingerprinting.
Any other relevant data received on your server.

Example `/payment` Request with 3D-Secure v2 Parameters

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount":"200",
  "currency":"USD",
  "userTokenId":"<unique customer identifier in merchant system – required for UPO creation>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "relatedTransactionId": "<initPayment TransactionId>",
  "paymentOption":{
    "card":{
      "cardNumber":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"GooglePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      },
      "threeD": {
        "methodCompletionInd": "Y",
        "version": "2.2.0",
        "notificationURL": "<notificationURL>",
        "merchantURL": "<merchantURL>",
        "platformType": "02",
        "v2AdditionalParams": {
          "challengePreference": "02",
          "challengeWindowSize": "05"
        },
        "browserDetails": {
          "acceptHeader": "text/html,application/xhtml+xml",
          "ip": "192.168.1.11",
          "javaEnabled": "TRUE",
          "javaScriptEnabled": "TRUE",
          "language": "EN",
          "colorDepth": "48",
          "screenHeight": "400",
          "screenWidth": "600",
          "timeZone": "0",
          "userAgent": "Mozilla"
        }
      }
    }
  },
  "billingAddress": {
    "country": "US",
    "email": "[email protected]"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

3D-Secure Challenge
Conditional – Only when a challenge is required.

Final Payment Request
Conditional – Based on the outcome of the 3D-Secure Challenge, you may need to send a final Liability Shift /payment request:

Sending a final Liability Shift /payment Request

Complete the payment by sending a /payment request with its mandatory parameters and include these additional parameters:

userTokenId
relatedTransactionId
paymentOption.card.cardNumber
paymentOption.card.expirationMonth
paymentOption.card.expirationYear
paymentOption.card.brand (press here to see possible values)
paymentOption.card.last4Digits
paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
paymentOption.card.externalToken.cryptogram: “<cryptogram from Google Pay>” (Conditional, only mandatory for DPAN flows)
paymentOption.card.externalToken.eciProvider: “<value from Google Pay>” (Optional)

Example Liability Shift `/payment` Request (3D-Secure v2)

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantSiteId>",
  "merchantSiteId":"<your merchantId>",
  "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>",
  "relatedTransactionId":"<transactionId of the first payment request>",
  "paymentOption":{
    "card":{
      "cardNumber":"4390189522010496",
      "expirationMonth":"12",
      "expirationYear":"25",
      "brand":"VISA",
      "last4Digits":"0496",
      "externalToken":{
        "externalTokenProvider":"GooglePay",
        "eciProvider":"5",
        "cryptogram":"ejJRWG9SWWRpU7I1M28DelozSXU="
      }
    }
  },
  "billingAddress":{
    "country":"US",
    "email":"[email protected]"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Liability Shift `/payment` (3D-Secure v2) Response

The response includes these parameters:

Returned from the external token provider:
- paymentOption.card.externalToken.eciProvider: “<value from GooglePay>“
Returned from the 3DS authentication process:
- paymentOption.card.threeD.externalMpi.eci: “<eci value>“
- paymentOption.card.threeD.externalMpi.cavv: “<cavv value>“

Example Liability Shift `/payment` (3D-Secure v2) DMN

A DMN is sent to you containing the response details of the request:

...'ppp_status=FAIL&Status=ERROR&ExErrCode=1289&ErrCode=-1100&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=Issuer+data+is+not+available%2C+please+try+again+later&ReasonCode=1289&PPP_TransactionID=37893001&userid=ZDMIYVPRAJCB&merchant_unique_id=695701003&customData=Custom+Data%21&productId=MAH3ST7266GM&first_name=Wxjtyskuuj&last_name=Pauwbeuyid&email=jhahn.jhnui%40srzaw.cb&currency=EUR&clientUniqueId=695701003&customField1=customField1-valueU&customField2=customField2-valueU&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=340689+Billing+Str.+Updated.&address2=&country=Germany&state=&city=Billing+City+Updated&zip=BNE+4895U&phone1=359888797070&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=CL-BRW1&cardNumber=5****0902&bin=535275&noCVV=&acquirerId=99&expMonth=12&expYear=25&Token=SABHAGUAUABuAFAAMAAwAGQAZAAwAEYAbgAyAEgAZwBoADYARgAlACgAUABFAF0ANgB0AHgAVgBSAHkANABbAHoAJQBTAFMAeQAsAEMAeABjAHQAcgBfADgAPgBnAE0AXABiAGwAMwA%3D&tokenId=1688429575&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=US&shippingState=&shippingCity=Shipping+City+Updated&shippingAddress=33+Shipping+Str.+Updated.&shippingZip=SDC+33334U&shippingFirstName=Mlxdwieffa&shippingLastName=Uvnoirngbg&shippingPhone=359888576900&shippingCell=359887576903&shippingMail=gmwch.bphmv%40ducdb.qz&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=126006&merchant_status=&action=&requestVersion=&message=ERROR&merchantLocale=&unknownParameters=&payment_method=cc_card&ID=&merchant_id=2502136204546424962&responseTimeStamp=2022-08-01.07%3A57%3A52&buyButtonProductId=&webMasterId=9IFAQ4ARB0IX&appliedPromotions=&uniqueCC=RHZ4oBPNguWJuqKZFoGGpmzIDw0%3D&transactionType=Auth&externalEmail=&cardCompany=MasterCard&eci=2&user_token_id=ZDMIYVPRAJCB&userPaymentOptionId=8303261&TransactionID=2110000000006785046&externalAccountDescription=nameOnCard%3ACL-BRW1&finalFraudDecision=Accept&fraudScore=0&systemID=1&systemDecision=None&totalAmount=35.0&dynamicDescriptor=Cashier+API+U&item_name_1=Item+1U&item_number_1=&item_amount_1=35.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&houseNumber=&customCurrency=&externalToken_blockedCard=0&externalToken_cardAcquirerId=0&externalToken_cardAcquirerName=&externalToken_cardBin=0&externalToken_cardBrandId=0&externalToken_cardBrandName=&externalToken_cardExpiration=0&externalToken_cardLength=0&externalToken_cardMask=&externalToken_cardName=&externalToken_cardTypeId=0&externalToken_cardTypeName=&externalToken_clubName=&externalToken_creditCompanyId=0&externalToken_creditCompanyName=&externalToken_extendedCardType=&externalToken_Indication=&externalToken_tokenValue=&externalToken_tokenProvider=&ECIRaw=5&upoRegistrationDate=20220801&cavv=kHQxQjBDQTAyRDlDNEE0NzRFMTc%3D&shippingCounty=SCountyU&type=DEPOSIT&clientRequestId=16WH99KFX&relatedTransactionId=2110000000006785044&externalTokenProvider=GooglePay&threeDSVersion=2.1.0&isLiabilityOnIssuer=1&challengePreferenceReason=0&lastFourDigits=0902&responsechecksum=36291b228a50daceaeccfb5b563df484&advanceResponseChecksum=c3c6afdf8fdeb352839e28d262d3aec5',

Payout (Withdrawal) Flow

Gaming and Gambling merchants who wish to process a card payout transaction must provide cardData.cardHolderName to the payout request. Without this parameter, a payout may be rejected by the card schemes.

A payout is performed using the REST API /payout request.

A /payout request is performed using a previously deposit UPO (representing the customer bank account).

Call the /payout request with its mandatory parameters including:

userTokenId – Unique customer identifier in merchant system.
userPaymentOption class containing: userPaymentOptionId
deviceDetails class containing: ipAddress
urlDetails class containing: notificationUrl

Press here for more information about updating and/or adding user details.

Example `/payout` Request

{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "currency": "USD",
  "amount": "100",
  "userPaymentOption": {
    "userPaymentOptionId": "<UPO received from previous deposit>"
  },  
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "urlDetails": {
    "notificationUrl": "<URL to which DMNs are sent>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The request is processed and returns a transaction notification with the final status.

If the transaction is successful, then the following is returned:
- A response with status=APPROVED.
- A DMN containing status=APPROVED.
If the transaction is not successful, then the following is returned:
- A response with status=DECLINED.
- A DMN containing status=DECLINED.

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
For Subsequent Recurring Payments

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
paymentOption.card.externalToken.externalTokenProvider: “GooglePay“
paymentOption.card.externalToken.mobileToken
Format the mobileToken value as a string:
1. Retrieve the paymentMethod class (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 class 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": "<encrypted GooglePay Token converted to a string>" 
      }
    }
  },
  "billingAddress":{
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress": "<customer's IP address>"
  },
  "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 Control 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
isRebilling: “1“
relatedTransactionId
paymentOption.userPaymentOptionId
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": "[email protected]",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress": "<customer's IP address>"
  },
  "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 Control 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"
}

Appendices

`brand` Values

Visa
Mastercard
Maestro
AMEX
Diners
Discover

Payment with Decrypted Google Pay Token

This is a description of how the old “Merchant Decrypts Token” integration works.

The old “Merchant Decrypts Token” only works as a non-3DS flow.

If you want to use a 3DS flow integration where you can decrypt the Google Pay token and then send the relevant data extracted in a /payment request, then:

Contact the Nuvei Integration Team to enable Google Pay 3D processing in your merchant account.
See the details of our new flow in the Merchant Decrypts Token section above.

Old Flow for Payment with Decrypted Google Pay Token

The following description assumes that your merchant account is still not enabled for Google Pay 3D processing.

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

Perform these steps to process a Google Pay payment:

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:
  - See the Initialize 3D-Secure topic.
  - See the Non-3D-Secure Payment topic.

Call the /payment REST API request with its mandatory parameters and include the following (as shown below):

paymentOption.card.brand (press here to see possible values)
paymentOption.card.last4Digits
userTokenId
paymentOption.card.threeD.externalMpi (class containing relevant card details extracted from the decrypted token)
paymentOption.card.threeD.externalMpi.eci (optional)
paymentOption.card.threeD.externalMpi.cavv
paymentOption.card.threeD.externalMpi.externalTokenProvider: “GooglePay“

Example `/payment` Request only showing the 3DS parameters extracted from the Decrypted Google Pay Token

{ 
  ...
  "paymentOption":{
    "card":{ 
      ...
      "brand":"VISA",
      "last4Digits":"0496",
      "threeD":{
        "externalMpi":{
          "externalTokenProvider":"GooglePay",
          "eci":"2",
          "cavv":"ejJRWG9SWWRpU2I1M21DelozSXU="
        }
      }
    }
  },
  ...
}

Full Example `/payment` Request with Decrypted Google Pay 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",
      "expirationMonth": "12",
      "expirationYear": "25",
      "brand": "VISA",
      "last4Digits": "0496",
      "threeD": {
        "externalMpi": {
          "externalTokenProvider": "GooglePay",
          "eci": "2",
          "cavv": "ejJRWG9SWWRpU2I1M21DelozSXU="
        }
      }
    }
  },
  "billingAddress": {
    "email": "[email protected]",
    "country": "BR"
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "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"
}

Google Pay (REST API)

Overview

Google Pay Integrations

Setting Up the Google Pay UI

Prerequisites and Notes

Google Pay as an “External token provider”

Set Up the Google Pay UI

1. Authentication

2. The Google Pay UI Button

Example tokenizationSpecification Request

3. Collect the Card Details

Nuvei Decrypts Token

1. Initialize the Payment

Example /initPayment Request

Example /initPayment Response with v2supported: “true”

Example /initPayment Response with v2supported: “false”

2. Handling /initPayment

3. Processing a Payment

3.1 Non-3DS Payments

Example /payment Request for Non-3DS

Example /payment Response for Non-3DS

3.2 3DS-v2 Payments

Example /payment Request with 3D-Secure v2 Parameters

Example Liability Shift /payment Request (3D-Secure v2)

Liability Shift /payment (3D-Secure v2) Response

Example Liability Shift /payment (3D-Secure v2) DMN

Merchant Decrypts Token

Non-3DS Payments

Example /payment Request with Decrypted Google Pay Token

Example /payment Response for Non-3DS

External 3DS Provider

Example /payment Request with Decrypted Google Pay Token

Example /payment Response from Decrypted GooglePay Token

Nuvei as the 3DS Provider

1. Decrypt Google Pay Token

2. Initialize the Payment

Example /initPayment Request

Example /initPayment Response with v2supported: “true”

Example /initPayment Response with v2supported: “false”

3. Handling /initPayment

4. 3DS v2 Payments

Example /payment Request with 3D-Secure v2 Parameters

Example Liability Shift /payment Request (3D-Secure v2)

Liability Shift /payment (3D-Secure v2) Response

Example Liability Shift /payment (3D-Secure v2) DMN

Payout (Withdrawal) Flow

Example /payout Request

Recurring Payments

For Initial Recurring Payments

Example /payment Request Initial Recurring Payments

Example /payment Response for Initial Recurring Payments

For Subsequent Recurring Payments

Example /payment Request for a Subsequent Recurring Payment

Example /payment Response for a Subsequent Recurring Payment

Appendices

brand Values

Payment with Decrypted Google Pay Token

Old Flow for Payment with Decrypted Google Pay Token

Example /payment Request only showing the 3DS parameters extracted from the Decrypted Google Pay Token

Full Example /payment Request with Decrypted Google Pay Token

Example /payment Response from Decrypted GooglePay Token

Example `tokenizationSpecification` Request

Example `/initPayment` Request

Example `/initPayment` Response with `v2supported`: “true”

Example `/initPayment` Response with `v2supported`: “false”

2. Handling `/initPayment`

Example `/payment` Request for Non-3DS

Example `/payment` Response for Non-3DS

Example `/payment` Request with 3D-Secure v2 Parameters

Example Liability Shift `/payment` Request (3D-Secure v2)

Liability Shift `/payment` (3D-Secure v2) Response

Example Liability Shift `/payment` (3D-Secure v2) DMN

Example `/payment` Request with Decrypted Google Pay Token

Example `/payment` Response for Non-3DS

Example `/payment` Request with Decrypted Google Pay Token

Example `/payment` Response from Decrypted GooglePay Token

Example `/initPayment` Request

Example `/initPayment` Response with `v2supported`: “true”

Example `/initPayment` Response with `v2supported`: “false”

3. Handling `/initPayment`

Example `/payment` Request with 3D-Secure v2 Parameters

Example Liability Shift `/payment` Request (3D-Secure v2)

Liability Shift `/payment` (3D-Secure v2) Response

Example Liability Shift `/payment` (3D-Secure v2) DMN

Example `/payout` Request

Example `/payment` Request Initial Recurring Payments

Example `/payment` Response for Initial Recurring Payments

Example `/payment` Request for a Subsequent Recurring Payment

Example `/payment` Response for a Subsequent Recurring Payment

`brand` Values

Example `/payment` Request only showing the 3DS parameters extracted from the Decrypted Google Pay Token

Full Example `/payment` Request with Decrypted Google Pay Token

Example `/payment` Response from Decrypted GooglePay Token