GooglePay - Direct API Integration

This document describes the integration steps for Google Pay using the direct API model.

Under the pure API integration model, merchants must build their own payment interfaces, such as the checkout page and payment results page. Furthermore, merchants must perform complex certificate configuration and encryption and decryption. Therefore, this model requires merchants to invest more in R&D costs.

For more information about the pure API integration model, please see the Integration Mode Overview.

1. Interaction Process

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#e6f0ff',
    'primaryTextColor': '#333',
    'primaryBorderColor': '#5b9bd5',
    'lineColor': '#888',
    'actorMargin': 40,
    'noteBkgColor': '#0056b3',
    'noteTextColor': '#ffffff',
    'noteBorderColor': '#004a99'
  }
}}%%
sequenceDiagram
    participant Client as Merchant Client
    participant MServer as Merchant Server
    participant PMServer as PayerMax Server
    participant Google as Google

    %% Phase 1: Order and Payment Sheet
    Client->>MServer: 1.1 User places order and selects Google Pay
    MServer->>Google: 1.2 Merchant requests Google Pay and launches Payment Sheet 
using developer account credentials

    %% Phase 2: Card Selection and Encryption
    Client->>Google: 2.1 User selects or adds a card and confirms
    Google->>Google: 2.2 Encrypt card info using Merchant Public Key
    Google-->>Client: 2.3 Return Encrypted Token

    %% Phase 3: Payment Processing
    Client->>MServer: 3.1 Submit Payment
    MServer->>MServer: 3.2 Decrypt using Private Key
    MServer->>PMServer: 3.3 Submit Payment Request
    PMServer->>PMServer: 3.4 Complete Payment
    PMServer-->>MServer: 3.5 Payment Result

2. Integration Steps

Merchants must first obtain a Google Pay Token, decrypt the token to obtain the card information, and then pass the decrypted card information to PayerMax.

For more information on Google Pay payment requests, please refer to: Google Pay Object Reference.

Note:

If merchants have already integrated Google Pay at their checkout, they can proceed directly to step 2.2.

2.1 Integrating Google Pay

For information on integrating Google Pay, please first refer to the Google Pay API Guide.

2.1.1 Configuring a Google Pay Merchant Account

1. Register for the Google Pay Business Console;

2. Obtain core parameters:

• merchantId - Google Merchant ID

• paymentGatewayId - Payment Gateway ID

3. Generate a decryption key:

# Generate an ECDSA key pair
openssl ecparam -genkey -name prime256v1 -noout -out google_pay_private.pem
openssl ec -in google_pay_private.pem -pubout -out google_pay_public.pem

2.1.2 Client-Side Integration with Google Pay

The server provides payment configuration parameters for the client to initialize Google Pay.

const paymentsClient = new google.payments.api.PaymentsClient({
  environment: 'PRODUCTION' // or 'TEST'
});

const paymentDataRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  merchantInfo: {
    merchantId: 'YOUR_GOOGLE_MERCHANT_ID',
    merchantName: 'Your Store Name'
  },
  allowedPaymentMethods: [{
    type: 'CARD',
    parameters: {
      allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
      allowedCardNetworks: ['VISA', 'MASTERCARD', 'AMEX']
    },
    tokenizationSpecification: {
      type: 'PAYMENT_GATEWAY',
      parameters: {
        'gateway': 'companyA',
        'gatewayMerchantId': 'YOUR_COMPANY_A_MID'
      }
    }
  }],
  transactionInfo: {
    totalPrice: '99.99',
    totalPriceStatus: 'FINAL',
    currencyCode: 'USD'
  }
};

paymentsClient.loadPaymentData(paymentDataRequest)
  .then(paymentData => {
    // Get an encrypted token
    const token = paymentData.paymentMethodData.tokenizationData.token;
    // Sent to the merchant server
    sendToServer({ googlePayToken: token });
  })
  .catch(err => console.error(err));

