Accept Google Pay™ with OneGate

01Overview

OneGate offers Google Pay™ as a payment method through three integration approaches, letting you choose the best fit for your architecture and PCI compliance posture. The OneGate platform securely decrypts the Google Pay token and processes the payment; you manage only the checkout experience.

Every Google Pay integration on OneGate:

• Uses a server-generated payment key as the session identifier.
• Requires HTTPS on your domain.
• Supports the PAN_ONLY and CRYPTOGRAM_3DS authorization methods.
• Supports Visa, Mastercard, American Express and Discover.
• Is PCI DSS Level 1 compliant via the OneGate platform.

02Integration methods

Pick the path that matches how much of the checkout you want to own.

03Requirements

• A OneGate merchant account with Google Pay enabled.
• A unique payment key, generated server-side, for each transaction.
• HTTPS and a valid SSL certificate on your domain.
• For SDK and widget integrations: a browser or device that supports Google Pay. Google Pay works in Chrome, Edge, Safari, Firefox, Opera and other modern browsers, and on Android with the Google Wallet app.
• For the Wallet Pay SDK and the Checkout Widget: register your production and staging domains with OneGate so they are added to the Google Pay Business Console. Google validates the top-level (parent) domain where the button renders, so register the parent domain your checkout runs on. Only the hosted redirect flow is exempt, since it runs on OneGate's own registered domain.

04Authentication

API calls are authenticated with three HTTP headers on every request. There is no token in the request body. Base URL: https://payments.onegate.co.za/api/v2/.

Your api_salt is a secret issued by OneGate and kept server-side. Compute the Auth-Token per request:

const crypto = require('crypto');
const timestamp = Math.floor(Date.now() / 1000);
const authToken = crypto.createHash('sha256')
  .update(`${apiSalt}_${orgId}_${timestamp}`)
  .digest('hex');
// send as headers: Auth-Token, Org-Id, Timestamp

05Create a payment key

The payment key is the setup identifier for every transaction. Generate it server-side; all three integration methods use it. It expires 10 minutes after creation.

curl -X POST https://payments.onegate.co.za/api/v2/payment-key \
  -H "Auth-Token: {sha256_hex of api_salt_org_id_timestamp}" \
  -H "Org-Id: {your-org-id}" \
  -H "Timestamp: {unix-timestamp}" \
  -d "amount=150.00" \
  -d "merchant_reference=ORDER-12345" \
  -d "success_url=https://merchant.com/success" \
  -d "error_url=https://merchant.com/error" \
  -d "notify_url=https://merchant.com/webhook" \
  -d "payment_type=credit_card" \
  -d "wallet_payment=google_pay"

Use payment_type=all to show Google Pay alongside your other payment methods. The response returns the key and a hosted url:

{
  "key": "0cd95fd9adabdc00275fdf6eef675950",
  "url": "https://payments.onegate.co.za/pay/hosted?payment_key=...&payment_type=google_pay",
  "origin": "https://payments.onegate.co.za"
}

Shared parameters

06Hosted redirect

The simplest method. After creating a payment key, redirect the customer to the url in the response. OneGate hosts the page, renders the Google Pay button using the standard Google Pay API, and handles the full flow.

https://payments.onegate.co.za/pay/hosted?payment_key={key}&payment_type=google_pay

The hosted page detects device support on load: if Google Pay is available the button renders, otherwise an in-page message points the customer to alternative methods. You can redirect safely without doing your own OS or browser checks.

Merchant setup steps

1. Contact OneGate support to enable Google Pay on your organisation and register your production domain.
2. In your OneGate dashboard, confirm Google Pay is enabled under Organisation Settings, Wallet Payments.
3. If you load the hosted URL inside an iframe, allow frame-src https://payments.onegate.co.za and connect-src https://payments.onegate.co.za in your Content-Security-Policy. The default top-level redirect needs no CSP change.
4. Configure your success_url, error_url, cancel_url and notify_url before going live.

07Wallet Pay SDK

The SDK renders a native Google Pay button directly on your site. It loads the official Google Pay API script, handles isReadyToPay() detection, presents the payment sheet, extracts the token and submits it to OneGate, with no redirect or iframe.

<script src="https://payments.onegate.co.za/ext/wallet-pay/v1/google-pay.js"></script>

<div id="google-pay-button"></div>

var gpay = new CallpayGooglePay({
  serviceUrl: 'https://payments.onegate.co.za',
  paymentKey: '{{your-payment-key}}',
  containerId: 'google-pay-button',
  onSuccess: function(result){ window.location.href = '/success'; },
  onError:   function(error){ alert(error.message); }
});
gpay.init().catch(function(){
  // Google Pay unavailable on this device: hide the button
  document.getElementById('google-pay-button').style.display = 'none';
});

