Google Pay ödeme işleyici spesifikasyonu

İşleyici Adı: com.google.pay
Sürüm: 2026-01-11

1. Giriş

com.google.pay işleyici, işletmelerin UCP uyumlu platformlar üzerinden hızlandırılmış ödeme seçeneği olarak Google Pay'i sunmasını sağlar. Google Pay API'si, kullanıcılara Google Hesaplarında saklanan ödeme yöntemlerine erişim vererek hızlı ödeme yapılmasını sağlar.

Bu işleyici, işletmelerin Google Pay yapılandırmalarını (ör. izin verilen kart ağları ve ağ geçidi parametreleri) sağladığı ve platformların güvenli bir ödeme jetonu oluşturmak için Google Pay API ile istemci tarafı etkileşimini yönettiği bir başsız entegrasyon modelini etkinleştirir.

1.1 Temel Avantajlar

Evrensel Yapılandırma: İşletmeler, Google Pay'i standart JSON kullanarak bir kez yapılandırır. Bu sayede, yetkili tüm platformlar ödeme arayüzünü özel ön uç kodu olmadan oluşturabilir.
Ayrılmış Ön Uç: Platformlar, Google Pay JavaScript API veya SDK entegrasyonunun karmaşıklığını yönetirken işletmeler de sonuçta ortaya çıkan jetonu kullanır.
Güvenli belirteç oluşturma: Şifrelenmiş kimlik bilgilerini doğrudan işletmenin ödeme hizmeti sağlayıcısına (PSP) iletmek için Google'ın yerleşik belirteç oluşturma özelliğinden yararlanır.

2. İş Entegrasyonu

2.1 Şartlar

İşletmeler, Google Pay'in UCP üzerinden reklamını yapmadan önce şunları yapmalıdır:

