Skip to content

Google™ Pay - Paythru Developer Documentation

1.0 Introduction

Paythru can decrypt Google Pay card tokens and allow a merchant to process payments for Android applications or web checkout journeys.

The process for conducting transactions using Google Pay is:

  1. The customer, on the merchant's app or website, opts to pay using Google Pay
  2. The merchant initiates the payment process directly with Google, using paythru as the payment gateway and the value for gatewayMerchantId as supplied by Paythru during boarding
  3. Google will return to the merchant the encrypted card data (token)
  4. The merchant base64 encodes the token prior to sending to Paythru
  5. The merchant forwards this base64 encoded payload to the walletPay method of the Paythru Gateway API for decryption and payment processing
  6. (When required) The merchant presents the additional authentication challenge to the end user to finalise payment

These steps are the same whether the checkout journey is being conducted via an Android App or via the web.

1.1 Card Acceptance

Paythru can accept cards of any type (e.g. Credit, Debit, PrePaid), scheme (e.g. Visa, MasterCard, American Express) or territory which is supported by the connected acquirer.

2.0 Configuration

Our support for Google Pay assumes the merchant already has a Google Developer Account and proficiency in Android application development, or web application development, and server-side development.

The merchant will be responsible for integrating with Google and obtaining the encrypted token containing payment card information. The encrypted token is to be presented to Paythru's walletPay method for decryption and payment. The merchant will also have to implement support for additional authentication challenges, which may be presented for any payments placed on PAN_ONLY tokens.

Paythru's gateway value is paythru.

Your gatewayMerchantId value will be issued by Paythru during your boarding process.

We support both authMethod values: PAN_ONLY and CRYPTOGRAM_3DS. Depending on precise configuration details and territory requirements PAN_ONLY tokens may require further authentication, see method documentation for full details.

2.1 App Payments

The developer instructions for adding Google Pay into your application are available on Google's documentation.

Once you have completed these implementation steps you will be able to collect tokens from Google Pay containing encrypted card data. These tokens should be submitted to Paythru's walletPay method below from your own server (they must not be sent directly from the App).

2.2 Web Payments

Note: Paythru do not currently provide Hosted Payment Page support for Google Pay.

The merchant must first follow the Google Pay API setup steps. If the merchant does not have a Google Developer account, they will need to create one.

With the Google account created follow all the steps in the Google Pay tutorial for web applications using the gateway value provided in section 2.0 of this document and the gatewayMerchantId as supplied by Paythru during on-boarding.

When you have obtained a Google card token you need to submit this, via your own server, to our walletPay method below. Never submit this request directly from the client.

2.2 Additional Authentication

A call to walletPay may return a transaction result, e.g. "transactionStatusCode": 600 if additional authentication is not required, but payments may instead return a URL, e.g. "authenticationUrl": "https://...". In cases where you do get back this URL, you should follow the instructions in our Gateway API documentation for handling 3DS challenges.

2.3 Further guidance

Further guidance can be obtained directly from the following documentation:

3.0 Methods

3.1 Wallet Pay method

Description

The wallet pay method is used to request payment on behalf of a customer using a Google card token.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned. Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes.

See our Gateway API documentation for detailed descriptions of endpoint URLs, signing requests, error responses and additional parameters.

Note that the payload parameter needs the encrypted card data received from Google to be base64 encoded prior to transmission.

URL

/v3/transaction/walletPay

Request parameters