Button appearance

You can customise the button. The SDK passes every appearance option straight to the Google Pay API's own createButton(), so what you set is limited to the options Google publishes in ButtonOptions, and the rendered asset stays an approved one.

var gpay = new CallpayGooglePay({
  serviceUrl: 'https://payments.onegate.co.za',
  paymentKey: '{{your-payment-key}}',
  containerId: 'google-pay-button',
  buttonType: 'checkout',
  buttonColor: 'white',
  buttonOptions: { buttonSizeMode: 'fill', buttonRadius: 4 },
  onSuccess: function(result){ window.location.href = '/success'; }
});

Domain registration

Google Pay requires the domain that renders the button to be registered against a Google Pay Business Console merchant ID. This applies to both the Wallet Pay SDK and the Checkout Widget: even though the widget renders in an iframe, Google validates the top-level (parent) domain of the page, which is your site. Send OneGate support the parent domains where your checkout runs (for example checkout.yoursite.com) and we register each one. Approval is usually immediate. Only the hosted redirect flow is exempt.

08Checkout widget

The widget shows Google Pay in an iframe-based modal on your page without leaving the site, keeping you fully descoped from PCI.

<script src="https://payments.onegate.co.za/ext/checkout/v4/checkout.js"></script>
<button id="pay-button">Pay with Google Pay</button>

document.getElementById('pay-button').addEventListener('click', async () => {
  const checkout = new EftSecureCheckout({
    serviceUrl: 'https://payments.onegate.co.za/rpp-transaction/create-from-key',
    paymentKey: '{{your-payment-key}}',
    paymentType: 'credit_card',
    walletPayment: 'google_pay',
    onComplete: (data) => { window.location.href = data.success ? '/success' : '/error'; }
  });
  await checkout.init();
});

Pass paymentType and walletPayment explicitly. To show Google Pay alongside other methods use paymentType: 'all' and omit walletPayment.

09Webhooks

Implement webhooks (notify_url) for reliable payment confirmation rather than relying on client-side callbacks alone. The webhook is delivered asynchronously once the gateway confirms the status, and retried on failure with exponential backoff.

1. Customer completes payment via Google Pay (any method).
2. Show a "thank you" page from the client-side callback or redirect.
3. Trust the webhook: use its payload to update order status and fulfil.
4. As a fallback, query the View Transaction API to confirm status and amount before fulfilment.

Transaction statuses

103D Secure and authorization methods

Google Pay returns credentials under one of two authMethod values. Both are supported, and 3DS handling differs by method. OneGate can restrict the methods enabled for your organisation.

Choosing which methods you accept

Two separate things are easily confused here. You do not choose what Google returns for a given shopper: that follows from the device and the card. A shopper on desktop Chrome paying with a card saved to their Google account yields PAN_ONLY; the same card provisioned in the Google Wallet app on Android yields CRYPTOGRAM_3DS. You do choose which of the two you accept.

Acceptance is the allowedAuthMethods field of the Google Pay CardParameters object. OneGate sets it for you from a per-organisation setting, so you never send it by hand, but the value is yours to decide:

Restricting to CRYPTOGRAM_3DS is a legitimate choice for a merchant who wants every wallet payment to carry liability shift, and it is how a higher-risk merchant can guarantee that. Treat it as a reach decision rather than a purely technical one: the narrower the setting, the fewer shoppers can complete a Google Pay payment. Contact OneGate support to change it for your organisation.

Assurance details

OneGate sets assuranceDetailsRequired: true on every request, so Google returns an assuranceDetails object alongside the credential, describing the validation it performed through the accountVerified and cardHolderAuthenticated flags.

This reports on the credential you were given; it does not control which credential you receive, and it cannot be used to require an authenticated one. allowedAuthMethods is the setting for that. OneGate records both flags against the transaction for verification, and does not treat cardHolderAuthenticated: true as a reason to skip the 3D Secure step-up on a PAN_ONLY credential.

Enabling 3DS for PAN_ONLY credentials

A PAN_ONLY payload decrypts to a normal card PAN with no Google Pay cryptogram, so it carries no wallet-side authentication. For merchants provisioned for OneGate decryption, PAN_ONLY credentials are automatically stepped up through 3D Secure before authorisation, using the same 3DS 2.x authentication (frictionless or challenge, as the issuer determines) that OneGate applies to a standard card payment.

This is handled by OneGate. You do not add any parameter, SDK option or code to enable it:

