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.

Google Pay on the web support is still being developed and will be added as soon as it is available.

The overall 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

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.

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

Paythru's gateway value is paythru.

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

We support both authMethods PAN_ONLY and CRYPTOGRAM_3DS

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 or Apple 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 or Apple 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 or Apple 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 (Google or Apple) 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

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
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>TokenisedWalletAuth</transactionType>
    <transactionKey>f2085db4024085b4ffc79cbeca463909</transactionKey>
    <bankTransId>10676</bankTransId>
    <bankResponseCode>1</bankResponseCode>
    <bankResponseMessage>OK</bankResponseMessage>
    <bankAuthCode>20200</bankAuthCode>
</paythruResponse>
HTTP Response (JSON)
{
    "transactionStatusCode": 600,
    "transactionStatus": "Approved",
    "transactionType": "TokenisedWalletAuth",
    "transactionKey": "0d39485ae87d7d4ce24561e99316c7b3",
    "bankTransId": "51894",
    "bankResponseCode": "1",
    "bankResponseMessage": "OK",
    "bankAuthCode": "20200"
}
Back to top