Name Description Format
apiKey* The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword* The API Password provided by Paythru used for authentication. Alpha-numeric characters
payload* The payload received from Google Pay Pay, base64 encoded Base64 encoded string
threeDSecure Defaults to 0
If set to 1 and Google payload contains PAN only without authentication details then the response would contain an authentication URL. This URL should be set as the 'src' parameter of a new window or iframe and presented to the customer to complete authentication. Merchants will need to discuss setup with Paythru to allow this.		 0/1
returnUrl Required if threeDSecure is set 1. The user will be returned to this URL after the authentication has been completed. URL
walletType* The type of digital wallet being used. enum (googlePay or applePay)
paymentType* The type of payment to be processed enum (auth, preauth or verifycard)
shaSignature* The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature 128 Alpha numeric characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric characters
itemName0* The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0* The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Integer
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 255 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
merchantCustomerReference A reference for the merchant to identify the customer. This parameter is optional and can be used for validating the card key Up to 45 characters
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
ipAddress IP address of the customer x.x.x.x
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD

* denotes a mandatory field

Note that in territories governed by PSD2 regulations it is strongly recommended to set threeDSecure to 1 for all transactions.

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction 3 numeric characters
transactionStatus The human readable status of the transaction Up to 100 characters
transactionType The human readable type of the transaction Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. 32 alpha numeric characters
authenticationKey A unique key that will be needed to authorise a transaction. (This parameter will only be present if 3-D Secure was initiated successfully.) 32 alpha numeric characters
authenticationUrl The authentication URL. (This parameter will only be present if 3-D Secure was initiated successfully.) Alpha numeric characters and symbols
bank% Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to):
- bankAuthCode (Card issuer's authorisation code)
- bankTransId (Transaction ID issued by acquiring bank)
- bankResponseCode (Transaction status code issued by acquiring bank)
- bankResponseMessage (Transaction status message issued by acquiring bank)
- bankOrderId (Order ID issued by acquiring bank)		 Alpha numeric characters and symbols

Example Requests

HTTP Request
apiKey=******************
&apiPassword=******************
&payload=ey...Q==
&walletType=googlePay
&terminalKey=default
&currency=GBP
&itemName0=Baseball Cap
&itemPrice0=500
&shaSignature=c0...92e
&paymentType=auth

Example Responses

HTTP Response (XML)
<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
    <transactionStatusCode>600</transactionStatusCode>
    <transactionStatus>Approved</transactionStatus>
    <transactionType>Auth</transactionType>
    <transactionKey>f2085db4024085b4ffc79cbeca463909</transactionKey>
    <bankTransId>10676</bankTransId>
    <bankResponseCode>1</bankResponseCode>
    <bankResponseMessage>OK</bankResponseMessage>
    <bankAuthCode>20200</bankAuthCode>
</paythruResponse>

Response if 3D secure was initiated 

<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
    <transactionStatusCode>607</transactionStatusCode>
    <transactionStatus>Success</transactionStatus>
    <transactionType>3DSecureCheck</transactionType>
    <transactionKey>27d9527c37162f8012a391cdfd996aa6</transactionKey>
    <bankECIValue>06</bankTransId>
    <authenticationKey>0ca722e9fff3c94e7f38d81f91ae6eb9</authenticationKey>
    <authenticationUrl>https://ws.paythru.com/threeDSRedirect/form/0ca722e9fff3c94e7f38d81f91ae6eb9</authenticationUrl>
</paythruResponse>

HTTP Response (JSON)
{
    "transactionStatusCode": 600,
    "transactionStatus": "Approved",
    "transactionType": "Auth",
    "transactionKey": "0d39485ae87d7d4ce24561e99316c7b3",
    "bankTransId": "51894",
    "bankResponseCode": "1",
    "bankResponseMessage": "OK",
    "bankAuthCode": "20200"
}

Response if 3D secure was initiated

{
    "transactionStatusCode": 607,
    "transactionStatus": "Success",
    "transactionType": "3DSecureCheck",
    "transactionKey": "27d9527c37162f8012a391cdfd996aa6",
    "bankECIValue": "05",
    "authenticationKey": "0ca722e9fff3c94e7f38d81f91ae6eb9",
    "authenticationUrl": "https://ws.paythru.com/threeDSRedirect/form/0ca722e9fff3c94e7f38d81f91ae6eb9",
}
Back to top