Table Of Contents
  INTRODUCTION  OVERVIEW  TEST DATA  LIABILITY SHIFT  PREREQUISITES  ONBOARDING  GOOGLE PAY™ ON YOUR WEBSITE  HOW GOOGLE PAY™ WORKS  2. INTEGRATE GOOGLE PAY™ API  GOOGLE PAY™ IN APP (ANDROID)  HOW GOOGLE PAY™ WORKS  2. INTEGRATE GOOGLE PAY™ API  PARAMETERS FOR GOOGLE PAY PAYMENTS  GOOGLE PAY™ SPECIFIC ERROR MESSAGES

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.


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

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

    Payment gateway parameters

    Supported payment methods

    Choose Card Authentication Method

    Forwarding the payment token to the PAYONE API


    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.

    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

    Payment gateway parameters

    Supported payment methods

    Choose Card Authentication Method

    Forwarding the payment token to the PAYONE API

    Parameters for Google Pay Payments

    Structure mobilePaymentMethodSpecificInputSpecificInput GROUP

    Mandatory parameters

    The following parameters are mandatory for every Google Pay payment method:

    Parameter Description
      paymentProductId  Payment product identifier - please check product documentation for a full overview of possible values. ( for Google Pay is 320 )
      authorizationMode

     Determines the type of the authorization that will be used. Allowed values:

    • PRE_AUTHORIZATION - The payment creation results in a pre-authorization that is ready for Capture. Pre- authortizations can be reversed and can be captured within 30 days. The capture amount can be lower than the authorized amount.
    • SALE - The payment creation results in an authorization that is already captured at the moment of approval.
      encryptedPaymentData  The payment data if we will do the decryption of the encrypted payment data. Typically you'd use encryptedCustomerInput in the root of the create payment request to provide the encrypted payment data instead.
      threeDSecure.redirectionData.returnUrl  The URL that the customer is redirected to after the payment flow has finished. You can add any number of key value pairs in the query string that, for instance help you to identify the customer when they return to your site. Please note that we will also append some additional key value pairs that will also help you with this identification process. Note: The provided URL should be absolute and contain the protocol to use, e.g. http:// or https://. For use on mobile devices a custom protocol can be used in the form of protocol://. This protocol must be registered on the device first. URLs without a protocol will be rejected.

    Example

    Simple example for a Google Pay payment via Commerce Platform

    • Creating a checkout (here in one step, creating in multiple steps possible)
    • Creating an order for the entire checkout (partial orders also possible), payment is initialized automatically
    • Initialization of deliver to capture the amount of the order (partial deliver also possible)

     

    Create CommerceCase/Checkout WITH AUTOEXECUTE ORDER

    Creating a Commerce Case with the initial Checkout including a reference, information about the customer and the items in the shopping cart, including also the Apple Pay payment details. 

    Example without 3D secure redirection.

    POST Commerce Case
    Request
    /v1/{merchantId}/commerce-cases
    {
  "merchantReference" : "DuHqTKPrzc",
  "customer" : {
    "merchantCustomerId" : "123456",
    "billingAddress" : {
      "city" : "Bremervörde",
      "countryCode" : "DE",
      "houseNumber" : "23a",
      "state" : "MS",
      "street" : "Moritz-Günther-Straße",
      "zip" : "22332"
    },
    "contactDetails" : {
      "emailAddress" : "test@test.com",
      "phoneNumber" : "0188711725"
    },
    "fiscalNumber" : "23432334432233",
    "businessRelation" : "B2C",
    "personalInformation" : {
      "dateOfBirth" : "19800101",
      "name" : {
        "firstName" : "Chaos - Gott",
        "surname" : "Nörgle"
      }
    }
  },
  "checkout" : {
    "amountOfMoney" : {
      "amount" : 100,
      "currencyCode" : "EUR"
    },
    "references" : {
      "merchantReference" : "DuHqTKPrzc"
    },
    "shipping" : {
      "address" : {
        "city" : "Lüdenscheid",
        "countryCode" : "DE",
        "houseNumber" : "77b",
        "state" : "WA",
        "street" : "Platz der guten Hoffnung",
        "zip" : "99999",
        "name" : {
          "firstName" : "Rüdiger",
          "surname" : "Sörensen",
          "title" : "Prof. Dr."
        }
      }
    },
    "shoppingCart" : {
      "items" : [ {
        "invoiceData" : {
          "description" : "Beschreibung"
        },
        "orderLineDetails" : {
          "productCode" : "Produkt-Code",
          "productPrice" : 100,
          "productType" : "GOODS",
          "quantity" : 1,
          "taxAmount" : 19
        }
      } ]
    },
    "orderRequest" : {
      "orderReferences" : {
        "descriptor" : "status_SUCCESSFUL",
        "merchantReference" : "DuHqTKPrzc"
      },
      "paymentMethodSpecificInput" : {
        "mobilePaymentMethodSpecificInput" : {
          "paymentProductId" : 320,
          "authorizationMode" : "PRE_AUTHORIZATION",
          "encryptedPaymentData" : "+sp+Vffqkq5mtGn2RhP1qXgRBC1hOSzWCXt1CAHK/ZjnHIh1ZjJyQ+4lG7MnwXOBd3M8lRgxicxmKNJlATJLhOLALUVfWvFz3unq7QWZHmVW8RJ2zwNGlyQxhWn9umuG/5eAuH0zDB75+NxbyAUim+ptRcDWSpbR3t0+SVAXX0NG+7Dbh23ArUerZbIej2whQvpq4yOUbe+o6RorktTmqiE3xJ5CWwjy1U6VXO9zqpX8y9ezOAZ9La8pJvllvPcmclh6PKeIT/lvOBxv5QqN0+fj/weaI0pt25BFijlLf7sPw/RiBoOrEYjq82BxVORmUSJu3VESDfRdxRiuG1LlxM46Lgju6xWrHa6gj4oS/VrJhShmmIKQESjv0PWPAxx9pNyzs9GtqgWix2M1",

           "threeDSecure": {
                "redirectionData": {
                     "returnUrl": "https://secure.yourwebsite.com/ncol/test/displayparams.asp"
                                              }
         },
    },
    "autoExecuteOrder" : true
  }
}

    Response
    {
  "commerceCaseId" : "1d08123e-71ce-4fe6-b512-de9bcfa6292b",
  "merchantReference" : "DuHqTKPrzc",
  "customer" : {
    "merchantCustomerId" : "123456",
    "billingAddress" : {
      "city" : "Bremervörde",
      "countryCode" : "DE",
      "houseNumber" : "23a",
      "state" : "MS",
      "street" : "Moritz-Günther-Straße",
      "zip" : "22332"
    },
    "contactDetails" : {
      "emailAddress" : "test@test.com",
      "phoneNumber" : "0188711725"
    },
    "fiscalNumber" : "23432334432233",
    "businessRelation" : "B2C",
    "personalInformation" : {
      "dateOfBirth" : "19800101",
      "name" : {
        "firstName" : "Chaos - Gott",
        "surname" : "Nörgle"
      }
    }
  },
  "checkout" : {
    "checkoutId" : "1c175daa-fd0c-4b5b-b32e-29956878420d",
    "shoppingCart" : {
      "items" : [ {
        "invoiceData" : {
          "description" : "Beschreibung"
        },
        "orderLineDetails" : {
          "id" : "b19db2a5-b6a0-47e5-b22c-7bbc28181da5",
          "status" : [ {
            "cartItemStatus" : "ORDERED",
            "quantity" : 1
          } ],
          "productCode" : "Produkt-Code",
          "productPrice" : 100,
          "productType" : "GOODS",
          "quantity" : 1,
          "taxAmount" : 19
        }
      } ]
    },
    "paymentResponse" : {
      "payment" : {
        "paymentOutput" : {
          "amountOfMoney" : {
            "amount" : 100,
            "currencyCode" : "EUR"
          },
          "references" : {
            "merchantReference" : "DuHqTKPrzc"
          },
          "mobilePaymentMethodSpecificOutput" : {
            "paymentProductId" : 302
          },
          "paymentMethod" : "mobile"
        },
        "status" : "PENDING_CAPTURE",
        "statusOutput" : {
          "isCancellable" : true,
          "statusCategory" : "PENDING_MERCHANT",
          "isAuthorized" : true,
          "isRefundable" : false
        },
        "id" : "PP2ABD7X9XUCZ9X1"
      },
      "paymentExecutionId" : "e601283a-b81f-4241-9039-370769e45ef8"
    },
    "amountOfMoney" : {
      "amount" : 100,
      "currencyCode" : "EUR"
    },
    "references" : {
      "merchantReference" : "DuHqTKPrzc"
    },
    "shipping" : {
      "address" : {
        "city" : "Lüdenscheid",
        "countryCode" : "DE",
        "houseNumber" : "77b",
        "state" : "WA",
        "street" : "Platz der guten Hoffnung",
        "zip" : "99999",
        "name" : {
          "firstName" : "Rüdiger",
          "surname" : "Sörensen",
          "title" : "Prof. Dr."
        }
      }
    },
    "paymentExecution" : {
      "paymentExecutionId" : "e601283a-b81f-4241-9039-370769e45ef8",
      "paymentId" : "PP2ABD7X9XUCZ9X1",
      "mobilePaymentMethodSpecificInput" : {
        "paymentProductId" : 320,
        "authorizationMode" : "PRE_AUTHORIZATION",
        "encryptedPaymentData" : "+sp+Vffqkq5mtGn2RhP1qXgRBC1hOSzWdfsdfsdfsdfsdfUSJu3VESDfRdxRiuG1LlxM46Lgju6xWrHa6gj4oS/VrJhShmmIKQESjv0PWPAxx9pNyzs9GtqgWix2M1",
        }
      },
      "paymentChannel" : "ECOMMERCE",
      "references" : {
        "descriptor" : "status_SUCCESSFUL",
        "merchantReference" : "DusdfKPrzc"
      },
      "lastUpdated" : "2024-09-09T11:21:38.367496947Z",
      "events" : [ {
        "type" : "RESERVATION",
        "amountOfMoney" : {
          "amount" : 100,
          "currencyCode" : "EUR"
        },
        "paymentStatus" : "PENDING_CAPTURE"
      } ]
    },
    "checkoutStatus" : "COMPLETED",
    "statusOutput" : {
      "paymentStatus" : "PAYMENT_NOT_COMPLETED",
      "isModifiable" : false,
      "openAmount" : 100,
      "collectedAmount" : 0,
      "cancelledAmount" : 0,
      "refundedAmount" : 0,
      "chargebackAmount" : 0
    },
    "creationDateTime" : "2024-09-09T11:21:37.976738656Z",
    "allowedPaymentActions" : [ "ORDER_MANAGEMENT", "PAYMENT_EXECUTION" ]
  },
  "creationDateTime" : "2024-09-09T11:21:37.976738656Z"
}

    Webhook after successful confirmation on Apple Pay portal by end customer

    You can identify the corresponding transaction by the field createPaymentResponse.payment.id in the order response. The status PENDING_CAPTURE shows that the amount is authorized and the payment gateway is waiting for a capture.

    Webhook
    {
    "apiVersion": "v1",
    "created": "2023-11-15T09:54:18.097694888+00:00",
    "id": "88ec52d6-bd59-47bf-b21e-147508d85b02",
    "merchantId": "P1_XXXX_XXXXX",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 100,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "DusdfKPrzc"
            },
            "mobilePaymentMethodSpecificInput": {
                "paymentProductId": 320
            },
            "paymentMethod": "redirect"
        },
        "status": "PENDING_CAPTURE",
        "statusOutput": {
            "isCancellable": true,
            "statusCategory": "PENDING_MERCHANT",
            "isAuthorized": true,
            "isRefundable": false
        },
        "id": "PP2ABD7X9XUCZ9X1"
    },
    "type": "payment.pending_capture"
}

    Deliver

    Full Deliver to capture the complete order amount.

    POST Deliver
    Request
    /v1/{merchantId}/commerce-cases/{commerceCaseId}/checkout/{checkoutId}/deliver
     {
  "deliverType": "FULL",
  "isFinal": false,
  "cancellationReason": "CONSUMER_REQUEST",
  "deliverItems": [
    {
      "id": "b19db2a5-b6a0-47e5-b22c-7bbc28181da5",
      "quantity": 1
    }
  ]
}

    Response
    {
    "capturePaymentResponse": {
        "captureOutput": {
            "amountOfMoney": {
                "amount": 100,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "DuHqTKPrzc"
            },
            "paymentMethod": "mobile"
        },
        "status": "CAPTURED",
        "id": "TX2AAD7X9X452WAY"
    },
    "shoppingCart" : {
      "items" : [ {
        "invoiceData" : {
          "description" : "Beschreibung"
        },
        "orderLineDetails" : {
          "id" : "b19db2a5-b6a0-47e5-b22c-7bbc28181da5",
          "status" : [ {
            "cartItemStatus" : "ORDERED",
            "quantity" : 1
          } ],
          "productCode" : "Produkt-Code",
          "productPrice" : 100,
          "productType" : "GOODS",
          "quantity" : 1,
          "taxAmount" : 19
        }
      } ]
    }
}

    Webhook after successful Deliver

    The payment gateway informs you via webhook about the successful capture.

    Webhook
    {
    "apiVersion": "v1",
    "created": "2023-11-14T17:25:17.996829148+00:00",
    "id": "74e4fe0e-ee75-4c02-9b80-a3e3df8140d4",
    "merchantId": "P1_XXXX_XXXXX",
    "payment": {
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 100,
                "currencyCode": "EUR"
            },
            "references": {
                "merchantReference": "DusdfKPrzc"
            },
            "mobilePaymentMethodSpecificInput": {
                "paymentProductId": 320
            },
            "paymentMethod": "mobile"
        },
        "status": "CAPTURED",
        "statusOutput": {
            "isCancellable": false,
            "statusCategory": "COMPLETED",
            "isAuthorized": true,
            "isRefundable": true
        },
        "id": "TX2AAD7X9X452WAY"
    },
    "type": "payment.captured"
}

    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.