Google Pay direct AUTH integration

  Last updated: 

 

  The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.
Read this article to learn more.

  All businesses within the EEA (European Economic Area) are mandated to use 3-D Secure when processing e-commerce transactions, as part of the PSD2 mandate.

Merchants that process e-commerce transactions MUST support 3DS authentication. Click here to learn more.

The following content should only be utilised by merchants processing Mail Order Telephone Order (MOTO) payments or other workflows that are exempt from the PSD2 mandate.

The PAN_ONLY authmethod described below requires 3DS authentication.

 

This document assumes you have configured a direct integration with Google Pay and have followed    Google's guidance on how to consume the Google Pay payment token payload (link to external site) and are looking to use the TRU Connect gateway to process the payment.

 

About authentication methods

Each Google Pay transaction can be authenticated in two different ways:

  • PAN_ONLY - A card stored on the customer's Google account.
  • CRYPTOGRAM_3DS - A device token stored on an Android-powered device authenticated with a 3-D Secure cryptogram.

 

If your Google Pay integration is configured to support both PAN_ONLY and CRYPTOGRAM_3DS authentication methods, you will need to identify which of these two authentication methods were performed for each transaction. This is important because the authentication method returned by the Google Pay API dictates the next steps your system must perform in order to complete the payment.

To check the authentication method used for a given transaction, you will need to decrypt the encryptedMessage returned in the payment token from the Google Pay API. Specifically, you will need to look at the field paymentMethodDetails > authMethod and check whether the value is PAN_ONLY or CRYPTOGRAM_3DS.

 

1️⃣ PAN_ONLY 2️⃣ CRYPTOGRAM_3DS

If PAN_ONLY is returned in the authMethod, you must first authenticate the transaction with 3-D Secure. Providing the card is enrolled and successfully authenticated, you will be in possession of the fields listed below, which are required in the AUTH request:

Result data from 3-D Secure provider:

  • cavv
  • eci
  • enrolled
  • status
  • threedversion
  • threeddirectorytransactionreference

Fields must be submitted in AUTH if available.

Payment details from the Google Pay response:

  • pan
    Mapped from:
    encryptedMessage ≫ paymentMethodDetails ≫ pan
  • expirydate
    Mapped from:
    encryptedMessage ≫ paymentMethodDetails ≫ expirationMonth/expirationYear
  • walletdisplayname
    Mapped from:
    paymentMethodData ≫ info

If you intend to capture the customer's billing and delivery details from their Google Wallet, you will also need to parse the response from the Google API for these fields and map these to the appropriate fields in the subsequent AUTH request.

PAN_ONLY - AUTH Request - Specification

  Before submitting the AUTH!


  Unenrolled cards

If both your business and the cardholder’s bank are based within the European Economic Area (EEA) or the UK, your implementation must be compliant with the Revised Directive on Payment Services (PSD2).

PSD2 requires online card payments to be processed with 3-D Secure. If a card is not enrolled, the recommended approach would be to stop the transaction and offer the customer alternative means of payment.

If you have considered the legal implications covered above and are allowed to proceed, your system will need to construct and manually submit an AUTH request to complete the payment with an unenrolled card. Click here for the full specification.


  Unauthenticated cards

We strongly recommend against proceeding with the transaction if the status is ‘N’ or ‘R’:

  • If status is ‘N’, this indicates the customer was not authenticated.
  • If status is ‘R’, this indicates the authentication was rejected.

 

AUTH Request example

Python PHP cURL Raw JSON Raw XML
#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
"accounttypedescription":"ECOM",
  "baseamount":"2000",
  "currencyiso3a":"GBP",
  "expirydate":"07/2026",
 "pan":"5100000000000511",
  "requesttypedescriptions": ["AUTH"],
 "sitereference": "test_site12345",
  "cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=",
  "eci":"05",
  "enrolled":"Y",
  "status":"Y",
  "threedversion":"2.2.0",
  "threeddirectorytransactionreference":"f00e1111-0011-00a6-ab00-a00000a00000",
  "walletdisplayname":"MasterCard 0511",
"orderreference":"My_Order_123",
"walletsource":"GOOGLEPAY"

}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response

 

AUTH Request field specification

  Field Mapping to fields from Google paymentData Format Description
X1-EN.png accounttypedescription
XPath: /operation/accounttypedescription
N/A Alpha (20) Submit “ECOM” to represent an e-commerce transaction.
X1-EN.png baseamount
XPath: /billing/amount
N/A Numeric (13)

