Google Play Faturalandırma dışında para kazanmayla ilgili arka uç entegrasyonu kılavuzu

Google Play Geliştirici API'si artık alternatif bir faturalandırma veya harici teklifler sisteminden işlemleri raporlamak için ek işlevler içeriyor. Bu kılavuzda, alternatif faturalandırma veya harici teklif işlemlerini nasıl bildireceğiniz açıklanmaktadır.

Arka uçunuzdan uygulama içi satın alma işlemleri gerçekleştirmek için gerekli olabilecek birkaç bileşen vardır. Bunları oluşturmak için arka uç entegrasyonunuzu Google Play Developer API'yi yapılandırma bölümünde belirtildiği şekilde ayarlamanız gerekir. Alternatif faturalandırma veya harici fırsatlar API'lerine özel olmayan tüm geliştirici arka uç işlevleri için Google Play faturalandırma sistemi dokümanlarındaki talimatlar geçerlidir.

Yeni harici işlemleri Google Play'e bildirme

Ücretsiz deneme satın alma işlemlerinden kaynaklanan ücretsiz işlemler de dahil olmak üzere, desteklenen ülkelerde Google Play'in faturalandırma sisteminin dışında gerçekleşen işlemleri Externaltransactions APIs ile entegre edin. Alternatif faturalandırma veya harici teklif sistemlerindeki işlemler, yalnızca alternatif faturalandırma veya harici teklifler programlarında izin verildiği şekilde uygun kullanıcı ülkeleri için başlatılmalı ve bildirilmelidir. Aksi takdirde API çağrısı reddedilir. Bu durum, yeni satın alma işlemleri, yenilemeler, para ekleme, yükseltme, düşürme vb. tüm işlemler için geçerlidir.

Harici işlem raporlaması

Ödeme, alternatif faturalandırma veya harici teklif sistemi üzerinden yetkilendirildikten sonra harici bir işlemi bildirmek için Externaltransactions API numaralı telefonu arayın. Bu; başlangıç ödemeleri, yenilemeler, geri ödemeler ve diğerleri dahil olmak üzere tüm işlemler için geçerlidir. Tüm işlemlerin, işlemin gerçekleşmesinden sonraki 24 saat içinde bildirilmesi gerekir.

Her harici işlem, harici bir işlem kimliğiyle raporlanır. Tekrarlanan satın alma işlemlerinde (otomatik yenilenebilir abonelikler gibi) yinelenen satın alma işlemindeki ilk işlemle ilişkilendirilmiş harici işlem kimliğini, geri ödemeler dahil sonraki tüm işlemler için parametre olarak göndermeniz gerekir. Bu, söz konusu satın alma işlemine ilişkin işlem dizisini kaydeder. Ürün değiştiğinde (yükseltme veya düşürme gibi) veya yinelenen işlem iptal edildiğinde ya da süresi dolduğunda ve aynı ürün daha sonra tekrar satın alındığında satın alma işlemleri için yeni bir harici işlem kimliği gönderirsiniz. Bu harici işlem kimliğinin bir parçası olarak kimliği tanımlayabilecek bilgiler, özel veya gizli bilgiler eklememelisiniz.

Yeni bir satın alma işlemini bildirme

Alternatif faturalandırma veya harici teklifler sisteminde yapılan her yeni satın alma işlemi başarılı olduğunda Externaltransactions API'ye çağrı yapılması gerekir. Bu yeni satın alma işlemleri için arka ucunuzda sorgu parametresi olarak satın alma işlemiyle ilişkilendirilmiş benzersiz bir externalTransactionId sağlamanız gerekir. Bu externalTransactionId, aynı uygulamanın paket kimliği içinde tekrar kullanılamaz.