2.1.3 Decrypting the Payment Token on the Server

• The client returns the payment token paymentMethodData;

• Decrypt the token on the server. For details, please refer to: How to decrypt the payment method token.

2.2 Calling PayerMax for Payment

Create payment/orderAndPay API interface request, where the key fields are:

• paymentDetail.paymentMethodType: GOOGLEPAY

• paymentDetail.googlePayDetails: Decrypted payment information

API request example:

Pass the decrypted Card Information from the Google Pay Token to the data.paymentDetail.googlePayDetails field.

{
  "version": "1.4",
  "keyVersion": "1",
  "requestTime": "2022-02-25T09:23:06.473+00:00",
  "appId": "6666c8b036a24579974497c2f9800001",
  "merchantNo": "020213834421284",
  "data": {
    "outTradeNo": "Test1645780876511",
    "subject": "this is subject",
    "totalAmount": 1,
    "currency": "AED",
    "country": "AE",
    "userId": "userId001",
    "integrate": "Direct_Payment",
    "expireTime": "1800",
    "paymentDetail": {
      "paymentMethodType": "GOOGLEPAY",
      "buyerInfo": {
        "firstName": "James",
        "lastName": "Smith",
        "phoneNo": "903124360628",
        "email": "james@google.com",
        "clientIp": "124.156.108.193",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36"
      },
      "googlePayDetails": {
        "authMethod": "CRYPTOGRAM_3DS",
        "cardHolderFullName": "cryptogram googlePayDetails cardHolderFullName",
        "cardNetwork": "VISA",
        "expirationMonth": "01",
        "expirationYear": "2029",
        "pan": "3604241234569621",
        "description": ""
    },
    "goodsDetails": [
      {
        "goodsId": "D002",
        "goodsName": "Key buckle",
        "quantity": "2",
        "price": "0.5",
        "goodsCurrency": "AED",
        "showUrl": "http://ttt.com",
        "goodsCategory": "电脑"
      }
    ],
    "shippingInfo": {
      "firstName": "James",
      "lastName": "Smith",
      "phoneNo": "903124360628",
      "email": "James@google.com",
      "address1": "GOLGELI SOKAK NO.34, 06700",
      "city": "GAZIOSMANPASA/ANKAR",
      "country": "TR",
      "zipCode": "06700"
    },
    "billingInfo": {
      "firstName": "James",
      "lastName": "Smith",
      "phoneNo": "903124360628",
      "email": "James@google.com",
      "address1": "GOLGELI SOKAK NO.34, 06700",
      "city": "GAZIOSMANPASA/ANKAR",
      "country": "TR",
      "zipCode": "06700"
    },
    "riskParams": {
      "registerName": "lily",
      "regTime": "2023-07-01 12:08:34",
      "liveCountry": "VN",
      "payerAccount": "987654XXX",
      "payerName": "lily",
      "taxId": "1234567890"
    },
    "language": "en",
    "reference": "020213827524152",
    "terminalType": "WAP",
    "frontCallbackUrl": "https://xxx.com",
    "notifyUrl": "https://yyy.com"
  }
}

Interface response example:

{
  "code": "APPLY_SUCCESS",
  "msg": " Success.",
  "data": {
    "outTradeNo": "a1234934974321",
    "tradeToken": "T2025051210335071234567",
    "status": "SUCCESS"
  }
}

注意：

1. Make sure that your documentation links to Google Pay Android brarnd guidelines or Google Pay web brand guidelines appropriately, and if your documentation displays any example of Google Pay assets, which uses approved assets only in compliance with our guidelines.

2. Adhere to Google policies: all merchants are required to follow the Google Pay and Wallet API's Acceptable Use Policy and acccept the terms defined in the Google Pay API Terms of Service .

3. We provide 3DS on Google Pay PAN_ONLY transactions. Depends on situation, PAN_ONLY credential returned from a Google Pay PAN_ONLY encrypted payload will initiate 3DS verification.