Genel Bakış
Google Standart Ödemeler, marketlerden (7-Eleven gibi) yapılan satın alma işlemleri gibi nakit tabanlı ödeme şekillerini destekler. Genel olarak, ürünler için ödeme yapmak isteyen kullanıcı ödeme entegratörü aracılığıyla bir referans numarası oluşturur. Kullanıcı daha sonra bu referans numarasını bir markete, kiosk'a veya bankaya yönlendirir ve referans numarasını öder.
|
|
|
Kavramlar ve terminoloji
Semboller ve Kongreler
Anahtar kelimeleri "ZORUNLU", "ZORUNLU OLMAMALIDIR", "Zorunlu", "SHALL", "YAPMAYIN," "ZORUNLU", "YAPMAYIN:" "ÖNERİLİR", "MAYIS," ve "OPTIONAL" (İsteğe bağlı) RFC 2119'da açıklandığı gibi yorumlanmalıdır.
Zaman damgaları
Tüm zaman damgaları, UTC saat diliminde Unix döneminden (1 Ocak 1970) itibaren milisaniye olarak gösterilir.
Örneğin:
- 23 Nisan 2019 20:23:25 GMT = 1556051005000 milisaniye
- 16 Ağustos 2018 12:28:35 GMT = 1534422515000 milisaniye
Miktarlar
Bu API'deki parasal değerler "mikro değerler" biri oldu. Mikro değerler, tamsayı tabanlı, sabit bir hassasiyet biçimidir. Parasal bir değeri mikro cinsinden göstermek için standart para birimi değerini 1.000.000 ile çarpın.
Örneğin:
- 1,23 TL = 1230.000 mikro ABD doları
- 0,01 TL = 10.000 mikro ABD doları
Aciliyet
Bu API içindeki tüm yöntem çağrıları idempotent davranışına sahip olmalıdır. Google, işlemlerin her iki tarafta da aynı durumda olmasını sağlamak için belirli aralıklarla istekleri yeniden dener. Entegratörler, başarıyla işlenmiş olan istekleri yeniden işlemeyi denememelidir. Bunun yerine, başarılı işleme için alınan yanıt bildirilmelidir. Tüm yöntemlerde requestId içeren bir ortak RequestHeader bulunur. Bu requestId, tüm çağrılar için idempotency anahtarıdır.
Terminal olmayan yanıtlar (HTTP 200 başarılı olmayan) dolaylı olarak işlenmemelidir. Dolayısıyla, daha önce 400 (hatalı istek/başarısız ön koşul) alan bir istek, ikinci kez çağrıldığında, dolaylı olarak 400 değerini döndürmemelidir. Bu durumda, isteğin yeniden değerlendirilmesi gerekir. Yeniden değerlendirme sırasında 400 kod döndürebilir veya başarıyla işlenebilir.
Yeterlilik hakkında daha fazla bilgi için bu ayrıntılı kılavuza bakın.
Entegratör
İşletmesi için Google'ın Ödeme Platformu'nu kullanan bir şirket. YouTube veya AdWords gibi dahili (birinci taraf) olabilir. Ayrıca, hizmetlerini Google'ın ekosistemiyle çalışacak şekilde entegre etmek isteyen harici (3. taraf) bir işletme de olabilir.
FOP
Ödeme Şekli. Bu, bir enstrümantan daha genel bir ifadedir. Visa, MasterCard ve PayPal FOP'tur.
Enstrüman
Belirli bir müşteri tarafından gerçekleştirilen belirli bir ödeme şekli. Örneğin, kullanıcının kredi kartı veya PayPal hesabı. Belirli bir müşteri için token atanmış bir ödeme şekli, sistemimizde güvenli bir şekilde depolanan bir müşteri ödeme şeklinin bir örneği olduğundan aynı zamanda bir araçtır.
Jeton
Google'ın sisteminde belirli bir kullanıcının ödeme yöntemini temsil eder. Satın alma işlemi için gereken tüm bilgileri içerdiğinden jeton da bir araçtır. Kullanıcının entegrasyon uzmanındaki hesap numarası gibi bilgiler de bu kapsamda yer alabilir.
Temel akışlar
Google, bu referans numaralarını oluşturmak ve ödemek için iki temel akıştan yararlanır:
- Referans Numarası Akışı Oluşturun.
- Referans Numarası Akışı.
Daha sonra, bu satın alma işlemlerinden kaynaklanan mutabakat ve ödeme havale akışı tarafından gerçekleştirilir.
Aşağıdaki diyagramda bu akışların her biri gösterilmiştir.
Nakit ödeme şekillerine genel bakış
İlk iki akış, sonraki bölümlerde daha ayrıntılı olarak açıklanmıştır. Bu akış hakkında daha fazla bilgi edinmek için Havale akışı sayfasını inceleyin.
Referans numarası oluştur
Referans numarası oluşturma akışının amacı, hem Google'ın hem de entegrasyon uzmanının bir satın alma işlemini tanımlamak için kullanabileceği bir tanımlayıcı (referans numarası) oluşturup değiştirmektir. Kullanıcı daha sonra bu referans numarasını bir markette, kiosk'ta veya bankada kullanarak satın alma işlemini tamamlayabilir. Bu tanımlayıcı, Google'ın isteği üzerine entegratör tarafından generateReferenceNumber yöntemi çağrılarak oluşturulur. Referans numarası oluşturma isteği, bir tutar ve işlem açıklamasını içerir.
Aşağıdaki şemada, referans numarasının nasıl oluşturulduğu ve talimatlarla müşteriye nasıl gönderildiği gösterilmektedir.
Referans numarası akışı oluşturma
Aşağıda, nesnelerin bir listesi ve bunların neleri temsil ettiği gösterilmiştir:
- Kullanıcı: Bu ödeme şeklini kullanarak ödeme yapmak isteyen kullanıcıdır.
- Google kullanıcı arayüzü: Bu, kullanıcının satın alma işlemini yaptığı arayüzdür. Web veya uygulama üzerinden de olabilir.
- Google sunucusu: Referans numarasının oluşturulmasını isteyen ve kullanıcı için ödeme talimatları oluşturan Google arka uç sunucusu.
- Ödeme Entegratörü Sunucusu: Ödeme ayrıntılarını takip eden ve referans numarasını oluşturan Ödeme Entegratörü'nün arka uç sunucusu.
Bu akış, bu nakit ödeme şeklini kullanmak isteyen kullanıcıyla başlar.
- Kullanıcı, referans numarası için istek gönderen Google kullanıcı arayüzüne erişir.
- Google kullanıcı arayüzü, Google sunucusuna bir referans numarası (
getReferenceNumber) gerektiğini belirten bir mesaj gönderir. - Google sunucusu, ödeme entegratörü sunucusundan bir referans numarası (
generateReferenceNumber) oluşturmasını ister. - Ödeme Entegratörü sunucusu, referans numarasını oluşturur ve Google sunucusuna gönderir.
- Google sunucusu, referans numarasıyla birlikte ödeme talimatları oluşturur. Ardından bu bilgileri Google kullanıcı arayüzüne gönderir.
- Google Kullanıcı Arayüzü, bu talimatları ve referans numarasını Kullanıcıya gönderir.
Referans numaralarıyla ilgili notlar
Referans numaraları yalnızca bir kez ödenebilir ve referans numarası iptali akışıyla iptal edilebilir. Ayrıca, referans numaraları alfanümerik olmalı ve birden fazla görüntüleme biçimini desteklemelidir.
Google'ın kullanıcı arayüzleri, referans numarasını görüntülemenin yanı sıra isteğe bağlı olarak referans numarasını Kod 128 biçiminde (barkod biçiminde) gösterebilir. Diğer barkod biçimleri istek üzerine desteklenebilir.
Ödeme referans numarası
Kullanıcı, ödemesini yapmak istediği satın alma işlemini tanımlamak için bir market, kiosk veya bankada bu referans numarasını kullanır. Entegrasyonu sağlayan kişi, ödeme yapmadan önce kullanıcıdan satın alma tutarını, tarihini ve işlem açıklamasını göstererek satın alma işlemiyle ilgili ödemeyi onaylamasını sağlamalıdır.
Kullanıcı ödeme yapmayı seçtikten sonra yalnızca bir kez ödeme yaparak eksiksiz ödeme yapmalıdır. Bu API, tek bir referans numarasıyla gereğinden fazla veya az ödemeleri desteklemez. Ayrıca, tek bir referans numarasına birden çok ödeme yapılması da desteklenmez.
Kullanıcı ödeme yaptıktan sonra entegrasyon uzmanı, bu referans numarasına referenceNumberPaidNotification yöntemiyle ödeme yapıldığını hemen Google'a bildirmelidir. Entegratör, kullanıcının fiziksel olarak ödeme yapmasının ardından saniyeler içinde bu yöntemi çağırarak kullanıcının mallarını hızlı bir şekilde teslim almasına olanak tanır. (Ağ kapalıysa bu çağrı, sıraya eklenebilir.)
Ödeme yapıldıktan sonra referans numarası ve tutar, T+2 günlerinde gönderilen havale ekstresine eklenecektir.
Aşağıda, bir referans numarasının ödemesini gösteren dizi diyagramı verilmiştir.
Ödeme referans numarası akışı
Diyagramdaki nesneler aşağıdakileri temsil eder:
- Kullanıcı: Bu ödeme şeklini kullanarak ödeme yapmak isteyen kullanıcıdır.
- Market: Belirtilen referans numarası ve talimatlar üzerinden kullanıcının ödeme yaptığı yerdir (ör. market).
- Ödeme Entegratörü Sunucusu: Ödeme ayrıntılarının kaydını tutan Ödeme Entegratörü'nün arka uç sunucusu.
- Google sunucusu: Referans numarasının oluşturulmasını isteyen ve kullanıcı için ödeme talimatları oluşturan Google arka uç sunucusu.
Bu akış, kendisine verilen talimatlara göre ödeme yapmak için bir markete giden kullanıcıyla başlar.
- Kullanıcı ödeme yapmak için bir Market'e gider.
- İşlem tamamlandıktan sonra market, ödeme entegrasyon uzmanını ödeme konusunda bilgilendirir.
- Ödeme Entegratörü Sunucusu, Market'e başarı mesajı gönderir.
- Market, kullanıcının işlemin başarılı olduğunu ve ürünlerin kısa süre içinde Kullanıcıya teslim edileceğini bildirir.
- Ödeme Entegratörü sunucusu, Google'ın sunucusuna referans numarası için ödeme yapıldığına (
referenceNumberPaidNotification) dair bir mesaj gönderir. Bu adım 4. adımı engellememelidir. - Google sunucusu, Ödeme Entegratörü Sunucusu'na işlemin başarılı olduğunu belirten bir mesaj verir.
Referans numarasını iptal et
Referans numaraları Google tarafından iptal edilebilir. Google bir referans numarasını iptal ederse cancelReferenceNumber yöntemi aranır. Bu çağrı başarılı bir şekilde iade edildikten sonra, söz konusu referans numarasının ödenmesi geçersiz olur ve entegrasyon uzmanının bu numara için ödemeyi reddetmesi gerekir. Bu görüşme başarılı olursa gelecekteki tüm referenceNumberPaidNotification çağrıları başarısız olacaktır.
Ödeme süreci zaten başladıysa (örneğin, kullanıcı referans numarasını bir kiosk'a girdiyse ancak henüz ödeme yapmadıysa) entegrasyon uzmanı, USER_ACTION_IN_PROGRESS ifadesini içeren ErrorResponse ile bir HTTP 423 yanıt kodu döndürmelidir.
Sıradaki: Havale akışı