Google Pay™

Google Pay is a digital wallet platform that empowers customers to make online purchases securely without the need to enter their card details for each payment. This payment method is available across all devices (mobile and desktop), irrespective of the operating system and web browser.

When the cardholder selects to pay by Google Pay in-app or on the web, Google Pay displays a payment sheet where they can select which card they want to use and confirm the purchase. For more information, check out this video on how Google Pay works.

How it works

  1. You request the encrypted payload from your app or browser
  2. Google Pay returns a token value that contains an encrypted payload
  3. You send the token to your server and Base64 encode it
  4. You submit a request into Acquired’s Card API containing the token value
  5. Acquired processes the payment and returns a payment response
  6. You inform the customer of the transactions outcome

Setup

Before you get started you will need:

  1. A direct integration into the Acquired.com API
  2. A Google Developer account - see here
  3. Acquired to enable Google Pay on your account - contact support@acquired.com
  4. To contact Google via the Business Console so that they can add your app to their system for production use - see here

Integrate with Google Pay

See the Google Pay API documentation for a detailed resource of how to integrate Google Pay into your application.

Google Pay > Web

Support Google Pay on your website - checkout the links below to get started:

Get Started

Android Google Pay > in-App

Support Google Pay on your Android app - check out the links below to get started:

Get Started

Defining your payment gateway

When providing your payment tokenization method, set the tokenizationSpecification.type value as “PAYMENT_GATEWAY”.

In addition provide acquired as your “gateway” and specify the Acquired Company ID that will subsequently be used when submitting your request into the Card API as the “gatewayMerchantId” value.

"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "acquired",
    "gatewayMerchantId": "YOUR_ACQUIRED_COMPANY_ID"
  }
}

Set the allowedCardNetworks property

For supported payment type, select ‘CARD’.

Acquired supports Google Pay payments from Visa, MasterCard & Amex cards, you can define these accepted card networks in the ‘allowedCardNetworks’ property when initiating your request to the Google Pay API.

const allowedCardNetworks = ["VISA", "MASTERCARD", "AMEX"];

Set the allowedCardAuthMethods

If you are not decrypting the Google Pay payload then you will not have visibility of the underlying credential, including whether the authentication method equals PAN_ONLY or CRYPTOGRAM_3DS.

const allowedCardAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];
  • PAN_ONLY: associated with payment cards stored on file that may require 3-D Secure to comply with SCA requirements.
  • CRYPTOGRAM_3DS: associated with cards stored as Android device tokens - this method is SCA compliant and does not require 3-D Secure to be processed.

It is therefore required that you also send additional 3-D Secure parameters when submitting your request into Acquired so that transactions can be routed via 3D Secure if required. See our PAN Only Section below for details of the additional fields required.

If the authenticationMethod of the decrypted payload equals “PAN_ONLY” and the card is enrolled for EMV 3DS (V2) then we will validate your request before proceeding with 3D Secure authentication. If your request is invalid then we will respond with “response_code”: “550”, “response_message”: “SCA Field (field name)”.

Please ensure you are also capable of handling the 3DS challenge flow and displaying this information to your customer, we will respond with “response_code”: “503”, “response_message”: “SCA: Challenge Required” if challenge flow is required.

Note: If you limit your accepted credentials to CRYPTOGRAM_3DS in your Google Pay API Integration then you will not be required to provide these additional 3-D Secure parameters.

Integrate with Acquired.com

Once you’ve successfully integrated with your web application with Google Pay and are able to send the returned payload to your server then you’re capable of submitting Google Pay transactions to Acquired via our API.

Making a Payment

Step 1: at the end of the Google Pay process an encrypted payload will be returned to your application, an example of this can be found below:

{"apiVersionMinor":0,"apiVersion":2,"paymentMethodData":{"description":"Visa%u2006%u2022%u2022%u2022%u2022%u20061111","tokenizationData":{"type":"PAYMENT_GATEWAY","token":"{\"signature\":\"MEQCIEzQUUkhKfSNmtQn7yw3VmnZNNF8xYkKvhUS1O1aGRbPAiBQ6uDUh9rFGv92RX1+zbOAzY1QcAkzaGliIuc+vmQG1g\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEn1O+Iev10IvDndJ6naCWcGc/XCacYXL3ZTrDar9OS9taA2/ZAzJa+WUkqSZUcFDMdHTK4lbmebn3MeyYdoFQJw\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1621529256367\\\"}\",\"signatures\":[\"MEYCIQCnrV3uzf90iWDvMYIrzVk7FliPcj+P57mUKDZ9D3Zc1AIhAJD5P7QBl8LOtSVkjjjq+3SY4o3AcpbkDqXJQuXfs1tg\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"k/zi37h/ZPZ49kKuaod7hcP6AQFb5edMYln9leNtQdRkmUZoIoOIEYMqoc0VmMxkCdhs21GzuZ0UYvZaelPFcjNzpYyBPGqHZhD52WX8nO107VQ27tXtc6+7bAD7XzgMl/1U8cPw2l+LbNzuVKwGcY7cfrxMRx32KXnjsz/S5igNkPaE6kuYjPp/zsMFHJte8t5W4hhZrrY1OM3Rt1JExqQrBQCPJPfZNh9EuAyA4s+7edka5YCQx8gBZr5iIWcCz8HkBiF/c+MwjwuAoBmuYbTVK2k+JX523Owa1L/44Zhz7PBB/iS4ptc/j9A0Qc1Gh7GDb5psTCNq1AUi56TyL/Ckh/KAn3SJ2W9D7aqDpXYKTX2DQil2p/kT2536TtSQI2tbqAk1gWOb20R4A1Gy6o1Q49eIq9QUQhylTIXoXt7fHEq5zGerrRrCXYbhzaD1LFaywJrYqDi82LnpEiQG10Iln8iIaTRXSGJicLIPZfVtK81cI9nIh/+HgBu3hItuU44lMRtmw5a+0hxOCq0bDiMQhQlX4zCKgZEPGzc7aSg+s3fNatR66U54TWW6WvkcDhA\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BP4lqDq/9e24uPcRG3qleyaY//Fr4StEuoBf8wDE7/9MFtsAXTqut8jT61DqYS3HFN49lrp4f9GHdEoRAyio81E\\\\u003d\\\",\\\"tag\\\":\\\"SWZfba8mk1qGBmvpHylgQxzBWhBgw5xGTt7vZnvVWqg\\\\u003d\\\"}\"}"},"type":"CARD","info":{"cardNetwork":"VISA","cardDetails":"1111"}}}

To simplify the integration process, base64 this entire JSON string which you can then pass through to us in the API in the payment.token field to be decrypted by us.

Step 2: using the Acquired API in the same way as a card payment, submit the base64 encoded string value through to us in the payment.token field of your request.

Here’s a table with a list of mandatory and additional parameters that formulate the Acquired card api request, as well as some handy sample code in the right-hand side bar.

Parameter Format Length Description
timestamp
Required
date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id
Required
int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
company_pass
Required
string 10-30 API Password we issue to merchants.
Acceptable Characters: 0-9 a-z A-z
company_mid_id int 1-11 Targets a specific mid_id within the company structure. Leave it blank (or don't pass it) to balance traffic across multiple mid_ids (banks).
Acceptable Characters: 0-9
request_hash
Required
string 64 Verification hash value - please see here.
Acceptable Characters: 0-9 a-z A-z _ -
transaction
Required
object Click here.
merchant_order_id
Required
string 1-50 Unique ID you’ll use to identify each transaction.
Acceptable Characters: a-z A-Z 0-9 _ -
transaction_type
Required
string 1-20 The type of transaction you are trying to perform - possible values for this request are either AUTH_ONLY or AUTH_CAPTURE.
Acceptable Characters: a-z A-Z _
amount
Required
string 0-11 Transaction amount.
Acceptable Characters: 0-9 in the format DDDDDD.CC
currency_code_iso3
Required
string 3 Transaction currency, an ISO 4217 3-digit code.
Acceptable Characters: a-z A-Z
payment
Required
object Click here. Click here.
method string 10 The payment method used. For this trasnaction set this value to "google_pay"
token
string 1-2048 Base64-encoded payment token
display_name string 0-50 The display name often includes the card scheme and the last four digits of the credit card number when available, for example: “Visa 1233”, “MasterCard 5678”, “AmEx 9876”
Acceptable Characters: a-z A-Z 0-9 - * • ! " # % & ' + , - . : ; = ? ^ _ ]
network
string 0-50 The card scheme for the card used in this trasnaction, for example: "visa", "mastercard", "amex"
Acceptable Characters: a-z A-Z
billing
object Click here. Click here.
billing_zipcode
AVS & MCC 6012
string 0-100 Cardholder’s billing ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
{
      "timestamp":"20190620101530",
      "company_id":113,
      "company_pass":"password",
      "company_mid_id":1045,
      "request_hash" : "f0a18260b08a0bfacb.....",
"transaction":{
    "merchant_order_id":"a9f0ce93-6f0d-4a15-a18b-45f1304b4bc0",
      "transaction_type":"AUTH_CAPTURE",
      "amount":"14.99",
      "currency_code_iso3":"GBP",
      
},
"payment" : {
    "method":" google_pay",
      "token":"eyJhcGlWZXJzaW9uTWlub3IiOjAsImFwaVZlcnNpb24iO.....",
      "display_name":"Visa 1233",
      "network":"VISA",
      
}
}
Note: if you want to process your card authorisation request including AVS data, you will need to request BillingAddressParameters in your Google Pay Api request. The MIN option will return enough data for a postcode check only, to also validate the address you will need to send the FULL details - see here.

Step 3: we will respond in the normal way so if you have an existing card payments integration, nothing will change just handle the response_code value and display a response to your customer.

Pan Only

Merchants wanting to process payments against PAN_ONLY cards are required to provide additional parameters to support 3-D Secure authentication when submitting their request into Acquired.

Additional 3D Secure Supporting Parameters

Additional parameters are required if you are supporting the PAN_ONLY Authentication Method.

To support this the customer's billing information is also required to be submitted into Acquired. This information can be retrieved from the Google Pay API, see ‘Google Pay API - Request Objects’ section of this guide for details on how to achieve this.

As well as the billing information, Acquired requires the browser_data object. You should therefore collect your customers browsers data and pass it through in the authorisation request, for more information on this please see Gather Device Data guide.

The below table shows a list of all parameters you'll need to create your PAN_ONLY request as well as a complete sample code example of Acquired API request located on the right-side bar.

Request Parameters

Parameter Format Length Description
timestamp
Required
date 14 Date and time of transaction submission.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id
Required
int 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
company_pass
Required
string 10-30 API Password we issue to merchants.
Acceptable Characters: 0-9 a-z A-z
company_mid_id int 1-11 Targets a specific mid_id within the company structure. Leave it blank (or don't pass it) to balance traffic across multiple mid_ids (banks).
Acceptable Characters: 0-9
request_hash
Required
string 64 Verification hash value - please see here.
Acceptable Characters: 0-9 a-z A-z _ -
transaction
Required
object Click here.
merchant_order_id
Required
string 1-50 Unique ID you’ll use to identify each transaction.
Acceptable Characters: a-z A-Z 0-9 _ -
transaction_type
Required
string 1-20 The type of transaction you are trying to perform - possible values for this request are either AUTH_ONLY or AUTH_CAPTURE.
Acceptable Characters: a-z A-Z _
amount
Required
string 0-11 Transaction amount.
Acceptable Characters: 0-9 in the format DDDDDD.CC
currency_code_iso3
Required
string 3 Transaction currency, an ISO 4217 3-digit code.
Acceptable Characters: a-z A-Z
payment
Required
object Click here. Click here.
method string 10 The payment method used. For this trasnaction set this value to "google_pay"
token
string 1-2048 Base64-encoded payment token
display_name string 0-50 The display name often includes the card scheme and the last four digits of the credit card number when available, for example: “Visa 1233”, “MasterCard 5678”, “AmEx 9876”
Acceptable Characters: a-z A-Z 0-9 - * • ! " # % & ' + , - . : ; = ? ^ _ ]
network
string 0-50 The card scheme for the card used in this trasnaction, for example: "visa", "mastercard", "amex"
Acceptable Characters: a-z A-Z
billing
Required
object Click here. Click here.
cardholder_name
EMV 3DS
string 0-45 Cardholder’s name.
Acceptable Characters: a-z A-Z , . - '
billing_street
AVS & EMV 3DS
string 0-50 Cardholder’s billing street address.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
billing_street2
EMV 3DS
string 0-50 Cardholder’s billing street address, line 2.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
billing_city
EMV 3DS
string 0-100 Cardholder’s billing city.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
billing_state string 0-100 Cardholder’s billing state or province.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_zipcode
MCC 6012 & AVS & EMV 3DS
string 0-100 Cardholder’s billing ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
billing_country_code_iso2
EMV 3DS
string 2 Cardholder’s billing country, an ISO 3166 2-character code.
Acceptable Characters: a-z A-Z
billing_phone_code string 3 Cardholder’s billing phone number country code (For example, 44 for the UK).
Acceptable Characters: 0-9 ( ) -
billing_phone string 7-20 Cardholder’s billing phone number.
Acceptable Characters: 0-9 ( ) + -
billing_email
EMV 3DS
string 0-50 Cardholder’s billing email address.
Acceptable Characters: 0-9 a-z A-z _ - . @
shipping object Click here.
shipping_street string 0-100 Cardholder’s shipping street address.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
shipping_street2 string 0-100 Cardholder’s shipping street address, line 2.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
shipping_city string 0-100 Cardholder’s shipping city.
Acceptable Characters: a-z A-Z 0-9 , . - _ / \ &
shipping_state string 0-100 Cardholder’s shipping state or province.
Acceptable Characters: a-z A-Z 0-9 , . - _
shipping_zipcode string 0-100 Cardholder’s shipping ZIP or postal code.
Acceptable Characters: a-z A-Z 0-9 , . - _
shipping_country_code_iso2 string 2 Cardholder’s shipping country, an ISO 3166 2-character code.
Acceptable Characters: a-z A-Z
shipping_phone_code string 2 Cardholder’s shipping phone number country code (For example, 44 for the UK).
Acceptable Characters: 0-9 ( ) + -
shipping_phone string 7-20 Cardholder’s shipping phone number.
Acceptable Characters: 0-9 ( ) + -
shipping_email string 0-50 Cardholder’s shipping email address.
Acceptable Characters: 0-9 a-z A-z _ - . @
tds
Required
object Click here. Click here.
action string 3 This value should be set to SCA when the Authentication Method for the payment card is “PAN_ONLY”.
browser_language object
accept_header string 1-2048
HTTP accept headers as sent by the browser.
color_depth enum Browser color depth.
Acceptable values: ONE_BIT, TWO_BITS, FOUR_BITS, EIGHT_BITS, FIFTEEN_BITS, SIXTEEN_BITS, TWENTY_FOUR_BITS, THIRTY_TWO_BITS, FORTY_EIGHT_BITS.
ip string 7 -39 IP address returned by the browser in either IPv4 or IPv6 format.
java_enabled boolean If the device can execute Java.
javascript_enabled boolean If the browser can execute JavaScript.
language string 1-8 Browser language (en-US = English for example)
screen_height string 1-6 Total height of the users screen in pixels.
screen_width string 1-6 Total width of the users screen in pixels.
user_agent string 1-2048 Exact content of the HTTP user-agent header sent by the browser.
challenge_window_size enum The size of the challenge window you are going to display to the customer, the ACS will send it back formatted appropriately.
Acceptable Values:WINDOWED_250X400, WINDOWED_390X400, WINDOWED_500X600, WINDOWED_600X400, ßFULL_SCREEN
timezone string 1-5 Time difference between UTC time and the user’s browser time, in minutes.
Acceptable Characters:1-9 -
merchant object
contact_url url Link to the contact / customer care section of your website, just in case something goes wrong.
Example: https://merchantdomain.com/contactus
challenge_url url In the event of a Challenge Flow, where the ACS should POST back their response to.
{
      "timestamp":"20190620101530",
      "company_id":113,
      "company_pass":"password",
      "company_mid_id":1045,
      "request_hash" : "f0a18260b08a0bfacb.....",
"transaction":{
    "merchant_order_id":"a9f0ce93-6f0d-4a15-a18b-45f1304b4bc0",
      "transaction_type":"AUTH_CAPTURE",
      "amount":"14.99",
      "currency_code_iso3":"GBP",
      
},
"payment" : {
    "method":" google_pay",
      "token":"eyJhcGlWZXJzaW9uTWlub3IiOjAsImFwaVZlcnNpb24iO.....",
      "display_name":"Visa 1233",
      "network":"VISA"
      
},
"billing" : {
    "cardholder_name":"John Smith",
      "billing_street":"Suite 2, 4th Floor",
      "billing_street2":"44 Baker Street",
      "billing_city":"London",
      "billing_state":"",
      "billing_zipcode":"W1U7AL",
      "billing_country_code_iso2":"GB",
      "billing_phone":"02039826580",
      "billing_email":"support@acquired.com"
      
},
"shipping" : {
    "shipping_street":"Suite 2, 4th Floor",
      "shipping_street2":"44 Baker Street",
      "shipping_city":"London",
      "shipping_state":"",
      "shipping_zipcode":"W1U7AL",
      "shipping_country_code_iso2":"GB",
      "shipping_phone":"02039826580",
      "shipping_email":"support@acquired.com"
      
},
"tds" : {
    "action":"SCA",
    "browser_data" : { 
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9;q=0.8",
      "color_depth":"TWENTY_FOUR_BITS",
      "ip":"127.0.0.1",
      "java_enabled":"true",
      "javascript_enabled":"false",
      "language":"en-gb",
      "screen_height":"1440",      
      "screen_width":"2560",
      "challenge_window_size":"FULL_SCREEN",
      "language":"en-gb",
      "timezone":"-60",
         "user_agent":"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.114 Safari/537.36",
    "merchant" : { 
      "contact_url":"https://www.testdomain.com/contactus/",
      "challenge_url":"https://challenge.test.com.....",
      
}
}

Google Pay API - Request Objects

The Google Pay API enables you to call up your customers' saved payment information.

To reduce friction at the checkout you should request the billing object data required by Acquired when calling the Google Pay API. You can then use the available Google Pay API response data to populate Acquired’s billing object parameters before submitting your request into Acquired for authorisation.

Please see below for the request objects that should be configured when making a request into the Google Pay API when PAN_ONLY Authentication Method is supported:

If you prefer, you can see Google's own reference guide here.
Parameter Format Length Description
PaymentDataRequest
Required
object
emailRequired
PAN_ONLY
boolean Set to true to request an email address.
BillingAddressParameters
Required
object This object allows you to set additional fields to be returned for a requested billing address.
format
PAN_ONLY
string 4 Set to FULL to request complete billing address details.
NOTE: If not set to "FULL" the Google Pay API Response will not return all of the fields you are required to submit into Acquired.
phoneNumberRequired
PAN_ONLY
boolean Set to true to request a phone number.

Google Pay API - Response Objects

The table below describes the response objects and parameters returned by the Google Pay API in response to the to the Google Pay API - Request highlighted in the table above. The last column in the below table shows how the Google Pay API Response Data can be mapped into Acquired’s Card API when submitting your request for authorisation.

Parameter Format Description Acquired's Card API Parameter (Maps to...)
PaymentData
object
email
string Payer's email address returned if emailRequired is set to true in PaymentDataRequest.
billing_email
Address
object
name
string Cardholder's name as stored on the Payer's Google wallet. cardholder_name
postalCode
string Payer's billing address Postal or ZIP code.
billing_zipcode
countryCode
string Payer's billing address country code provided in ISO 3166-1 alpha-2 format.
billing_country_code_iso2
phoneNumber
string Payer's A telephone number, if phoneNumberRequired is set to true in PaymentDataRequest.
billing_phone
address1
string Payer's billing address line 1
billing_street
address2
string Payer's billing address line 2.
billing_street2
address3
string Payer's billing address line 3.
N/A
locality
string Payer's billing address city, town, neighbourhood, or suburb.
billing_city
administrativeArea
string Payer's billing address state, county or province.
billing_state
sortingCode
string Payer's billing address sorting code.
N/A

Acquired Card API API - Response Codes

As mentioned, if you support PAN_ONLY Authentication Method then you will not have visibility of the underlying authentication method for the payment card when you submit your request into Acquired.

If the Authentication Method is CRYPTOGRAM_3DS then Acquired will immediately proceed to authorisation for the transaction, as shown in the diagram.

If the Authentication Method for the payment card is PAN_ONLY and tds.action is set to SCA in your request then Acquired will perform a 3DS Version check against the payment card.

If the card is NOT enrolled for 3DS V2 or 3DS V1 we will proceed to authorisation. If the card is enrolled for 3DS V1 we will respond back to your request with Response Code "501", see table below for details.

If the Authentication Method for the payment card is PAN_ONLY and the card is enrolled 3DS V2 we will validate your request message, ensuring that the additional 3D Secure parameters are provided and valid (see PAN Only Request Parameters table above).

If the request is invalid, we will respond back to your request with Response Code "550", see table below.

If the request is valid and the issuing back requires no further authentication (frictionless flow) then Acquired will proceed to authorisation.

If the request is valid and the issuing bank requires further authentication then Acquired will respond back to your request with Response Code "503", see table below for details.

If your request proceeds to authentication, then you should handle the response code and message as per a standard authorisation message.

Response Code Response Message Description
501
Pending:Card Enrolled The cardholder is enrolled for 3D Secure V1, continue to redirect them to the ACS page. See documentation
550
SCA Field (parameter_name) Your request was invalid because of an issue with one or more of the 3D Secure V2 parameters. The Response Message will provide the name of the parameter(s) where the error occurred.
503
SCA: Challenge Required The issuing bank requires further information to authenticate the cardholder. See Acquired’s developer site for more information on how to handle this scenario, see Challenge Flow

Testing Google Pay

In simulate different responses from our API to test Google Pay, you will need to update the "amount" value in your request as detailed below:

For a successful response - you can submit any other value.
Amount Response Code Response Message
11.02 101 Declined
11.03 301 Declined: Insufficent Funds
11.04 402 Declined: Lost or Stolen Card
91.01 503 Chellenge Required
91.11 501 Pending:Card Enrolled