MSolution Docs / Google Pay™

Google Pay™ Web SDK documentation

Set up Google Pay through the MSolution Gateway with configuration, tokenization, button rendering, and production go-live guidance.

SDK file Google Pay Guide

GatewayMSolution

EnvironmentsTEST / PRODUCTION

TokenECv2

Introduction

The MSolution Google Pay integration creates a session on your backend, accepts the Google Pay token in the browser, and routes it to the gateway.

Flow

A session is created, the token is collected, the gateway routes it for processing, and the result comes back as an event.

Use case

Designed for web checkout, payment pages, and merchant checkout flows.

Sequence

Load the scripts, set the button attributes, apply setConfig, connect the createSession backend, then handle the payment-success and payment-error events.

Compliance Requirements

You must comply with Google Pay policies, branding rules, and merchant obligations.

Web resources

Brand guidelines Integration checklist AUP Seller Terms

Android resources

Android docs Android checklist Android brand guidelines

Merchants must accept the Google Pay Acceptable Use Policy and Google Pay API Terms of Service, and they must use official Google Pay button and logo assets without modification.

Supported Platforms and Environments

The primary focus of this guide is the web SDK; official Android reference links are listed above.

Platform

The MSolution Google Pay Web SDK and custom element are the primary integration path.

TEST

Sandbox behavior, demo results, and issuer variance are expected.

PRODUCTION

Requires an approved domain, production gatewayMerchantId, and a live backend.

Prerequisites

Complete the following setup before you start integration.

MSolution onboarding must be completed and a gatewayMerchantId must be issued.
The merchant backend must expose a createSession endpoint.
Amounts must be calculated on the backend and never trusted from the client.
Google Pay domain verification and allow-listing must be completed.

Google Pay Configuration

This section defines the required config parameters and the 3DS enablement rule.

Configuration sample

// The MSolution SDK builds this Google Pay request structure internally.
const baseRequest = { apiVersion: 2, apiVersionMinor: 0 };
const googleEnvironment = "TEST";     // Google Pay UI (TEST | PRODUCTION)
const processEnvironment = "TEST";    // MSolution gateway (TEST | PRODUCTION)

const tokenizationSpecification = {
  type: "PAYMENT_GATEWAY",
  parameters: {
    gateway: "msolution",
    gatewayMerchantId: "MSOL_12345"
  }
};

const allowedCardNetworks = ["MASTERCARD", "VISA"];
const allowedAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];
const billingAddressParameters = {
  format: "FULL",
  phoneNumberRequired: false
};

const cardPaymentMethod = {
  type: "CARD",
  parameters: {
    allowedAuthMethods,
    allowedCardNetworks,
    billingAddressRequired: false,
    // If your checkout requires a billing address, use:
    // billingAddressRequired: true,
    // billingAddressParameters
  },
  tokenizationSpecification
};

// Merchants do not pass baseRequest or cardPaymentMethod directly
// into btn.setConfig(). The SDK builds them internally.

SDK integration mapping

The baseRequest, tokenizationSpecification, and cardPaymentMethod objects in Section 05 describe how the MSolution SDK builds the Google Pay request internally.
Merchants do not pass these objects directly into btn.setConfig; the SDK generates them internally from googleEnvironment, processEnvironment, gateway, and gatewayMerchantId.
Inside the SDK, baseRequest defines the Google Pay API version and cardPaymentMethod combines allowedAuthMethods, allowedCardNetworks, and tokenizationSpecification into the Google Pay request.
Inside the SDK, allowedCardNetworks are applied as MASTERCARD and VISA, and allowedAuthMethods are applied as PAN_ONLY and CRYPTOGRAM_3DS.

3DS enablement

Keep both PAN_ONLY and CRYPTOGRAM_3DS in allowedAuthMethods.
No extra 3DS flag is required in createSession or setConfig.
For PAN_ONLY transactions, 3DS is enforced automatically on the gateway side.

Billing address

