Introduction

Google Pay™ offers a fast, simple and secure way for customers to handle payments both online and in store using their digital wallet. Integrating Google Pay™ helps merchants deliver a seamless checkout experience, increasing user satisfaction and encouraging repeat business.

Merchants need to place a Google Pay™ button in their online shops or mobile apps. Customers are then presented with a payment sheet displaying saved payment methods from their Google Account, along with other optional data like shipping addresses.

Google Pay™ allows merchants to customize the payment button's appearance to match the merchant's UI design, while adhering to Google Pay™ branding guidelines.

Overview

Google Pay™ is now available worldwide, however some Google Pay™ and Google Wallet™ payments features are only available in certain countries and on certain devices. For more details, please check with Google Pay™ feature availability.

All currencies that Google Pay™ supports are currently also supported by the PAYONE platform.

Supported Payment methods:

  • Visa
  • Mastercard


Google Pay™ may use cards or network tokens. Card based payloads consisting of PAN require PCI DSS compliance and 3D-Secure processing. To avoid the software on your server to come in contact with credit card data, PAYONE gets the complexity away from you via our Google Pay™ implementation in combination with the existing 3D Secure and SCA handling available in our gateway.

Test Data

You can use Google’s sample cards or PAYONE's test cards to perform test transactions.

Google’s sample cards
the test data that can be used is documented on the Google Pay™ test card suite for Web and test card suite for Android
Payone test cards

When testing the Google Pay™ integration with PAYONE, you can utilize PAYONE test cards, which also support the 3DS flow, providing a comprehensive end-to-end testing experience. The account you use for testing with PAYONE test cards must be added to the Google Pay test card suite group.

LIABILITY SHIFT

Google Pay™ supports liability shift to issuers for qualified transactions using Mastercard and Visa Android device tokens (CRYPTOGRAM_3DS). Meanwhile, Google Pay™ PAN-based transactions follow the same liability shift rules based on the results of 3D Secure and corresponding card scheme rules.

The liability shift features are part of Visa and Mastercard programs with Google Pay™ and are subject to card scheme rules. For Visa, merchants can opt-in for "Fraud Liability Protection for Visa device tokens" at the Google Pay™ & Wallet Console.

European merchants are automatically opted-in.

---end


Details about liability shift for Google Pay™ can be found in the Google Pay™ FAQ.

Integrations

POST Request Pre- /Authorization
Account Parameters
request
required
Fixed Value: preauthorization
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
PERSONAL DATA Parameters
firstname
optional
Format CHAR(1..50)

First name of customer; optional if company is used, i.e.: you may use

"company" or "lastname" or "firstname" plus "lastname"

lastname
required
Format CHAR(2..50)

Last name of customer; optional if company is used, i.e.: you may use

"company" or "lastname" or "firstname" plus "lastname"

company
optional
Format CHAR(2..50)

Company name, required for B2B transactions (if add_paydata[b2b] = “yes”)

street
optional
Format CHAR(1..50)

Street number and name (required: at least one character)

zip
optional
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode

city
optional
Format CHAR(2..50)

City of customer

country
required
Format List

Permitted values ISO 3166 2-letter-codes

Samples DE / GB/ US

Specifies country of address for the customer.

Some countries require additional information in parameter "state"
email
optional
Format CHAR(5..254)

Permitted Symbols RFC 5322

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

Username = Max. 63 characters

Domain Name = Max. 63 characters
Domain Suffixes = Max. 4 suffixes with max. 124 characters
Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]

"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

email-address of customer

birthday
optional
Format DATE(8), YYYYMMDD

Samples 20190101 / 19991231


Date of birth of customer

telephonenumber
optional

Telephone number

add_paydata PARAMETERS
add_paydata[paymentmethod_token_data]
required

Sample rhHAQUrR118u[...]cwDw

Google Pay encrypted token, Base64 encoded

Response Parameters

Permitted Values

APPROVED
REDIRECT
ERROR
Response Parameter (Approved)
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

userid
Format NUMERIC(9..12)

PAYONE User ID, defined by PAYONE

