MSolution Logo

MSolution Docs / Google Pay™

Google Pay™ Web SDK dokumentasiyası

MSolution Gateway üzərindən Google Pay inteqrasiyasını konfiqurasiya, tokenization, button render və production go-live addımları ilə qurun.

GatewayMSolution
MühitlərTEST / PRODUCTION
TokenECv2
01

Introduction

MSolution Google Pay inteqrasiyası merchant backend üzərindən session yaradır, browser-də Google Pay tokenini qəbul edir və tokeni gateway-ə yönləndirir.

Axın

Session yaradilir, token toplanir, gateway prosessinqə göndərir, nəticə event kimi qayıdır.

Use case

Web checkout, payment pages və merchant checkout axınları üçün nəzərdə tutulub.

Ardıcıllıq

Skriptləri qoşun, button atributlarını verin, setConfig tətbiq edin, createSession backend-i bağlayın, sonra payment-success və payment-error event-lərini emal edin.

02

Compliance Requirements

Google Pay siyasətlərinə, brand qaydalarına və merchant öhdəliklərinə riayət etmək məcburidir.

Merchant-lar Google Pay Acceptable Use Policy və Google Pay API Terms of Service sənədlərini qəbul etməli, rəsmi Google Pay button və loqo asset-lərindən dəyişiklik etmədən istifadə etməlidir.
03

Supported Platforms and Environments

Bu sənədin əsas fokusunda web SDK var; Android üçün rəsmi reference linkləri yuxarıda verilib.

Platforma

MSolution Google Pay Web SDK və custom element əsas axın üçün nəzərdə tutulur.

TEST

Sandbox davranışı, demo nəticələr və issuer fərqləri mümkündür.

PRODUCTION

Təsdiqlənmiş domain, production gatewayMerchantId və live backend tələb olunur.

04

Prerequisites

İnteqrasiyaya başlamazdan əvvəl aşağıdakı hazırlıq tamamlanmalıdır.

  • MSolution onboarding tamamlanmalı və gatewayMerchantId təqdim olunmalıdır.
  • Merchant backend createSession endpoint-i hazırlamalıdır.
  • Məbləğ backend-də hesablanmalı və client-ə etibar edilməməlidir.
  • Google Pay üçün domain təsdiqi və allow-list prosesi tamamlanmalıdır.
05

Google Pay Configuration

Required config parametrləri və 3DS enablement qaydası burada müəyyən olunur.

Konfiqurasiya nümunəsi
// 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

  • Section 05-də göstərilən baseRequest, tokenizationSpecification və cardPaymentMethod obyektləri MSolution SDK-nın Google Pay request-i daxildə necə qurduğunu göstərir.
  • Merchant bu obyektləri btn.setConfig daxilində birbaşa ötürmür; SDK onları googleEnvironment, processEnvironment, gateway və gatewayMerchantId əsasında daxildə generasiya edir.
  • baseRequest SDK daxilində Google Pay API versiyasını müəyyən edir, cardPaymentMethod isə allowedAuthMethods, allowedCardNetworks və tokenizationSpecification hissələrini birləşdirərək Google Pay request-ə əlavə olunur.
  • SDK daxilində allowedCardNetworks dəyərləri MASTERCARD və VISA, allowedAuthMethods dəyərləri isə PAN_ONLY və CRYPTOGRAM_3DS olaraq tətbiq olunur.

3DS enablement

  • PAN_ONLY və CRYPTOGRAM_3DS allowedAuthMethods daxilində qalmalıdır.
  • Əlavə 3DS flag createSession və ya setConfig daxilində tələb olunmur.
  • PAN_ONLY əməliyyatlarında 3DS gateway tərəfində avtomatik tətbiq edilir.

