Google Pay

Google Pay lets customers check out quickly with a card saved to their Google account, in Chrome, Safari, Firefox, Edge, and other major browsers. With Checkout and the Web SDK, Onerway renders the Google Pay button and handles the token. With the Direct API, you load the Google Pay JS SDK yourself, obtain the encrypted payment token, and submit it to Onerway.

Choose an integration method

All three methods require HTTPS and Google Pay enabled on your Onerway merchant account. Browser and device support follows the Google Pay Web documentation; for sandbox testing, join the test card group with a Google account, see Test cards.

Setup

Before integrating through the Direct API, decide how token authentication methods are handled, who decrypts the token, and where the merchant identifier comes from.

Token authentication method

authMethod is determined by the status of the customer's card on the Google side and you cannot choose it; Onerway requires allowedAuthMethods to declare both values below, accepting only one is not supported:

• CRYPTOGRAM_3DS: a card the customer has tokenized on the device; the token carries a dynamic cryptogram and 3DS credentials and can be authorized directly.
• PAN_ONLY: a card saved to the Google account but not tokenized on a device; the token carries no 3DS credentials, so the CVC must be collected before it can be charged, see "Two paths for PAN_ONLY tokens".

Both values occur in real traffic, and not declaring PAN_ONLY means you cannot charge those customers. PAN_ONLY does not mean the card number reaches you: with Onerway decryption the token is encrypted with the Onerway key and the card number never enters your systems, and on the standard path the CVC is collected on an Onerway-hosted page, so no PCI DSS compliance is required. PCI DSS applies only if you choose merchant decryption or collect the CVC yourself.

Decryption mode

For merchant decryption, map the decrypted result into cardInfo as follows:

Merchant identifier

Google requires merchantInfo.merchantId when environment is PRODUCTION (optional in TEST). Its value depends on how your domain is registered; choose one:

• Onerway registers your domain under its Google Pay & Wallet Console profile: use the merchantId returned by List available payment methods.
• You register your own Google Pay & Wallet Console profile and domain: use your own merchant identifier. Merchant decryption requires this option.

Confirm with Onerway technical support which account you will use, then complete website registration before going live.

Website registration before going live

This applies only to Direct API integrations; Checkout and the Web SDK use Onerway's Google Pay integration and need no website registration.

Register your website and obtain Google's approval before accepting production payments; a successful sandbox test does not replace it. Follow Google's Publish your integration guide for the Google Pay account you use:

The domain is the website that calls the Google Pay API. The account determines only the merchantInfo.merchantId to use: your own account does not require merchant decryption, and when Onerway decrypts the token, gatewayName and gatewayMerchantId still come from List available payment methods.

Five screenshots for Onerway registration

Provide one screenshot for each stage of your purchase flow:

If Android blocks screenshots of the Google Pay payment sheet, photograph the screen with another device; for this item only, an image of an error message is also accepted.

Switch to production after approval

After Google approves the website, set the merchantInfo.merchantId of the registering account, create the PaymentsClient with environment=PRODUCTION, and create transactions with your Onerway production API base URL and credentials.

Direct API integration

<script async src="https://pay.google.com/gp/p/js/pay.js" onload="onGooglePayLoaded()"></script>

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

Two paths for PAN_ONLY tokens

Neither path needs extra enablement.

When you collect the CVC yourself:

• After obtaining the token, call Check Google Pay PAN_ONLY token first.
• When checkResult=false, collect the CVC from the customer and create the direct transaction with the same tokenInfo and the CVC in cardInfo.cvv. For a PAN_ONLY token submitted without cardInfo.cvv, the transaction response contains data.status=R and data.redirectUrl; redirect the customer to data.redirectUrl to enter the CVC on the Onerway-hosted page. This applies whether or not you called the check endpoint before creating the transaction.
• When checkResult=true, create the direct transaction with the same tokenInfo; cardInfo is not required.
• The check and the transaction must use the same token and the same merchantTxnId; fall back to the standard path if the check call fails.
• Validate the CVC length in real time (3 digits for most card networks, 4 for American Express), display it as a password field, and tell the customer why it is needed.

Front-end example

Fill in the configuration from your server; processPayment hands the token to your server.