1. OneGate decrypts the PAN_ONLY payload and detects that no cryptogram is present.
2. The transaction is stepped up through OneGate's standard card 3D Secure flow.
3. 3DS on Google Pay PAN_ONLY is enabled by OneGate provisioning it on your organisation. If you require it, contact OneGate support to confirm your organisation is provisioned for OneGate decryption.

11API configuration

OneGate's SDK and hosted pages build the Google Pay PaymentDataRequest for you using the PAYMENT_GATEWAY tokenization type. In all three integration paths, OneGate sets both gateway and gatewayMerchantId; you never set them by hand.

The standard configuration OneGate generates, shown for reference:

const baseCardPaymentMethod = {
  type: 'CARD',
  parameters: {
    allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
    allowedCardNetworks: ['VISA', 'MASTERCARD', 'AMEX', 'DISCOVER']
  },
  tokenizationSpecification: {
    type: 'PAYMENT_GATEWAY',
    parameters: {
      gateway: 'onegate',
      gatewayMerchantId: '00021414'   // your org id, 8 digits ('googletest' in TEST)
    }
  }
};

const paymentDataRequest = {
  apiVersion: 2, apiVersionMinor: 0,
  allowedPaymentMethods: [baseCardPaymentMethod],
  merchantInfo: {
    merchantId: 'BCR2DN6D3L72TUDX',   // OneGate Google Pay & Wallet Console merchant ID
    merchantName: 'OneGate'
  },
  transactionInfo: {
    totalPriceStatus: 'FINAL', totalPrice: '150.00',
    currencyCode: 'ZAR', countryCode: 'ZA'
  }
};

Card networks

Define the networks you accept in allowedCardNetworks. OneGate supports VISA, MASTERCARD, AMEX and DISCOVER; the SDK sends all four by default. If your acquiring agreement covers a subset, OneGate can restrict the list for your organisation. All OneGate Google Pay transactions settle in South Africa.

Billing address

By default OneGate's Google Pay integration does not require a billing address: billingAddressRequired is not set, so the sheet does not collect address data. If your risk profile needs address verification, OneGate can enable BillingAddressParameters (format: 'FULL' or 'MIN') on your organisation; contact support.

Submitting encrypted data

You never handle the encrypted token directly. The SDK submits the token and payment session to POST /api/v2/google-pay; OneGate decrypts and processes it. For hosted and widget flows this happens entirely on OneGate's servers.

12Testing

• A test environment is available on request. Contact OneGate support for test credentials; test transactions use the same /api/v2/payment-key endpoint.
• For the SDK, use Google Pay test cards in Chrome and set debug: true for verbose logging.
• In the TEST environment, gatewayMerchantId is the literal googletest.
• Verify isReadyToPay() behaviour on supported and unsupported devices.

13Going live

Before Google Pay works in production on your own site (SDK or widget), the integration must be approved for production in the Google Pay & Wallet Console. This is Google's "Publish your integration" step.

• Hosted redirect: no production access needed on your side. The hosted page runs on OneGate's already-published domain.
• SDK & widget: send OneGate your production and staging domains. OneGate registers each and submits the integration through "Publish your integration" under its registered merchant profile (BCR2DN6D3L72TUDX). Once approved, Google Pay renders in production on your domains.

14Brand and UX compliance

OneGate's Google Pay™ integrations follow Google's published brand and user experience guidelines. On the hosted redirect the button and payment flow are rendered by OneGate, so these hold automatically. On the SDK and the widget the button is rendered by our code on your page, and the surrounding layout is yours.

How the button is rendered

• Buttons are produced by the Google Pay API's own createButton() on all three paths. Where you customise the button, the SDK passes your choices through Google's published ButtonOptions, so the asset rendered is always one of Google's own. No hand-built button is used anywhere.
• isReadyToPay() runs before the button is rendered, so it only appears on a device and browser that can complete the payment.
• The payment sheet opens from the button's own click handler, so it is always a response to a user gesture.
• Loading, success and error states are surfaced through the SDK callbacks (onReady, onSuccess, onError, onCancel) so the customer is told what happened.

What stays with you

• Place the Google Pay™ button prominently among your payment options. You can change its type, colour, size mode, locale and corner radius through the SDK's button appearance options, which go through Google's own ButtonOptions. Do not restyle the rendered button with CSS, rebuild it yourself, or cover any part of it.
• Serve your checkout over HTTPS. It is required by Google Pay and by OneGate.
• Register the domains the button renders on, so Google approves them (see Going live).

15Resources & support

Merchants using the SDK or widget integrate Google Pay directly on their own site and must follow Google's official web resources, including approved button assets from the brand guidelines.

OneGate support

For integration help, contact support@onegate.co.za or call 087 550 6850. For Google Pay onboarding queries, reach out to Louis Germishuys at louis@onegate.co.za.