Uygulamanın UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener veya ExternalOfferReportingDetailsListener geri çağırmaları aracılığıyla aldığı externalTransactionToken, tek seferlik satın alımlar ve yinelenen bir satın alma işlemindeki ilk işlemler (abonelik gibi) için istek gövdesinin de bir parçası olarak gereklidir. Her iki durumda da bu, ilk işlem olarak adlandırılır. İlk işlemden sonra externalTransactionToken artık gerekli değildir ve yeni bir benzersiz externalTransactionId sağlayarak sonraki işlemleri (abonelik yenilemeleri gibi) raporlarsınız. Sonraki işlemleri bildirme hakkında daha fazla ayrıntı için Bir satın alma işlemi için sonraki işlemleri raporlama bölümüne bakın.

Örnek:

  1. Geliştirici, uygulamasında alternatif faturalandırmayı yapılandırır ve etkinleştirir.
  2. 1. kullanıcı, desteklenen bir ülke olan Güney Kore'de bulunuyor ve bir aylık ücretsiz deneme teklifiyle product1 alanını ayda 12.634,10 KRW karşılığında satın almaya çalışıyor.
  3. Uygulama, product1 için ProductDetails ve kullanıcının seçtiği fırsatla satın alma akışını başlatır.
  4. 1. Kullanıcı, geliştiricinin alternatif faturalandırma sistemini seçer.
  5. UserChoiceBillingListener, my_token değerini externalTransactionToken olarak alır.
  6. Ardından geliştirici, ilgili bilgileri arka uçlarına gönderir (externalTransactionToken değer ve satın alınan ürünler). Ardından alternatif faturalandırma sisteminde product1 için satın alma akışını başlatır. Bu işlemin geliştirici tarafında, işlemi Google Play'e bildirmek için kullanılan benzersiz bir işlem kimliği atanır: 123-456-789. Kullanıcı ücretsiz deneme alıyor olsa bile işlem kimliği gereklidir.
  7. Satın alma işlemi alternatif faturalandırma sisteminde gerçekleştikten sonra, geliştirici aşağıdaki istekle işlemi Google Play'e bildirir. Kullanıcıya bir ay ücretsiz kullanım hakkı sunulduğu için bu ücret, başlangıçta sıfır dolarlık işlem olarak raporlanır.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Verginin kullanıcının idari alanına (eyalet veya il gibi) bağlı olduğu, Hindistan'da ikamet eden bir kullanıcıyla işlem yapıyorsanız bu alanı userTaxAddress'in altına eklediğinizden emin olun. Geçerli yönetim alanları için API referans kılavuzundaki önceden tanımlanmış dize listesine bakın.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

Bir satın alma işlemi için sonraki işlemleri raporlama

Bazı durumlarda, aynı harici satın alma işlemiyle ilişkili birden fazla kullanıcı ödemesi vardır (ör. abonelik yenileme veya ön ödemeli plan ekleme). Sonraki işlemleri Externaltransactions içinde aynı API'yi kullanarak bildirebilirsiniz. Yeni bir satın alma işlemini bildirme bölümünde açıklandığı gibi, sonraki işlemler için externalTransactionToken gerekli değildir. Bunun yerine, her yenileme veya para ekleme işlemi için sorgu parametresi olarak yeni bir benzersiz externalTransactionId gönderilir. İlk işlemin kimliği initialExternalTransactionId alanına eklenir.

Önceki örneğe devam edersek:

  1. 1. kullanıcının ilk yenilemesi alternatif faturalandırma sisteminde yapılır. İlk işlem kimliği 123-456-789'du.
  2. Geliştirici, initialExternalTransactionId alanında ilk işlemin harici işlem kimliğini referans gösterirken URL sorgu parametresindeki işlem yinelemesini bu yeni işlemin harici işlem kimliği olarak bildirir.

Örnek istek:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Yeni veya eski sürüme geçiş bildir

Kullanıcı alternatif faturalandırma sisteminde bir aboneliğe sahip olduğunda üst veya alt sürüme geçme işlemlerini bildirmek için aynı uç noktayı kullanın ve Externaltransactions API'de işlevi kullanarak yükseltme veya düşürme işlemi için uygulamaya sağlanan externalTransactionToken öğesini gönderin. Bu işlem, yeni bir satın alma işlemini bildirmeye benzer.