Billing address

  • MSolution gateway inteqrasiyasında billing address default olaraq məcburi deyil; əgər checkout axınınız bu məlumatı tələb etmirsə, billingAddressRequired false qala bilər.
  • Billing address toplamaq lazımdırsa, billingAddressRequired true edilməli və billingAddressParameters ötürülməlidir.
  • Tövsiyə olunan konfiqurasiya format FULL və phoneNumberRequired false-dir; telefon nömrəsi yalnız biznes və ya compliance qaydalarınız tələb edərsə aktiv edilməlidir.
06

Tokenization via MSolution Gateway

Session cavabı, publicKey və signature browser tərəfdə Google Pay tokenization üçün istifadə olunur.

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"
}

Gateway mode-da publicKey merchant tərəfindən əl ilə verilməz; createSession response daxilində gəlir və SDK bu dəyəri tokenization üçün istifadə edir.

createSession backend-i adətən redirectUrl, callBackUrl, terminalId, paymentType, email, numeric currency, desc, orderId və amount dəyərlərini istifadə edərək MSolution session yaradır. Demo ssenaridə bu çağırış birbaşa browser-dən edilə bilər, amma production-da credential-lar backend-də saxlanmalıdır.

07

Rendering the Google Pay Button

Button render prosesi addım-addım qurulmalıdır ki, developer inteqrasiyanı rahat izləsin.

1

Skriptləri qoşun

Google Pay JS və MSolution SDK səhifəyə əlavə olunur.

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>

Hər iki script məcburidir: birinci script Google Payments API-ni yükləyir, ikinci script isə <msolution-googlepay-button> custom element-ini və gateway axınını aktivləşdirir.

2

Button komponenti

Custom element render edilir və environment atributları təyin olunur.

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="az"
></msolution-googlepay-button>
3

setConfig tətbiq edin

Dynamic payment config və gateway mapping burada verilir.

How Section 05 is applied here

  • googleEnvironment Google PaymentsClient üçün environment dəyərini müəyyən edir, processEnvironment isə token-in hansı MSolution backend endpoint-ə göndəriləcəyini müəyyən edir.
  • gateway və gatewayMerchantId dəyərləri SDK daxilində tokenizationSpecification.parameters hissəsinə map olunur.
  • baseRequest və cardPaymentMethod merchant tərəfindən birbaşa ötürülmür; SDK onları Section 05-də göstərilən struktur ilə daxildə qurur və Google Pay request-ə əlavə edir.
  • allowedCardNetworks və allowedAuthMethods də merchant tərəfindən ayrıca ötürülmür; SDK v1.0 bu dəyərləri MASTERCARD, VISA və PAN_ONLY, CRYPTOGRAM_3DS olaraq sabit tətbiq edir.
  • Billing address toplamaq lazımdırsa, bu Google Pay request hissəsi də SDK-nın daxili request quruluşunda aktivləşdirilir; merchant yalnız checkout tələbinə uyğun parametrləri müəyyən edir.

Section 05-də göstərilən Google Pay request strukturu merchant tərəfindən birbaşa ötürülmür. Aşağıdakı setConfig nümunəsində verilən gateway, gatewayMerchantId, googleEnvironment və processEnvironment dəyərləri əsasında SDK həmin request-i daxildə qurur.

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
  });
});
4

createSession backend-i bağlayın

SDK createSession funksiyasını çağırır və backend-dən sessionId, signature və publicKey gözləyir.

SESSION_ENDPOINT merchant-in öz backend endpoint-idir. Bu endpoint MSolution session yaradır və response olaraq sessionId, signature və publicKey qaytarmalıdır.

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, ... }
}
08

Processing the Payment Token

Google Pay tokeni sessionId və signature ilə birlikdə gateway-ə göndərilir; nəticələr event-lərlə emal olunur.

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) */ }
}

sessionId və signature createSession backend cavabından gəlir və dəyişdirilmədən gateway-ə ötürülməlidir. SDK Google Pay tokenini browser-də toplayır və həmin dəyərlərlə birlikdə ECv2 obyektini MSolution gateway-ə göndərir.