The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero.

X1-EN.png currencyiso3a
XPath: /billing/amount/@currencycode
N/A Alpha (3) The currency of the transaction. Click here for a full list of available currencies.
X1-EN.png enrolled
XPath: /threedsecure/enrolled
N/A Char (1)

Submit ‘Y’ to indicate that card is enrolled.

X1-EN.png expirydate
XPath: /billing/payment/expirydate

encryptedMessage ≫ paymentMethodDetails ≫ expirationMonth/expirationYear

Date MM/YYYY

The expiry date printed on the card.

You will need to combine the expirationMonth and expirationYear fields returned from Google and submit this in the format "MM/YYYY" in the AUTH request.

X1-EN.png pan
XPath: /billing/payment/pan

encryptedMessage ≫ paymentMethodDetails ≫ pan

Numeric (12-19) This is the long number printed on the front of the customer’s card.
X1-EN.png requesttypedescriptions
XPath: /@type
N/A Alpha (20)

Supported request type combinations:

  • [“AUTH”]
  • [“AUTH”, “RISKDEC”]
  • [“AUTH”, “SUBSCRIPTION”]
  • [“ACCOUNTCHECK”, “AUTH”]
  • [“ACCOUNTCHECK”, “SUBSCRIPTION”]
  • [“RISKDEC”, “AUTH”]
  • [“RISKDEC”, “AUTH”, “SUBSCRIPTION”]
  • [“RISKDEC”, “ACCOUNTCHECK”, “AUTH”]
  • [“RISKDEC”, “ACCOUNTCHECK”, “AUTH”, “SUBSCRIPTION”]

Click here to learn more about request types.

X1-EN.png sitereference
XPath: /operation/sitereference
N/A Alphanumeric
& underscore (50)
Identifies your site on the Trust Payments system.
X1-EN.png status
XPath: /threedsecure/status
N/A Char (1)

Indicates whether or not the customer was authenticated on the card issuer’s ACS:

  • ‘Y’ – Customer authenticated.
  • ‘A’ – Authentication attempted but could not be completed.
  • ‘U’ – Unable to perform authentication.
  • ‘C’ – Challenge required for authentication.
X1-EN.png walletdisplayname
XPath:/billing/payment/wallet/displayname

paymentMethodData ≫ info

Numeric (4)

This is information provided by the card issuer that can be displayed to the customer in order to identify the payment method. This typically includes the last 4 digits of their card number.

The info object contains two properties we require you to send in the walletdisplayname field. You should parse the cardNetwork & cardDetails property values and combine them together e.g.
"VISA 1111"

X1-EN.png walletsource
XPath: /billing/payment/wallet/source
N/A Alpha (8) Must be submitted with value “GOOGLEPAY”.
X2-EN.png billingfirstname
XPath: /billing/name/first
billingAddress ≫ name Alphanumeric including
symbols (127)

The customer’s billing first name.

Required for gaming merchants.

X2-EN.png billinglastname
XPath: /billing/name/last
billingAddress ≫ name Alphanumeric including
symbols (127)

The customer’s billing last name.

Required for gaming merchants.

X2-EN.png cavv
XPath: /threedsecure/cavv
N/A  Alphanumeric (56)

The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction.

Always submit this value when it is available.

 

X2-EN.png customerpostcode
XPath: /customer/postcode
shippingAddress ≫ postalCode Alphanumeric (25)

The customer's delivery postcode or ZIP code. This must be a valid postcode/ZIP code for the customercountryiso2a submitted.

Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.

X2-EN.png customerlastname
XPath: /customer/name/last
shippingAddress ≫ name Alphanumeric including
symbols (127)

The last name on the customer's delivery address.

Required if Merchant Category Code (MCC) is 6012 and payment type is VISA.

X2-EN.png eci
XPath: /threedsecure/eci
N/A Alphanumeric (2)

The ECI (E-Commerce Indicator) security level associated with the transaction.

Always submit this value when it is available.

Click here to learn more about possible ECI values.

X2-EN.png threedversion
XPath: /threedsecure/version
 N/A Numeric (6)

Version of 3-D Secure used to authenticate the payment. (e.g. “2.2.0”)

Always submit this value when it is available.

 

X2-EN.png

threeddirectorytransactionreference

XPath: /threedsecure/directorytransactionreference

 N/A Alphanumeric (48)

Unique DSTransactionId returned by your MPI provider.