Response Parameter (Error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded    
Payload

add_paydata[paymentmethod_token_data]=FpFyA6zSGkZC[...]xi8xeXCNbpGBpvlNXfcang==
aid=12345
amount=1000
api_version=3.11
clearingtype=wlt
country=DE
currency=EUR
encoding=UTF-8
firstname=Demo
key=123456789abcdefghij
lastname=Dude
mid=12345
mode=test
portalid=123456
reference=013265464564654
request=preauthorization
wallettype=GGP
RESPONSE

status=APPROVED
txid=123456789
userid=987654321
POST Request Capture

The capture request is used to finalize a preauthorized transaction.

If you use preauth/Capture with installment transactions, the capture request has to be sent right after the preauthorization

Account Parameters
request
required
Fixed Value: creditcardcheck
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
txid
required
Format: NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

clearingtype
optional
Fixed Value: wlt
wallettype
optional
Fixed Value: GGP

GGP: Google Pay

capturemode
required
Format: LIST
Value Comment
completed

Set with last capture; i.e.: Delivery completed.
No further capture is allowed.

notcompleted

Set with partial deliveries (last delivery with "completed")
Another capture is expected to complete the transaction.

Specifies whether this capture is the last one or whether there will be another one in future.

sequencenumber
optional
Format: NUMERIC(1..3)
Permitted values: 0..127

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

amount
required
Format: NUMERIC(1..10)
Permitted values: max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Fixed Value: EUR
narrative_text
optional
Format: CHAR(1..81)

Dynamic text element on account statements
(3 lines with 27 characters each) and credit card statements.

Response Parameters
Permitted Values
APPROVED
ERROR
Response Parameter (approved)
Format: NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

settleaccount
Format: LIST
Value Comment
yes

Settlement of outstanding balances is carried out.

no

Do not carry out settlement of outstanding balances, book request only.

auto

The system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.

Response parameters (error)
Format: NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format: CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

customermessage
Format: CHAR(1..1024)

The customer message is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded


POST Request Debit
Account Parameters
request
required
Fixed Value: creditcardcheck
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
common Parameters
txid
required
Format: NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

sequencenumber
required
Format: NUMERIC(1..3)

Permitted values 0..127

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

amount
required
Format: NUMERIC(1..10)

Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Fixed Value: EUR
settleaccount
optional
Format: LIST
Value Comment
yes

Settlement of outstanding balances is carried out.

no

Do not carry out settlement of outstanding balances, book request only.

auto

The system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.

Response Parameters
Permitted Values
APPROVED
ERROR
Response Parameter (approved)
txid
Format: NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

settleaccount
Format: LIST 
Value Comment
yes

Settlement of outstanding balances is carried out.

no

Do not carry out settlement of outstanding balances, book request only.

Provides information about whether a settlement of balances has been carried out.

Response Parameter (error)
errorcode
Format: NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

errormessage
Format: CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

customermessage
Format: CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded

Sequence Diagram

Please ensure that you only offer payment methods through Google Pay™ that are included in your contract with us.

Prerequisites

Onboarding

Merchants with an existing account on our platform who wish to provide Google Pay™ must follow these preparatory steps:

1
Activate Google Pay™ payment method with us

Please contact PAYONE Merchant Services

2
register and obtain Google account

To integrate Google Pay™ in your online shop or Android app, you must first register with Google and obtain a Google account. Please follow the checklists below:

  1. Online shop/web checklist
  2. Android app checklist

3
accept Google Pay™ Terms of service and acceptable use policy

Before your production access you should read and accept Google Pay™ Terms of Service and adehere to Google Pay™ and Wallet APIs Acceptable Use Policy

    4
    meet the Google pay™ API requirements

    Check the criteria for Google Pay™ API as described in Setup section of the Google documentation

    5
    payone is your gateway

    PAYONE handles PCI DSS and alleviates the burden from you when using and integrating Google Pay™. You will receive the encrypted payload (payment token data) from Google Pay™ with the PAYONE Public Key. Use the type: "PAYMENT_GATEWAY" to facilitate integration via the PAYONE Gateway and to avoid receiving PAN data on your end..


    You should specify PAYONE as your GatewayId:

    1. GatewayId: payonegmbh
    2. Gateway Merchant ID: <your merchant id with PAYONE>

    Google Pay™ on Your Website

    How Google Pay™ Works

    The Google Pay™ API offers a streamlined checkout process, allowing customers to make purchases using payment methods saved to their Google Accounts. This not only simplifies the checkout process but also enhances security, as customer payment data is encrypted from Google's servers to the payment processor. With easy integration, you can implement Google Pay™ with minimal coding, potentially leading to a significant increase in unique users and sales volume.

    Checkout the Google Pay - checkout experience pages for more buyer's experience with Google Pay.

    source: Google Developers

    1. Google Pay™ brand guideline for web

    Make sure to follow the Google Pay™ brand guidelines before adding Google Pay™ payment button on your online shop.

    2. Integrate Google Pay™ api

    Integrate Google Pay™ API in your online shop. For detailed instructions please use the Google Pay™ API web integration guide and Google Pay™ API web integration checklist

    ---end

    Payment gateway parameters

    You should use the following values for the payment gateway, in accordance with the Tokenization Specifications illustrated below:

    • type: "PAYMENT_GATEWAY"
    • GatewayId: payonegmbh
    • Gateway Merchant ID: <your merchant id with PAYONE>

     const tokenizationSpecification = {
                type: “PAYMENT_GATEWAY”,
                parameters: {
                'gateway': 'payonegmbh',
                'gatewayMerchantId': 'yourPayoneMerchantID'
                }

    ---end

    Supported payment methods

    You should configure your online shop to accept only the card schemes that your merchant account supports:

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

    ---end

    Choose Card Authentication Method

    The Google Pay™ API may return payment cards stored on file with the customer's Google Account (PAN_ONLY) and/or a device token on an Android device. This includes payment data with a cryptogram (CRYPTOGRAM_3DS) generated on the device.

      "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"]
    
    

    The PAN_ONLY will automatically follow the 3DS process to obtain liability shift to the issuer.

    GooglePay Object
    {
        "type": "CARD",
        "parameters":
            {
            "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
            "allowedCardNetworks": "MASTERCARD", "VISA"]
            },
        "tokenizationSpecification":
            {
            "type": "PAYMENT_GATEWAY",
            "parameters":
                {
                "gateway": "payonegmbh",
                "gatewayMerchantId": "yourPayoneMerchantid"
                }
            }

    ---end

    Forwarding the payment token to the PAYONE API

    After the customer has completed the payment sheet and authenticated themselves, you as the merchant, will receive a response object with the PaymentMethodTokenizationData from GoolgePay.

    Token example
    {
      "signature": "MEUCIFr4ETGzv0uLZX3sR+i1ScARXnRBrncyYFDX/TI/VSLCAiEAvC/Q4dqXMQhwcSdg/ZvXj8+up0wXsfHja3V/6z48/vk=",
      "intermediateSigningKey": {
        "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7PWUi+e6WPUhNmTSQ2WN006oWlcWy0FtBWizw9sph1wvX9XcXUNRLcfcsmCBfI5IsKQkjAmYxpCSB+L5sIudLw\\u003d\\u003d\",\"keyExpiration\":\"1722393105282\"}",
        "signatures": [
          "MEUCIQCpU30A3g2pP93IBE5NxgO9ZcJlGF9YPzCZS7H4/IR1CQIgF6+I5t8olT8YsRDUcj7w3R1bvX4ZCcyFXE2+YXa+3H0="
        ]
      },
      "protocolVersion": "ECv2",
      "signedMessage": "{\"encryptedMessage\":\"g8bw0neBOGqw739DUDshOZeCH8HhpWO+dh4tORaPoQOStkfbWNz2fNQiA8044eZiYpi9+5EWAB6w8F4WI2UnofSRp4jsG8s1cKYnI87XNxhYGHht1nLwya3nxH95w+85hsQyS6JcayJ+dxukqs7gf3LGy20SrpRcZchb+drR6SsBysK2Tb+OJd3x9EAq1U+65jCl8c4DqnLadi4hz6Myfusl5SPBVYEp8O7UdpkL8h8aLM3ahJwNp5LY8C3r2CKCM0N4wJKqB4KUCdYnm5mN2p0H404KFoPeKnO/bQcLogmwDwfzq23rVvbWaId6ps7En75yBgvTpSKFnSWmmDq82WGZlu9a7kPlfFNTZBfdrHY1y24ooHrQB0bMt9n0wrnH5MrTG/gWbBT7ulajUux4UyL8UucVWEc8/bx1hEQVotASEXep6yrH13GDwsdSxem2Ug1BLkzwVBF2Ghf23Wv3nuWz4S7S1OkdUDfJasuxQYcqyhH/0tEvj5dV2eEUMqQi0Ug/p3+m4x3GE8VhvPuJjRbHeVkSLnsYa3E5FujTsA\\u003d\\u003d\",\"ephemeralPublicKey\":\"BMtTvPwj3NpExAUqbg2mKM0RF3JkNe+ag6/gTdI6t/FeWTfybGfoFCEE+X+UjegnsCVpWlcD8BbWJqnE1h9NBK0\\u003d\",\"tag\":\"6Z88vW+1Vqtspsq6Cwp4tmyJqWx3hTpOBBYLJhJKH4Y\\u003d\"}"
    }


    To process the actual payment, you will need make an API  Pre- /Authorization request to PAYONE including the payment token received from Google as Base64 encoded.

    ---end

     Pre- /Authorization for GooglePay
      add_paydata[paymentmethod_token_data]=FpFyA6zSGkZC[...]xi8xeXCNbpGBpvlNXfcang==
      aid=12345
      amount=1000
      api_version=3.11
      cardtype=V
      clearingtype=wlt
      country=DE
      currency=EUR
      encoding=UTF-8
      firstname=Demo
      key=123456789abcdefghij
      lastname=Dude
      mid=12345
      mode=test
      portalid=123456
      reference=013265464564654
      request=preauthorization
      wallettype=GGP
    
    

    ---end

    Google Pay™ in App (android)

    How Google Pay™ Works

    The Google Pay™ API provides a streamlined checkout process for native Android applications, enabling customers to make purchases using payment methods saved to their Google Accounts within an app. When the customer clicks the Google Pay button in the app, the payment sheet appears, displaying all their saved payment methods and optional fields for shipping address data.

    Integration steps with PAYONE are similar to those for the web. However, the integration of the Google Pay API in an online shop or Android app differs.

    source: Google Developers

    1. Google Pay™ brand guideline for Android

    Make sure to follow the Google Pay™ brand guidelines before adding Google Pay™ payment button on Android application.

    2. Integrate Google Pay™ api

    Integrate Google Pay™ API in your Android application. For detailed instructions please use the Google Pay™ API Android integration guide and Google Pay™ API Android integration checklist

    ---end

    Payment gateway parameters

    You should use below values for the payment gateway as part of Tokenization Specifications as illustrated below:

    • type: "PAYMENT_GATEWAY"
    • GatewayId: payonegmbh
    • Gateway Merchant ID: <your merchant id with PAYONE>

          "tokenizationSpecification": {
            "type": "PAYMENT_GATEWAY",
            "parameters": {
              "gateway": "payonegmbh",
              "gatewayMerchantId": "yourPayoneMerchantId"
            }

    ---end

    Supported payment methods

    You should configure your Android app to accept only the card schemes supported by PAYONE for Google Pay and card schemes that your merchant account supports:

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

    ---end

    Choose Card Authentication Method

    The Google Pay™ API may return payment cards stored on file with the customer's Google Account (PAN_ONLY) and/or a device token on an Android device, which includes in payment data a cryptogram (CRYPTOGRAM_3DS) generated on the device.

      "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"]
    
    

    The PAN_ONLY will automatically follow the 3DS process to obtain liability shift to the issuer.

    GooglePay Object
    {
        "type": "CARD",
        "parameters":
            {
            "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
            "allowedCardNetworks": "MASTERCARD", "VISA"]
            },
        "tokenizationSpecification":
            {
            "type": "PAYMENT_GATEWAY",
            "parameters":
                {
                "gateway": "payonegmbh",
                "gatewayMerchantId": "yourPayoneMerchantid"
                }
            }

    ---end

    Forwarding the payment token to the PAYONE API

    After the customer has completed the payment sheet and authenticated themselves, you as the merchant, will receive a response object with the PaymentMethodTokenizationData from GoolgePay.
    To process the actual payment, you will need make an API  Pre- /Authorization request to PAYONE including payment token received from Google as Base64 encoded.

    ---end

     Pre- /Authorization for GooglePay
      add_paydata[paymentmethod_token_data]=FpFyA6zSGkZC[...]xi8xeXCNbpGBpvlNXfcang==
      aid=12345
      amount=1000
      api_version=3.11
      cardtype=V
      clearingtype=wlt
      country=DE
      currency=EUR
      encoding=UTF-8
      firstname=Demo
      key=123456789abcdefghij
      lastname=Dude
      mid=12345
      mode=test
      portalid=123456
      reference=013265464564654
      request=preauthorization
      wallettype=GGP
    
    

    ---end

    Google Pay™ Specific Error Messages

    Error Description Suggested Activity
    2702

    Error decrypting Apple Pay / Google Pay token
    Check if your payment processing certificate is valid and has been uploaded to the merchant backend.

    Check the environment settings for GooglePay  and mode for PAYONE to match either for Test or for Live.
    Otherwise please contact PAYONE.

    2703

    Certificate service declined request because of validation errors.
    An error occurred while processing this transaction (wrong parameters).

    Failure to decrypt or validate the Google Pay payment token due to incorrect encoding or malformed json
    Check the encoding (Base64) and/or unicode of the token.
    Check you are using the right gatewayMerchantId (your mid)
    Otherwise please contact PAYONE.