In the MSolution gateway integration, the billing address is not required by default; if your checkout flow does not need it, billingAddressRequired can remain false.
If you need to collect a billing address, set billingAddressRequired to true and pass billingAddressParameters.
The recommended configuration uses format FULL and phoneNumberRequired false; enable the phone number only if your business or compliance rules require it.

Tokenization via MSolution Gateway

The session response, publicKey, and signature are used by the browser for Google Pay tokenization.

Session request payload

const sessionPayload = {
  redirectUrl: "https://your-domain.com/callback",
  callBackUrl: "https://your-domain.com/webhooks/google-pay",
  terminalId: "50100105",
  paymentType: "DEBIT",
  email: "customer@example.com",
  currency: "944",
  desc: "Google Pay payment",
  orderId: generateOrderId(),
  amount: Number(amount)
};

Session response shape

{
  "sessionId": "string",
  "signature": "string",
  "publicKey": "string",
  "amount": "12.50",
  "transactionId": "optional",
  "redirectLink": "optional",
  "receiptUrl": "optional"
}

In gateway mode, the merchant does not manually provide the publicKey; it arrives in the createSession response and the SDK uses it for tokenization.

The createSession backend typically builds the MSolution session using redirectUrl, callBackUrl, terminalId, paymentType, email, numeric currency, desc, orderId, and amount. In the demo flow this call can be made directly from the browser, but in production the credentials must stay on the backend.

Rendering the Google Pay Button

The button rendering flow is broken into steps so developers can follow the integration cleanly.

Load scripts

Add Google Pay JS and the MSolution SDK to the page.

Scripts

<script async src="https://pay.google.com/gp/p/js/pay.js"></script>
<script async src="https://sdk.msolution.az/google/v1.0/msolution-google-pay-sdk.js"></script>

Both scripts are required: the first loads the Google Payments API, and the second enables the <msolution-googlepay-button> custom element and the gateway flow.

Button component

Render the custom element and set the environment attributes.

Button markup

<script async src="https://pay.google.com/gp/p/js/pay.js"></script>
<script async src="https://sdk.msolution.az/google/v1.0/msolution-google-pay-sdk.js"></script>

<msolution-googlepay-button
  id="gpay-btn"
  google-environment="TEST"
  process-environment="TEST"
  button-color="black"
  button-type="pay"
  button-size-mode="fill"
  locale="en"
></msolution-googlepay-button>

Apply setConfig

Provide the dynamic payment config and the gateway mapping here.

How Section 05 is applied here

googleEnvironment sets the environment for Google PaymentsClient, while processEnvironment determines which MSolution backend endpoint receives the token.
The gateway and gatewayMerchantId values map to tokenizationSpecification.parameters inside the SDK.
baseRequest and cardPaymentMethod are not passed directly by the merchant; the SDK builds them internally using the structure shown in Section 05 and injects them into the Google Pay request.
allowedCardNetworks and allowedAuthMethods are not passed separately by the merchant; SDK v1.0 applies them internally as MASTERCARD, VISA and PAN_ONLY, CRYPTOGRAM_3DS.
If billing address collection is required, that part of the Google Pay request is also enabled in the SDK's internal request structure; the merchant only decides whether checkout requires it.

The Google Pay request structure shown in Section 05 is not passed directly by the merchant. The SDK builds that request internally from the gateway, gatewayMerchantId, googleEnvironment, and processEnvironment values shown in the setConfig example below.

Runtime config

const btn = document.getElementById("gpay-btn");

document.addEventListener("msolution-googlepay-ready", () => {
  btn.setConfig({
    // The SDK converts these values into the internal Google Pay
    // request structure shown in Section 05.
    getAmount: () => 12.5,
    currency: "AZN",
    country: "AZ",
    label: "Order #1024",
    merchantName: "Your Brand",
    googleEnvironment: "TEST",
    processEnvironment: "TEST",
    gateway: "msolution",
    gatewayMerchantId: "MSOL_12345",
    createSession
  });
});

Connect createSession backend

