Yerleşik ödeme

Yerleşik ödeme entegrasyonu, web tabanlı ödeme işleminizin Google platformlarına yerleştirilmesini sağlar. Ürününüz, Native API'nin destekleyemediği karmaşık bir mantık (ör. özelleştirmeler) gerektiriyorsa bu yolu kullanın. Ödeme akışına bir iFrame aracılığıyla yerleştirilecek bir ödeme kullanıcı arayüzü uygulayacaksınız.

Yerleştirilmiş ödeme nedir?

Yerleştirilmiş ödeme (EC), bir barındırıcının (ör. Google Arama veya bir yapay zeka ajanı) mevcut web tabanlı ödeme işleminizi kendi uygulaması içinde (iFrame veya web görünümü kullanarak) göstermesine olanak tanır. Standart bir web yönlendirmesinin aksine, bu yöntem çift yönlü iletişime olanak tanır. Düzenleyen, kayıtlı bir adresi seçme veya kayıtlı bir kimlik bilgisiyle ödeme yapma gibi belirli görevleri "devredebilir". Böylece, daha hızlı ve doğal bir deneyim sunulurken siz de kayıtlı satıcı olarak kalır ve gerçek sipariş oluşturma işlemini gerçekleştirirsiniz.

Satıcı uygulama kontrol listesi

Yerleştirilmiş ödeme özelliğini desteklemek için UCP API'niz ve ön uç ödeme uygulamanızda aşağıdaki şartları uygulamanız gerekir.

1. Keşfetme özelliğini etkinleştirme (UCP API)

Ödeme işleminizin, UCP API yanıtlarınızda yerleştirilmiş uzantıyı desteklediğini beyan etmeniz gerekir.

• İşlem: dev.ucp.shopping.embedded_checkout yetenek nesnesini UCP yanıt yetenekleri dizinize ekleyin.
• Koşul: Spesifikasyon ve şema URL'lerini ekleyin.
• İsteğe bağlı: Ödeme sayfasının yüklenmesi için kimlik doğrulaması (ör. JWT jetonu) gerekiyorsa auth.required değerini true olarak ayarlayın.

"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. Herkese açık kullanıcı adı URL'si başlatma (ön uç)

Barındırıcı, continue_url öğenizi yüklediğinde belirli sorgu parametreleri ekler. Ön uçunuz, yükleme sırasında bunları hemen ayrıştırmalıdır.

• İşlem: Aşağıdaki URL sorgu parametrelerini ayrıştırın:
  • ec_version: Protokol sürümü (ör. 2026-01-11).
  • ec_auth: (Geçerliyse) auth.required: true ayarını yaparsanız ana makine tarafından sağlanan kimlik doğrulama jetonunu doğrulayın.
  • ec_delegate: Ana makinenin yerel olarak işlemek istediği işlemlerin virgülle ayrılmış listesi (ör. payment.credential, fulfillment.address_change, payment.instruments_change).

3. İletişim kurma (ön uç)

İletişim, JSON-RPC 2.0 biçimi kullanılarak postMessage üzerinden gerçekleşir.

• İşlem: message etkinlikleri için bir işleyici uygulayın.
• Koşul: Her iletinin kaynağını doğrulayarak ana makineyle eşleştiğinden emin olmanız gerekir.
• Yerel destek: Yerel uygulama ana makineleri için, yerleştirilmiş genel değişkenleri (ör. window.EmbeddedCheckoutProtocolConsumer) postMessage kullanılamıyorsa.

4. El sıkışma işlemini gerçekleştirme (ön uç)

Ödeme sayfanız oluşturulur oluşturulmaz barındırıcıya hazır olduğunuzu söylemeli ve hangi yetkileri kabul ettiğinizi onaylamalısınız.

• İşlem: ec.ready isteğini yüklemeden hemen sonra gönderin.
• Yük: Ana makinenin işlemesine izin verdiğiniz özellikleri listeleyen bir delegate dizisi ekleyin.
• Örnek: İstenen URL ec_delegate=payment.credential ise ve kabul ediyorsanız "payment.credential" öğesini ec.ready yüküne ekleyin.

// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5. Yetki mantığını uygulama (ön uç)

El sıkışma sırasında bir temsilci atamayı kabul ettiyseniz çakışmaları önlemek için kullanıcı arayüzü davranışınızı değiştirmeniz gerekir.

• İşlem: Temsil edilen görevlerle ilgili kullanıcı arayüzü öğelerini gizleyin.
• Örnek: fulfillment.address_change yetkilendirilmişse adres formunuzu gizleyin ve bunun yerine "Adresi Değiştir" düğmesi gösterin.
• İşlem: Kullanıcı bu düğmeyi tıkladığında _request mesajı gönderin (ör. ec.fulfillment.address_change_request) ev sahibine.
• İşlem: Düzenleyenin yanıtını bekleyin. Yanıtta yeni veriler (ör. seçilen adres) yer alır.
• Şart: Ödeme durumunuzu, ana makine tarafından döndürülen verilere göre PUT tarzı bir değiştirme işlemi kullanarak güncelleyin (nesnenin tamamını değiştirin).

// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. Yaşam döngüsü ve durum güncellemeleri gönderme (ön uç)

Ödeme durumu hakkında ev sahibini bilgilendirmeniz gerekir. Böylece ev sahibi kullanıcı arayüzünü güncelleyebilir veya hataları giderebilir.

• İşlem: Durum değiştiğinde bildirim gönderin (kimliksiz mesajlar):
  • ec.start: Ödeme sayfasının tamamı göründüğünde
  • ec.line_items.change: Sepet içeriği veya toplamları güncellenirse.
  • ec.buyer.change: Alıcı bilgileri güncellenirse.
  • ec.complete: Sipariş başarıyla verildiğinde.
  • ec.error: Önemli bir hata oluşursa.

7. Güvenliği zorunlu kılma (sunucu/başlıklar)

Ödeme sayfanızın kötü niyetli kişiler tarafından yerleştirilemediğinden emin olmanız gerekir.

• İşlem: İçerik Güvenliği Politikası (İGP) üstbilgilerini uygulayın.
• Şart: Yalnızca güvenilir ana makinelerin yerleştirmesine izin vermek için frame-ancestors <host_origin>; seçeneğini ayarlayın.
• Gezinme: Kullanıcıyı ödeme akışından uzaklaştıran mantığı engelleyin (ör. ana sayfanıza yönlendiren "Alışverişe Devam Et" bağlantılarını kaldırın). 3DS doğrulama veya üçüncü taraf ödeme yönlendirmeleri için istisnalara izin verilir.