Google Pay satıcı kimliği edinme: PRODUCTION ortamında işleme için gereklidir (Google Pay ve Cüzdan Konsolu'na kaydolun).
PSP desteğini doğrulayın: Ödeme hizmeti sağlayıcınızın (PSP) Google Pay jetonlaştırma için desteklenen işlemciler ve ağ geçitleri listesinde olduğundan emin olun.

2.2 İşleyici Yapılandırması

İşletmeler, ödeme işleyicileri dizisine işleyiciyi ekleyerek Google Pay desteğinin reklamını yapar. Yapılandırma, Google Pay API'yi başlatmak için gereken yapıya kesinlikle uygundur.

2.2.1 Yapılandırma Şeması

Yapılandırma nesnesi; ortamı, işletme kimliğini ve izin verilen ödeme yöntemlerini tanımlar.

Google Pay Ödeme Yöntemi

Google Pay'in PaymentMethod özelliğine göre.

Jetonlaştırma Spesifikasyonu

Google Pay'in TokenizationSpecification'ına göre.

2.2.2 Örnek işleyici bildirimi

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 Varlıklar

2.3.1 Enstrüman Şeması

Google Pay aracı (card_payment_instrument), temel Kart Ödeme Aracı'nı genişletir. Tutarlı bir makbuz oluşturma işlemi sağlamak için standart görüntüleme alanlarını (ör. brand ve last_digits) devralır. Aynı zamanda, belirli Google Pay jetonlaştırma yükünü taşımak için credential alanını hassaslaştırır.

Platform Davranışı: Platform, Google Pay PaymentMethodData yanıtını işletmeye göndermeden önce bu yapıya eşlemekten sorumludur.

Ad	Tür	Zorunlu	Açıklama
id	dize	Evet	Platform tarafından atanan, bu ödeme aracı için benzersiz bir tanımlayıcı.
handler_id	dize	Evet	Google Pay işleyicisinin tanımlayıcısı.
tür	dize	Evet	Sabit = `card`. Bu ödeme aracının kart gibi davrandığını (kart görüntüleme alanlarını devraldığını) gösterir.
marka	dize	Evet	Kart ağı (ör. `visa`, `mastercard`). Google Pay'in `info.cardNetwork` özelliğinden eşlenir.
last_digits	dize	Evet	Kartın son 4 hanesi. Google Pay'in `info.cardDetails` hizmetinden eşlenir.
rich_text_description	dize	Hayır	Kartın isteğe bağlı zengin metin açıklaması (ör. Visa ending in 1234, expires 12/2025").
rich_card_art	dize (uri)	Hayır	Kartı temsil eden zengin bir resmin isteğe bağlı URI'si (ör. kartı veren kuruluşun kart tasarımı).
billing_address	Posta Adresi	Hayır	Kartla ilişkili fatura adresi.
yeterlilik belgesi	Kimlik bilgisi yükü	Hayır	Google Pay tarafından döndürülen güvenli jeton oluşturma verileri.

Kimlik bilgisi yükü

Bu nesne, enstrümanın credential olarak işlev görür. Doğrudan Google Pay Jetonlu Ödeme Verileri ile eşlenir.

Posta Adresi

Bu nesne, address alanı olarak kullanılır. Doğrudan PostalAddress ile eşlenir.

3. Platform Entegrasyonu

3.1 Şartlar

Platformlar, com.google.pay ödemelerini işlemeden önce şunları yapmalıdır:

Web için Google Pay API'yi (veya Android'deki eşdeğerini) yükleyebilmelidir.
Ödeme düğmesini oluştururken Google Pay Marka Kuralları'na uyun.

3.2 Ödeme Protokolü

Platformlar, herkese açık kullanıcı adını işlemek için BU AKIŞI izlemelidir:

1. adım: Keşfedin ve yapılandırın

Platform, API yaşam döngüsünü yönetmek için istemciyi başlatır.

Referans: PaymentsClient

2. adım: Ödeme yapmaya hazır olup olmadığınızı kontrol edin

Platform, düğmeyi göstermeden önce kullanıcının belirtilen ödeme yöntemleriyle ödeme yapma olanağına sahip olup olmadığını kontrol eder.

Referans: isReadyToPay

3. adım: Ödeme isteği oluşturun

Platform, satıcı yapılandırması, ödeme yöntemleri ve işlem ayrıntıları (fiyat ve para birimi) dahil olmak üzere ödeme verileri isteği nesnesini oluşturur.

Referans: PaymentDataRequest

4. adım: Kullanıcı etkileşimini çağırın

Kullanıcı ödeme düğmesiyle etkileşimde bulunduğunda platform, ödeme sayfası görünümünü tetikler.

Referans: loadPaymentData

5. adım: Ödeme işlemini tamamlayın

Kullanıcı etkileşimi başarılı olduğunda Google Pay API, payment_data anahtarı altında bir PaymentInstrument nesnesi döndürür. Platform, bu yanıtı card_payment_instrument şemasıyla eşler ve ödeme işleminin tamamlanması isteğini gönderir.

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "last_digits": "4242",
    "billing_address": {
      "street_address": "123 Main Street",
      "extended_address": "Suite 400",
      "address_locality": "Charleston",
      "address_region": "SC",
      "postal_code": "29401",
      "address_country": "US",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. İşletme İşleme

Google Pay ödeme aracı aldıktan sonra işletmeler ŞUNLARI YAPMALIDIR:

Validate Handler: handler_id öğesinin Google Pay işleyiciyle eşleştiğini doğrulayın.
Jetonu Ayıklama: Jeton dizesini payment_data.credential.token konumundan alın.
Ödemeyi İşleme: Jeton dizesini ve işlem ayrıntılarını PSP'nin uç noktasına iletin.
- Not: Çoğu PSP'de "Google Pay Yükü" veya "Ağ Jetonu" için özel bir alan bulunur.
Yanıt Döndürme: Sonlandırılmış ödeme durumuyla (Başarılı/Başarısız) yanıt verin.

5. Güvenlikle İlgili Dikkat Edilmesi Gereken Noktalar

5.1 Jeton Güvenliği

PAYMENT_GATEWAY: Bu jetonlaştırma türü kullanılırken jeton, jetonlaştırma tarafı için özel olarak şifrelenir. Aracı taraf bu jetonun şifresini çözemez ve jetonu jetonlaştırma tarafına olduğu gibi iletmelidir.
DOĞRUDAN: DIRECT belirteçleştirme kullanılıyorsa işletme, şifresini çözmesi gereken şifrelenmiş kart verileri alır. Bu durum, PCI DSS uygunluk kapsamını önemli ölçüde artırır ve işletme 1. Düzey PCI Uyumlu Servis Sağlayıcı olmadığı sürece genellikle önerilmez.

5.2 Ortam Yalıtımı

TEST Modu: TEST ortamında Google Pay, sahte jetonlar döndürür. Bunlar için ödeme alınamaz.
ÜRETİM Modu: Gerçek kartlar kullanılır. İşletmeler, config.allowed_payment_methods içindeki ÖHP kimlik bilgilerinin ortamla eşleştiğinden emin olmalıdır.

Yerleştirilmiş ödeme (isteğe bağlı)

Kimlik bağlama (isteğe bağlı)

Google Pay ödeme işleyici spesifikasyonu Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.