Table of Contents
Overview
This article documents how to initiate a transaction using a Google Pay token with Direct Connect.
Supported Platforms
- WebMIS
Supported Solutions
- Direct Connect
Prerequisites
Before you get started, review the following prerequisites:
- The latest version of Direct Connect
- Test credentials for the NMI test platform
- A working test integration with Google Pay V2:
- InApp
-
Web
- When setting up your merchant account in the Google Pay Business Console for use with Google Pay for the Web, Google will ask if you are doing a Direct or Gateway integration; you should select Gateway.
Configuration
To correctly set up a Google Pay integration, you will first need to ensure the gateway tokenisation specification object is configured as follows. If you do not specify your Terminal ID or the gateway, the token generated will be invalid, and cannot be processed:
"tokenizationSpecification": { "type": "PAYMENT_GATEWAY", "parameters": { "gateway": "gatewayservices", "gatewayMerchantId": "<Your TerminalId>" } }
Please ensure you review the Google Pay documentation carefully, as there are some settings that may increase the potential risk on transactions, for example, enabling the PAN_ONLY
setting in the allowedAuthMethods
property. This authentication method is associated with payment cards stored on file with the user's Google Account. Returned payment data includes personal account number (PAN) with the expiration month and the expiration year.
NMI recommends only setting CRYPTOGRAM_3DS
, as this authentication method is associated with cards stored securely as Android device tokens, and configures Google Pay in a similar fashion to other digital wallet service providers. Returned payment data includes a 3-D Secure (3DS) cryptogram generated on the device.
Forming the Request Object
Once you have generated a valid Google Pay token, you can begin the process of sending a transaction request to the NMI Gateway using the token. NMI recommends using a back-office process to handle the transaction request to avoid instances where the transaction result may not be handled correctly due to communication issues on-device. If a back-office process is used, the token should be transferred from device to the system handling the request using a secure transport method.
A request object should be created, omitting any typical card details in favour of the Google Pay token supplied as an ExtendedProperty
:
C# Example
Request request = new Request { Amount = "<Amount>", AmountType = AmountType.Actual, AmountUnit = AmountUnit.Major, ApplicationId = "<Your ApplicationId>", CurrencyCode = "<ISO CurrencyCode>", ExtendedProperties = new Collection<ExtendedProperty> { new ExtendedProperty("digital-wallet", "googlepay"), new ExtendedProperty("googlepay-token", <GooglePayToken.PaymentData>), }, RequestType = RequestType.Auth, SoftwareName = "<Your SoftwareName>", SoftwareVersion = "<Your SoftwareVersion>", TerminalID = "<Your TerminalId>", TransactionKey = "<Your TransactionKey>", UserReference = "<A Unique Sale Reference>", };
PHP Example
$request = new Request(); $request->setAmount("<Amount>"); $request->setAmountType(AmountType_Actual); $request->setAmountUnit(AmountUnit_Major); $request->setApplicationId("<Your ApplicationId>"); $request->setCurrencyCode("<ISO CurrencyCode>"); $request->addExtendedProperty(new ExtendedProperty("digital-wallet", "googlepay")); $request->addExtendedProperty(new ExtendedProperty("googlepay-token", <GooglePayToken.PaymentData>)); $request->setRequestType(RequestType_Auth); $request->setSoftwareName("<Your SoftwareName>"); $request->setSoftwareVersion("<Your SoftwareVersion>"); $request->setTerminalID("<Your TerminalId>"); $request->setTransactionKey("<Your TransactionKey>"); $request->setUserReference("<A Unique Sale Reference>");
The integration should then proceed to send the request to the NMI Gateway for processing, and handle the response.
PAN_ONLY with 3DS
Direct Connect can be configured to inform the NMI Gateway to reject any PAN_ONLY
tokens if enabled and detected. The returned tokenized card data in the rejection message can then be submitted to NMI's 3DS MPI to upgrade the transaction. This is enabled through the use of the ExtendedProperty
digital-wallet-panonly-action
, which has two settings:
-
accept
=> The default value. Proceed as normal with the authorization. -
reject
=> Decline any transaction requests containing PAN_ONLY tokens. The transaction will be declined withErrorCode
6001
(DigitalWalletDecline) and the platform will return tokenized card data that can be submitted to NMI's 3DS MPI.
If the reject
setting is used and only if ErrorCode
6001
is returned in the Direct Connect response, the integration should proceed to carry out a 3DS2 request (please see our website for more details on how to integrate NMI's 3DS 3DS solution). Card tokens should be submitted in-place of PAN and expiry date:
-
PAN
=> Omitted -
ExpiryDate
=> Omitted -
ExpiryDateFormat
=> Omitted -
CardGuid
=>{CardReference}
-
CardHash
=>{CardHash}
Please note that due to the nature of the staging platform, the default card associated with all Google Pay tokens is not enrolled in 3DS. You can, however, substitute the CardGuid
and CardHash
at any point of the transaction with the tokens from a 3DS event card from our Test Cards list to invoke that response and test the integration. See Test Card PANs for use with 3-D Secure for more details.
Once the integration has obtained an approved 3DS response it should submit a new request via Direct Connect attaching all of the available 3DS details obtained in the previous response. Please note the examples below contain example elements - the actual data set returned during a 3DS request can vary depending on the result.
C# Example
Request request = new Request { Amount = "<Amount>", AmountType = AmountType.Actual, AmountUnit = AmountUnit.Major, ApplicationId = "<Your ApplicationId>", CardHash = "<Card Hash>", CardReference = "<Card Reference>", CurrencyCode = "<ISO CurrencyCode>", RequestType = RequestType.Auth, SoftwareName = "<Your SoftwareName>", SoftwareVersion = "<Your SoftwareVersion>", TerminalID = "<Your TerminalId>", TransactionKey = "<Your TransactionKey>", UserReference = "<A Unique Sale Reference>", ThreeDSecureCardHolderEnrolled = "<3DS Provided Value>", ThreeDSecureECI = "<3DS Provided Value>", ThreeDSecureIAV = "<3DS Provided Value>", ThreeDSecureIAVAlgorithm = "<3DS Provided Value>", ThreeDSecureTransactionStatus = "<3DS Provided Value>", ThreeDSecureXID = "<3DS Provided Value>", };
PHP Example
$request = new Request(); $request->setAmount("<Amount>"); $request->setAmountType(AmountType_Actual); $request->setAmountUnit(AmountUnit_Major); $request->setApplicationId("<Your ApplicationId>"); $request->setCardHash("<Card Hash>"); $request->setCardReference("<Card Reference>"); $request->setCurrencyCode("<ISO CurrencyCode>"); $request->setRequestType(RequestType_Auth); $request->setSoftwareName("<Your SoftwareName>"); $request->setSoftwareVersion("<Your SoftwareVersion>"); $request->setTerminalID("<Your TerminalId>"); $request->setTransactionKey("<Your TransactionKey>"); $request->setUserReference("<A Unique Sale Reference>"); $request->setThreeDSecureCardHolderEnrolled("<3DS Provided Value>"); $request->setThreeDSecureECI("<3DS Provided Value>"); $request->setThreeDSecureIAV("<3DS Provided Value>"); $request->setThreeDSecureIAVAlgorithm("<3DS Provided Value>"); $request->setThreeDSecureTransactionStatus("<3DS Provided Value>"); $request->setThreeDSecureXID("<3DS Provided Value>");