<div id="container"></div>
<script>
  // Configuration from the GooglePay record returned by List available payment methods on your server
  const onerwayConfig = {
    gateway: '<gatewayName>',
    gatewayMerchantId: '<gatewayMerchantId>',
    allowedCardNetworks: ['MASTERCARD', 'VISA'],
    merchantId: '<merchantId>',
    countryCode: 'US'
  }

  const baseRequest = { apiVersion: 2, apiVersionMinor: 0 }
  const baseCardPaymentMethod = {
    type: 'CARD',
    parameters: { allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'], allowedCardNetworks: onerwayConfig.allowedCardNetworks }
  }
  const cardPaymentMethod = {
    ...baseCardPaymentMethod,
    tokenizationSpecification: {
      type: 'PAYMENT_GATEWAY',
      parameters: { gateway: onerwayConfig.gateway, gatewayMerchantId: onerwayConfig.gatewayMerchantId }
    }
  }

  let paymentsClient = null
  function getPaymentsClient() {
    if (!paymentsClient) {
      paymentsClient = new google.payments.api.PaymentsClient({ environment: 'TEST' }) // 'PRODUCTION' when live
    }
    return paymentsClient
  }

  function getPaymentDataRequest() {
    return {
      ...baseRequest,
      allowedPaymentMethods: [cardPaymentMethod],
      transactionInfo: { countryCode: onerwayConfig.countryCode, currencyCode: 'USD', totalPriceStatus: 'FINAL', totalPrice: '99.99' },
      merchantInfo: { merchantId: onerwayConfig.merchantId, merchantName: 'Example Store' }
    }
  }

  function onGooglePayLoaded() {
    getPaymentsClient()
      .isReadyToPay({ ...baseRequest, allowedPaymentMethods: [baseCardPaymentMethod] })
      .then((res) => {
        if (!res.result) return
        const button = getPaymentsClient().createButton({ onClick: onButtonClicked, allowedPaymentMethods: [baseCardPaymentMethod] })
        document.getElementById('container').appendChild(button)
      })
  }

  function onButtonClicked() {
    getPaymentsClient()
      .loadPaymentData(getPaymentDataRequest())
      .then(processPayment)
      .catch(() => {
        // The customer closed the Google Pay sheet or the payment failed; restore the page
      })
  }

  async function processPayment(paymentData) {
    // Never log or store the token
    const paymentToken = paymentData.paymentMethodData.tokenizationData.token
    // Server calls Create direct transaction (tokenInfo.provider=GooglePay), maps a respCode other than 20000 to status 'F', and returns { status, redirectUrl }
    const res = await fetch('/api/google-pay/process-payment', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ paymentToken })
    }).then(r => r.json())

    if (res.status === 'R' && res.redirectUrl) {
      window.location.href = res.redirectUrl // PAN_ONLY: redirect to the Onerway-hosted page to collect the CVC; the final state comes from the webhook
    } else if (res.status === 'S') {
      // Synchronous success; the payment result webhook remains the final source of truth
    } else if (res.status === 'F') {
      // Failed; ask the customer to choose another payment method
    } else {
      // Processing; wait for the payment result webhook
    }
  }
</script>
<script async src="https://pay.google.com/gp/p/js/pay.js" onload="onGooglePayLoaded()"></script>

Google resources: Web integration guide, interactive demos, brand guidelines.

Wallet subscriptions

Google Pay can be used for subscriptions: submit subProductType=SUBSCRIBE with subscription on the initial subscription; both selfExecute=1 (managed by Onerway) and selfExecute=2 (you initiate each billing) are supported. On Checkout, lock to Google Pay with lpmsInfo.lpmsType=GooglePay; on the Direct API, submit the encrypted wallet token in tokenInfo to create the initial subscription. After the initial subscription succeeds, the subscription payment webhook returns contractId and the subscription tokenId; renewals and plan changes then work the same as card subscriptions, see Subscription payments.

Differences from card subscriptions: the encrypted wallet token is single-use and cannot be saved for reuse, so the only billing credential during the subscription is the subscription token; wallet subscriptions produce no saved payment method result webhook and return no card token.

Common issues

Go-live checklist

• Direct API only: website registration is complete and approved by Google.
• The token is never decrypted on the client and never logged or stored.
• Both the PAN_ONLY redirect path and the CRYPTOGRAM_3DS direct success path have been tested with real cards.
• If you collect the CVC yourself, the fallback for a failed check call has been tested.
• Webhook signature verification, deduplication, and amount checks are in place.