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.
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.
Session yaradilir, token toplanir, gateway prosessinqə göndərir, nəticə event kimi qayıdır.
Web checkout, payment pages və merchant checkout axınları üçün nəzərdə tutulub.
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.
Compliance Requirements
Google Pay siyasətlərinə, brand qaydalarına və merchant öhdəliklərinə riayət etmək məcburidir.
Supported Platforms and Environments
Bu sənədin əsas fokusunda web SDK var; Android üçün rəsmi reference linkləri yuxarıda verilib.
MSolution Google Pay Web SDK və custom element əsas axın üçün nəzərdə tutulur.
Sandbox davranışı, demo nəticələr və issuer fərqləri mümkündür.
Təsdiqlənmiş domain, production gatewayMerchantId və live backend tələb olunur.
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.
Google Pay Configuration
Required config parametrləri və 3DS enablement qaydası burada müəyyən olunur.
// 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.
Tokenization via MSolution Gateway
Session cavabı, publicKey və signature browser tərəfdə Google Pay tokenization üçün istifadə olunur.
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)
};{
"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.
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.
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.
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
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.
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.
Error Handling
Gateway cavablarında sabit error code-ları və istifadəçi-facing davranış aydın şəkildə idarə olunmalıdır.
{
"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.
Troubleshooting
Tez-tez rast gəlinən problemləri aşağıdakı qaydada yoxlayın.
Button görünmürsə pay.js, SDK və isReadyToPay nəticəsini yoxlayın.
Session alınmırsa backend endpoint, auth və response shape yoxlanmalıdır.
TEST/PRODUCTION qarışıbsa gatewayMerchantId mismatch alınacaq.
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.
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.azProduction gatewayMerchantId, domain approval və test nəticələri üçün screenshot və environment məlumatlarını göndərin.