Always submit this value when it is available.

 

X3-EN.png billingcountryiso2a
XPath: /billing/country
billingAddress ≫ countryCode Alpha (2)

The country on the customer's billing address. This will need to be in ISO2A format.

Click here for a full list of country codes.

X3-EN.png billingemail
XPath: /billing/email
N/A Email (255) The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
X3-EN.png billingpostcode
XPath: /billing/postcode
billingAddress ≫ postalCode Alphanumeric (25)

The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted.

X3-EN.png billingpremise
XPath: /billing/premise
billingAddress ≫ address1 Alphanumeric including
symbols (25)
The house name/number on the customer's billing address.
X3-EN.png billingtelephone
XPath: /billing/telephone
billingAddress ≫ phoneNumber Alphanumeric including
symbols (20)
The customer’s billing telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
X3-EN.png billingtown
XPath: /billing/town
billingAddress ≫ locality Alphanumeric including
symbols (127)
The town entered for the customer’s billing address.
X3-EN.png customercountryiso2a
XPath: /customer/country
shippingAddress ≫ countryCode Alpha (2)

The country on the customer's delivery address. This will need to be in ISO2A format.

Click here for a full list of country codes.

X3-EN.png customeremail
XPath: /customer/email
N/A Email (255) The customer’s delivery email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
X3-EN.png customerfirstname
XPath: /customer/name/first
shippingAddress ≫ name Alphanumeric including
symbols (127)

The first name on the customer's delivery address.

X3-EN.png customerpremise
XPath: /customer/premise
shippingAddress ≫ address1 Alphanumeric including
symbols (25)
The house name/number on the customer's delivery address.
X3-EN.png customertelephone
XPath: /customer/telephone
shippingAddress ≫ phoneNumber Alphanumeric including
symbols (20)
The customer’s delivery telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
X3-EN.png customertown
XPath: /customer/town
shippingAddress ≫ locality Alphanumeric including
symbols (127)
The town on the customer's delivery address.
X3-EN.png orderreference
XPath: /merchant/orderreference
N/A Alphanumeric including
symbols (25)

Your unique order reference that can be stored on the Trust Payments system.

X3-EN.png paymenttypedescription
XPath: /billing/payment/@type
N/A Alpha (20) Payment method (e.g. “VISA” or “MASTERCARD”).
PAN_ONLY - AUTH response - Specification

AUTH Response example

After submitting the AUTH request, you will be returned an AUTH response:

Python PHP Raw JSON Raw XML
{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'authcode': u 'TEST09',
u 'authmethod': u 'FINAL',
u 'baseamount': u '2000',
u 'cavv': u 'Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=',
u 'currencyiso3a': u 'GBP',
u 'customeroutput': u 'RESULT',
u 'debtrepayment': u '0',
u 'eci': u '05',
u 'enrolled': u 'Y',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'issuercountryiso2a': u 'JP',
u 'livestatus': u '0',
u 'maskedpan': u '510000######0511',
u 'merchantcategorycode': u '1234',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Test Merchant',
u 'merchantnumber': u '00000000',
u 'orderreference': u 'My_Order_123',
u 'operatorname': u 'webservices@example.com',
u 'paymenttypedescription': u 'MASTERCARD',
u 'requesttypedescription': u 'AUTH',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '0',
u 'settleduedate': u '2023-03-22',
u 'settlestatus': u '0',
u 'splitfinalnumber': u '1',
u 'status': u 'Y',
u 'threedversion': u '2.2.0',
u 'tid': u '27882788',
u 'transactionreference': u '36-9-286248',
u 'transactionstartedtimestamp': u '2023-03-22 09:34:31',
u 'walletdisplayname': u 'MasterCard 0511',
u 'walletsource': u 'GOOGLEPAY'
}]
}

 

AUTH Response field specification

  Field Format Description
X4-EN.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) “ECOM” is returned in the response to represent an e-commerce transaction.
X4-EN.png authmethod
XPath: /operation/authmethod
Alpha (11)

The authmethod specifies how a transaction is to be processed by the card issuer. You should expect one of the following values to be returned to indicate the authmethod employed. Click the following links to learn more:

  • PRE - Pre-authorisation
  • FINAL - Final authorisation

This field is returned if submitted in the request.

X4-EN.png baseamount
XPath: /billing/amount
Numeric (13) The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero.
X4-EN.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

The currency of the transaction.

Click here for a full list of available currencies.