Alternatif faturalandırma işlemlerinin manuel raporlanmasından geçiş yapın

Otomatik raporlama içermeyen alternatif faturalandırma sunduğunuz sırada başlatılan etkin abonelikleri taşımak için initialExternalTransactionId veya externalTransactionToken belirtmek yerine migratedTransactionProgram alanını kullanarak yeni bir sıfır maliyetli işlem oluşturun. transactionTime değerini, kullanıcının her etkin aboneliğe ilk kaydolduğu zamana ayarlayın. Daha sonra, yenileme işlemlerini oluşturmak için yukarıda kullanılan initialExternalTransactionId bilgisini sağlayarak bu aboneliklerle ilgili takip eden her işlemi API'ler aracılığıyla normal şekilde raporlayın. Abonelik taşındıktan sonra, bu sayfada açıklanan otomatik yöntemlerle raporlanıyorlarsa abonelikle ilgili sonraki işlemleri artık manuel olarak bildirmeniz gerekmez.

Abonelikleri taşırken taşıma işleminin kota kesintisine neden olmaması için kota sınırlarını göz önünde bulundurun. Çok sayıda aboneliğin taşınması gerekiyorsa bunları birden fazla güne dağıtın veya kota artışı talep edin.

migratedTransactionProgram alanı yalnızca manuel raporlamadan taşıma yapılırken kullanılabilir. Manuel raporlama artık desteklenmediğinde bu özellik kullanımdan kaldırılacaktır.

Örnek istek:

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Satın alma geri ödemelerini Google Play'e bildirme

Geri ödenen işlemleri Google Play'in faturalandırma sisteminin dışındaki kullanıcılara bildirmek için Externaltransactions API ile entegre edin. Play'in hangi işlem için geri ödeme yapıldığını doğru bir şekilde belirleyebilmesi için daha önce bildirilen işlemle ilgili externalTransactionId değerini URL parametrelerinin bir parçası olarak eklemeniz gerekir.

Abonelik satın alma işlemleriyle ilgili geri ödemeleri bildirirken, geri ödeme yapılan aboneliğin ilgili yinelemesine ilişkin externalTransactionId bilgisine bakın.

Örnek: Bir abonelikte aşağıdaki işlemlerin olduğunu varsayalım:

  • ABC.1234-5678-9012-34567 harici işlem kimliğine sahip ilk işlem
  • Harici işlem kimliği ABC.1234-5678-9012-34567..0 olan ilk yinelenen işlem
  • Harici işlem kimliği ABC.1234-5678-9012-34567..1 olan ikinci yinelenen işlem

Abonelikle ilgili tüm işlemlerin geri ödemesini bildirmek için biri ilk işlem, diğeri sonraki işlemler için olmak üzere üç ayrı geri ödeme isteğinde bulunmanız gerekir.

Bu yöntem hem tam geri ödemeleri (tutar, kullanıcının orijinal harici işlemde ödediği tutarla aynıdır) hem de kısmi geri ödemeleri (tutarın, kullanıcının orijinal harici işlemde ödediği tutardan düşük olduğu durumlarda) kabul eder. Kısmi geri ödemelerde, geri ödenen vergi öncesi tutarı belirtmeniz gerekir.

API kotaları

Externaltransactions API, Google Play Developer API'deki diğer uç noktalar gibi tüm çağrılar için günlük API kotalarına tabidir.

Buna ek olarak, Externaltransactions API'nin Externaltransactions.createexternaltransaction veya Externaltransactions.refundexternaltransaction çağrıları için Dakika Başına 1.200 Sorgu (QPM) sınırı vardır. Externaltransactions.getexternaltransaction için yapılan aramalar,bu 1.200 QPM sınırına dahil değildir.