Bu mərhələdən sonra əsas inteqrasiya ardıcıllığı payment-start, payment-success və payment-error event-lərini emal etməkdir. Uğurlu nəticədə redirectLink və ya receiptUrl istifadə oluna bilər; istifadəçi ləğv etdikdə isə isUserAction flag-i nəzərə alınmalıdır.

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");
});
09

Test Environment

TEST mühiti real issuer axınını tam imitasiya etmir; demək olar ki, validasiya və ilkin yoxlama üçündür.

  • Bəzi issuer-lər auth tamamlamaya bilər və demo nəticələr qaytara bilər.
  • isReadyToPay nəticəsi cihaz və Google hesabına görə dəyişə bilər.
  • TEST-də hər iki environment dəyərini TEST saxlamaq məsləhətdir.
10

Production Go-Live

Go-live mərhələsində həm Google, həm də MSolution tələbləri paralel tamamlanmalıdır.

  • Production domain təsdiqlənməli və allow-list-ə salınmalıdır.
  • Production gatewayMerchantId və production backend endpoint istifadə olunmalıdır.
  • googleEnvironment və processEnvironment dəyərləri PRODUCTION-a keçirilməlidir.
  • Signed release flow və real callback/redirect URL-lər yoxlanmalıdır.
11

Error Handling

Gateway cavablarında sabit error code-ları və istifadəçi-facing davranış aydın şəkildə idarə olunmalıdır.

Error response
{
  "success": false,
  "code": "TOKEN_MERCHANT_MISMATCH",
  "message": "gatewayMerchantId does not match token merchant",
  "retryable": false
}
  • TOKEN_MERCHANT_MISMATCH: gatewayMerchantId yanlışdır və ya səhv mühit istifadə olunur.
  • INVALID_SIGNATURE: Backend session imzası düzgün generasiya edilməyib.
  • SESSION_EXPIRED: Müddəti bitmiş session yenidən yaradılmalıdır.
12

Troubleshooting

Tez-tez rast gəlinən problemləri aşağıdakı qaydada yoxlayın.

Button

Button görünmürsə pay.js, SDK və isReadyToPay nəticəsini yoxlayın.

Session

Session alınmırsa backend endpoint, auth və response shape yoxlanmalıdır.

Environment

TEST/PRODUCTION qarışıbsa gatewayMerchantId mismatch alınacaq.

13

FAQ

İnteqrasiya zamanı ən çox verilən suallar.

Gateway inteqrasiyasında publicKey merchant tərəfindən verilir?

Xeyr. publicKey createSession backend cavabının bir hissəsi kimi MSolution tərəfindən qaytarılır.

PAN_ONLY üçün əlavə 3DS flag ötürülməlidir?

Xeyr. allowedAuthMethods daxilində PAN_ONLY saxlanılır və 3DS gateway tərəfində avtomatik tətbiq edilir.

Android üçün ayrıca sənədlər varmı?

Bəli. Bu səhifədə Android docs, Android checklist və Android brand guidelines linkləri ayrıca verilib.

TEST mühitində real uğurlu auth gözləməliyəm?

Həmişə yox. TEST mühitində issuer davranışı dəyişə bilər və demo cavablar mümkündür.

14

Support Contact

Onboarding, go-live və production aktivasiya üçün aşağıdakı kanal üzərindən əlaqə saxlayın.

Texniki dəstək

support@msolution.az

Production gatewayMerchantId, domain approval və test nəticələri üçün screenshot və environment məlumatlarını göndərin.

Rəqəmsal dünyaya keçidinizi MSolution ilə sürətləndirin

MSolution sizə ödənişlərinizi rahat, təhlükəsiz və sürətli şəkildə idarə etmək imkanı yaradır. Komandamız, biznesinizə uyğun fərdi yanaşmalarla həllər təqdim etməyə hər zaman hazırdır

icon