X4-EN.png dccenabled
XPath: /billing/dcc/@enabled
Numeric (1) Because Google Pay does not support DCC, "0" will be returned to indicate DCC is disabled for this transaction.
X4-EN.png debtrepayment
XPath: /merchant/debtrepayment
Numeric (1)

Indicates if transaction is flagged as debt repayment. Click here to learn more.

X4-EN.png eci
XPath: /threedsecure/eci
Alphanumeric (2) The ECI (E-Commerce Indicator) security level associated with the transaction. Click here to learn more about possible ECI values.
X4-EN.png errorcode
XPath: /error/code
Numeric (1-5) The error code should be used to determine if the request was successful or not.
  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

X4-EN.png errormessage
XPath: /error/message
Alphanumeric (255) This provides a brief explanation as to the cause of the error.

For successful transactions, this is returned as “Ok”.

Click here for a full list of errorcode and message values.

X4-EN.png issuercountryiso2a
XPath: /billing/payment/issuercountry
Alpha (2)

The country of the customer’s card issuer.
This will be in ISO2A format.

Click here for a full list of country codes.

X4-EN.png livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
X4-EN.png maskedpan
XPath: /billing/payment/pan
Alphanumeric including “#” (12-19) The maskedpan field represents the customer’s card number. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211.
X4-EN.png operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
X4-EN.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) Payment method (e.g. “VISA” or “MASTERCARD”).
X4-EN.png requesttypedescription
XPath: /@type
Alpha (20) “AUTH” is returned in the response.
X4-EN.png securityresponseaddress
XPath: /security/address
Numeric (1) The result of AVS and Security Code Checks.

Click here to learn more.

X4-EN.png securityresponsepostcode
XPath: /security/postcode
Numeric (1)
X4-EN.png securityresponsesecuritycode
XPath: /security/securitycode
Numeric (1)
X4-EN.png settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
X4-EN.png settlestatus
XPath: /settlement/settlestatus
Numeric (3)

A numeric value used to indicate the progress of settlement regarding this transaction.

Click here for a full list of settlestatus values.

X4-EN.png splitfinalnumber
XPath: /operation/splitfinalnumber
Numeric (2) Because Google Pay does not support Split Shipment, "1" will be returned to indicate funds will be settled in one passing.
X4-EN.png tid
XPath: /merchant/tid
Alphanumeric (255) The terminal ID used to process the transaction. This is accredited to your merchant number when we setup your account in our systems.
X4-EN.png transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
A unique reference for the transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction.
X4-EN.png transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time the transaction was processed.
X4-EN.png walletdisplayname
XPath: /billing/payment/wallet/displayname
Alphanumeric (255) The card type used by the customer and the last four digits of their card number (e.g. “Visa 1111”).
X4-EN.png walletsource
XPath: /billing/payment/wallet/source
Alphanumeric (20) Used to identify the type of wallet used for this payment (in this case “GOOGLEPAY”).
X2-EN.png acquirerresponsecode
XPath: /acquirerresponsecode
Alphanumeric (255)

Used by your acquirer to indicate the outcome of the request.

This will vary depending on your acquiring bank. Please contact your bank for further information.

X2-EN.png authcode
XPath: /authcode
Alphanumeric (255)

The authorisation code provided by the issuing bank. This will differ depending on which bank you use.

Only returned if the transaction is authorised.

X2-EN.png errordata
XPath: /error/data
Alphanumeric (255)

Additional information to help troubleshoot the error.

Only returned if there has been an error.

X2-EN.png merchantcategorycode
XPath: /merchant/merchantcategorycode
Alphanumeric (255)

These are details associated with the account used to process the transaction. To amend these fields, please contact our Support Team.

Values returned depend on your account configuration.

X2-EN.png merchantcity
XPath: /merchant/merchantcity
Alphanumeric (127)
X2-EN.png merchantcountryiso2a
XPath: /merchant/merchantcountryiso2a
Alpha (2)
X2-EN.png merchantname
XPath: /merchant/merchantname
Alphanumeric (255)
X2-EN.png merchantstatecode
XPath: /merchant/merchantstatecode
Alphanumeric (127)
X2-EN.png merchantzipcode
XPath: /merchant/merchantzipcode
Alphanumeric (10)
X2-EN.png orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (25)

Your unique order reference that can be stored on the Trust Payments system.

This field is returned if submitted in the request.

Was this article helpful?
0 out of 0 found this helpful