The SDK calls createSession and expects sessionId, signature, and publicKey from the backend.

SESSION_ENDPOINT is the merchant's own backend endpoint. That endpoint creates the MSolution session and must return sessionId, signature, and publicKey.

createSession function

const SESSION_ENDPOINT = "/api/payments/google/session"; // your backend endpoint

async function createSession({
  amount,
  currency,
  country,
  googleEnvironment,
  processEnvironment
}) {
  const res = await fetch(SESSION_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      amount,
      currency,
      country,
      googleEnvironment,
      processEnvironment
    })
  });

  if (!res.ok) throw new Error("Session failed");
  return res.json(); // { sessionId, signature, publicKey, ... }
}

Processing the Payment Token

The Google Pay token is posted to the gateway together with sessionId and signature; results are handled through events.

Gateway request

POST https://pay.msolution.az/eComIntegration/api/v1/google-pay/process-wallet-payment
Content-Type: application/json

{
  "sessionId": "<sessionId returned by createSession>",
  "signature": "<signature returned by createSession>",
  "data": { /* Google Pay token object (ECv2) */ }
}

The sessionId and signature come from the createSession backend response and must be passed to the gateway unchanged. The SDK collects the Google Pay token in the browser and sends that ECv2 object to the MSolution gateway together with those values.

After this step, the main integration sequence is to handle payment-start, payment-success, and payment-error events. On success you can use redirectLink or receiptUrl; when the user cancels, the isUserAction flag should be respected.

Event handling

document.addEventListener("payment-success", (e) => {
  const { redirectLink, receiptUrl } = e.detail || {};
  if (redirectLink) window.location = redirectLink;
  if (receiptUrl) window.open(receiptUrl, "_blank");
});

document.addEventListener("payment-error", (e) => {
  const { error, isUserAction } = e.detail || {};
  if (isUserAction) return;
  alert(error || "Payment error");
});

Test Environment

The TEST environment does not fully mirror live issuer behavior; it is mainly for validation and initial checks.

Some issuers may not complete auth and may return demo results.
isReadyToPay can vary by device and Google account state.
Keep both environment values in TEST while validating.

Production Go-Live

Both Google and MSolution requirements must be completed before going live.

The production domain must be verified and allow-listed.
Use the production gatewayMerchantId and the production backend endpoint.
Switch googleEnvironment and processEnvironment to PRODUCTION.
Validate the signed release flow and real callback/redirect URLs.

Error Handling

Gateway responses include stable error codes and should map cleanly to user-facing behavior.

Error response

{
  "success": false,
  "code": "TOKEN_MERCHANT_MISMATCH",
  "message": "gatewayMerchantId does not match token merchant",
  "retryable": false
}

TOKEN_MERCHANT_MISMATCH: The gatewayMerchantId is incorrect or the wrong environment is being used.
INVALID_SIGNATURE: The backend session signature was not generated correctly.
SESSION_EXPIRED: The expired session must be recreated.

Troubleshooting

Check these items first when debugging a failing integration.

Button

If the button is missing, verify pay.js, the SDK, and the isReadyToPay result.

Session

If the session fails, verify the backend endpoint, auth, and response shape.

Environment

Mixing TEST and PRODUCTION values will typically cause a gatewayMerchantId mismatch.

FAQ

The questions asked most often during integration.

Does the merchant provide the publicKey in gateway integration?

No. publicKey is returned by MSolution as part of the createSession backend response.

Do I need to pass an extra 3DS flag for PAN_ONLY?

No. Keep PAN_ONLY in allowedAuthMethods; 3DS is enforced automatically on the gateway side.

Are there separate docs for Android?

Yes. This page includes Android docs, Android checklist, and Android brand guideline links.

Should I expect a real successful auth in TEST?

Not always. Issuer behavior can vary in TEST and demo responses are possible.

Support Contact

Use the following channel for onboarding, go-live, and production activation support.

Technical support

support@msolution.az

Send screenshots and environment details for production gatewayMerchantId issuance, domain approval, and test result review.