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

Google Play Developer API, faturalandırma ve bağlantı programlarındaki işlemleri bildirmek için ek işlevler içerir. Bu kılavuzda, bu faturalandırma programlarındaki işlemlerin nasıl bildirileceği açıklanmaktadır.

Arka uçtan harici işlemleri yönetmek için gerekli olabilecek birkaç bileşen vardır. Bu API'leri 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. Faturalandırmaya ve bağlantı programlarına özgü olmayan geliştirici arka uç işlevleri oluşturmak için Google Play'in faturalandırma sistemi başlıklı makaleyi inceleyin.

Terim sözlüğü

Bu kılavuzda kullanılan terimler:

• Faturalandırma ve bağlantı programları: Google Play dışında dijital içerik satın alma veya uygulama indirme işlemlerini kolaylaştıran programlar. Alternatif faturalandırma ve dış kampanya programları bu kapsamdadır.
• Harici işlem API'leri: Uygun faturalandırma ve bağlantı programları için işlemleri bildirmek üzere kullanılan API'ler.
• Uygulama dışı işlem: Program şartlarında tanımlandığı şekilde uygulama dışında gerçekleşen, ödül kazanmaya uygun bir işlem. Buna dijital içerik satın alma işlemleri ve uygulama indirmeleri dahildir.
• Harici işlem jetonu: Kullanıcı harici bir işlemi tamamladığında kullanmanız için Play Faturalandırma Kitaplığı aracılığıyla sağlanan jeton. Bu jeton, Google Play'e başarılı bir harici işlem hakkında bildirimde bulunmak için kullanılır.
• Harici işlem kimliği: Harici bir işlemi tanımlamak için sizin tarafınızdan oluşturulan benzersiz tanımlayıcı.

Yeni uygulama dışı işlemleri Google Play'e bildirme

externaltransactions API ile entegrasyon yaparak Google Play'in faturalandırma sistemi dışında gerçekleşen işlemleri bildirin (ücretsiz deneme satın alma ve uygulama yükleme işlemlerinden kaynaklanan 0 ABD doları tutarındaki işlemler dahil). Yalnızca alternatif faturalandırma veya dış kampanyalar yönergeleri uyarınca izin verilen şekilde, uygun kullanıcı ülkeleri için faturalandırma ve bağlantı programlarındaki işlemleri başlatıp bildirmelisiniz. Aksi takdirde API çağrısı reddedilir. Bu durum, yeni satın alma işlemleri, yenilemeler, para eklemeler, üst sürüme geçişler, alt sürüme geçişler ve uygulama indirmeleri dahil olmak üzere tüm işlemler için geçerlidir.

Harici işlem raporlama

Bir ödeme, faturalandırma ve bağlantı programı aracılığıyla yetkilendirildikten sonra harici bir işlemi bildirmek için externaltransactions API'sini çağırmanız gerekir. Bu durum, ilk ödemeler, yenilemeler, geri ödemeler ve diğerleri dahil olmak üzere tüm işlemler için geçerlidir. Raporlama koşulları için ilgili faturalandırma ve bağlantı programının kurallarını inceleyin.

Her harici işlem, harici işlem kimliğiyle bildirilir. Yinelenen satın alma işlemleri (ör. otomatik yenilenen abonelikler) için, geri ödemeler dahil olmak üzere sonraki tüm işlemlerin parametresi olarak yinelenen satın alma işlemindeki ilk işlemle ilişkili harici işlem kimliğini göndermeniz gerekir. Bu işlem, söz konusu satın alma işlemine ait işlem dizisini kaydeder. Ürün değiştiğinde (ör. yükseltme veya düşürme) ya da yinelenen işlem iptal edildiğinde veya 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öndermeniz gerekir. Bu harici işlem kimliğine kimliği tanımlayabilecek bilgiler, tescilli bilgiler veya gizli bilgiler eklememelisiniz.

İlk işlemi bildirme

Faturalandırma ve bağlantı programlarında her yeni satın alma veya uygulama indirme işlemi başarılı olduğunda externaltransactions API'sini çağırmanız gerekir.

Uygulama tarafından UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener veya BillingProgramReportingDetailsListener geri çağırmaları aracılığıyla alınan externalTransactionToken, uygulama indirme, tek seferlik satın alma ve yinelenen satın alma işlemlerinde (ör. abonelik) ilk kez yapılan işlemler için istek gövdesinin bir parçası olarak gereklidir. Buna ilk işlem denir. İlk işlemden sonraki işlemleri (ör. abonelik yenilemeleri) yeni bir benzersiz externalTransactionId sağlayarak bildirin. Sonraki işlemleri bildirme hakkında daha fazla bilgi için Satın alma işlemiyle ilgili sonraki işlemleri bildirme başlıklı makaleyi inceleyin.

Ö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 aylık 12.634,10 KRW karşılığında product1 satın almaya çalışıyor.
3. Uygulama, product1 için ProductDetails ile satın alma akışını başlatır ve kullanıcının seçtiği teklifi gösterir.
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ğeri 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şleme, geliştirici tarafında Google Play'e bildirmek için kullanılan benzersiz bir işlem kimliği atanır: 123-456-789. Kullanıcı ücretsiz deneme alsa bile işlem kimliği gereklidir.
7. Satın alma işlemi için alternatif faturalandırma sisteminde işlem gerçekleştiğinde geliştirici, işlemi aşağıdaki istekle Google Play'e bildirir. Kullanıcıya bir ay ücretsiz kullanım hakkı verildiği için başlangıçta sıfır ABD doları tutarında bir 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"
 }
}

İlk işlemi bildirirken aşağıdakilere dikkat edin:

• subscriptionType, RECURRING (otomatik yenilenen abonelikler için) veya PREPAID (ön ödemeli abonelikler için) olabilir.
• Birden fazla ödeme veya gecikmeli ödeme gerektiren tek seferlik satın alma işlemlerini temsil etmek için OtherRecurringProduct kullanılmalıdır. Örneğin, bir ön siparişte ilk olarak 0 ABD dolarlık bir işlem yapılabilir. Ardından, ön sipariş karşılandığında SKU'nun fiyatı için daha sonraki bir tarihte ikinci bir işlem yapılabilir. Sonraki işlemleri bildirme hakkında daha fazla bilgi için Satın alma işlemine ilişkin sonraki işlemleri bildirme başlıklı makaleyi inceleyin.
• İlk harici teklif işlemlerini bildirirken ExternalOfferDetails sağlamanız gerekir. Bu, sonraki işlemler için gerekli değildir.

Verginin kullanıcının idari bölgesine (ör. eyalet veya il) bağlı olduğu Hindistan'daki bir kullanıcıyla işlem yapıyorsanız bu bölgeyi userTaxAddress altında belirtin. Geçerli idari bölgeler için API referans kılavuzundaki önceden tanımlanmış dizeler 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"
 }
}

Harici teklifler

Bildirilen işlem harici teklif programı kapsamındaysa ve tek seferlik bir işlemse veya yinelenen bir serinin ilk işlemiyse externalOfferDetails alanını ayarlamanız gerekir:

• Uygulama indirme işlemlerini raporlarken linkType değerini LINK_TO_APP_DOWNLOAD olarak ayarlayın ve installedAppPackage ile installedAppCategory için uygun değerleri girin. Ayrıntılar için Uygulama indirme işlemini bildirme başlıklı makaleyi inceleyin.
• Dijital içerik teklifi işlemlerini bildirirken linkType değerini LINK_TO_DIGITAL_CONTENT olarak ayarlayın.
• Harici uygulamalar programı aracılığıyla harici bir uygulama yüklendikten sonra, harici uygulamada yapılan işlemleri bildirmeniz gerekir. Bu işlemleri bildirirken, işlemleri orijinal uygulama indirme etkinliğine bağlayın:
  • Uygulama indirme etkinliğinden externalTransactionToken değerini sağlayın.
  • externalOfferDetails alanında, appDownloadEventExternalTransactionId değerini uygulama indirme etkinliğinin externalTransactionId olarak ayarlayın. externalOfferDetails içindeki diğer alanlar zorunlu değildir.

Harici teklifler aracılığıyla indirilen harici bir uygulamada işlem isteği örneği:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "100000",
   "currency": "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros": "10000",
   "currency": "EUR"
 },
"transactionTime" : "2025-11-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": my_external_transaction_token_for_link_to_download_event"
 },
 "userTaxAddress" : {
   "regionCode": "DE"
 },
 "externalOfferDetails" : {
   "appDownloadEventExternalTransactionId": "my_external_transaction_id_for_link_to_download_event"
 }
}

Farklı işlem türleri için güncellenen Play hizmet ücreti ayrıntılarını, Avrupa Ekonomik Alanı'ndaki (AEA) kullanıcılar için Dış kampanya programında yapılan değişiklikler başlıklı makalede bulabilirsiniz.

Satın alma işlemiyle ilgili sonraki işlemleri bildirme

Bazı durumlarda, aynı harici satın alma işlemiyle ilişkili birden fazla kullanıcı ödemesi olabilir. Örneğin, abonelik yenilemeleri veya ön ödemeli planlara para ekleme işlemleri. Bu sonraki işlemleri Externaltransactions bölümünde aynı API'yi kullanarak bildirebilirsiniz. Yeni bir satın alma işlemini bildirme başlıklı makalede açıklandığı gibi, sonraki işlemler için externalTransactionToken gerekli değildir. Bunun yerine, her yenileme veya yükleme 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 göre:

1. 1. kullanıcının ilk yenilemesi alternatif faturalandırma sisteminde gerçekleşir. İlk işlem kimliği 123-456-789 idi.
2. Geliştirici, URL sorgu parametresindeki işlem tekrarını bu yeni işlemin harici işlem kimliği olarak bildirirken initialExternalTransactionId alanında ilk işlemin harici işlem kimliğine referans verir.

Ö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"
 }
}

Sürüm yükseltme veya düşürme işlemini bildirme

Kullanıcı, alternatif faturalandırma sisteminde bir aboneliğe sahip olduğunda yükseltme veya düşürme işlemini bildirmek için Externaltransactions API'sinde aynı uç noktayı ve işlevi kullanıp yükseltme veya düşürme işlemi için uygulamaya sağlanan externalTransactionToken değerini gönderirsiniz. Bu işlem, yeni bir satın alma işlemini bildirmeye benzer şekilde çalışır.

Uygulama indirme işlemini bildirme

Harici teklifler faturalandırma sisteminde uygulama yükleme işlemini bildirmek için Externaltransactions.createexternaltransaction işlevini çağırıp uygulamaya sağlanan externalTransactionToken değerini göndermeniz gerekir. Bunu sıfır maliyetli, tek seferlik bir işlem olarak bildirin. Bu işlem, ilk işlemi bildirmeye benzer. İstek gövdesine ExternalOfferDetails eklediğinizden emin olun.

Örnek istek:

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

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "USD"
 },
"transactionTime" : "2025-12-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken": "my_token",
 },
 "userTaxAddress" : {
   "regionCode": "US"
 }
 "externalOfferDetails" : {
   "linkType" : "LINK_TO_APP_DOWNLOAD",
   "installedAppPackage" : "my.external.app",
   "installedAppCategory" : "APP"
 }
}

Alternatif faturalandırma işlemlerinin manuel olarak raporlanmasından geçiş yapma

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. Ardından, bu aboneliklerle ilgili sonraki her işlemi API'ler üzerinden normal şekilde bildirin ve yenileme işlemlerini oluşturmak için daha önce kullanılan initialExternalTransactionId değerini sağlayın. Abonelik taşındıktan sonra, bu sayfada açıklanan otomatik yöntemlerle bildirildiği sürece abonelikle ilgili sonraki işlemleri manuel olarak bildirmeniz gerekmez.

Abonelikleri taşırken, taşıma işleminin kota kesintisine neden olmaması için uygulanan kota sınırlarına dikkat edin. Çok sayıda aboneliğin taşınması gerekiyorsa bunları birden fazla güne yayın veya kota artışı isteğinde bulunun.

migratedTransactionProgram alanı yalnızca manuel raporlamadan geçiş yaparken 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"
 }
}

Play iş ortağı programlarının koşulları

Play Medya Oynatma Deneyimi Programı gibi iş ortağı programlarına katılan geliştiriciler, harici işlemleri bildirirken transaction_program_code değerini sağlamalıdır. Uygun bir geliştiriciyseniz bu alanı ayarlama hakkında daha fazla bilgi için İş Geliştirme Yöneticinizle iletişime geçin.

Satın alma işlemlerinde geri ödemeleri Google Play'e bildirme

Google Play'in faturalandırma sistemi dışında kullanıcılara iade edilen işlemleri bildirmek için externaltransactions API'siyle entegrasyon yapın. Play'in hangi işlemin geri ödendiğini doğru şekilde belirleyebilmesi için URL parametreleri kapsamında daha önce bildirilen işlemle ilgili externalTransactionId değerini eklemeniz gerekir.

Abonelik satın alma işlemlerinin geri ödemelerini bildirirken geri ödemesi yapılan aboneliğin belirli yinelenme sıklığına ait externalTransactionId değerini referans alın.

Örnek: Bir abonelikte aşağıdaki işlemlerin yapıldığını varsayalım:

• Harici işlem kimliği ABC.1234-5678-9012-34567 olan 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 üç ayrı geri ödeme isteğinde bulunmanız gerekir: biri ilk işlem için, ikisi de sonraki işlemler için.

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, kullanıcının orijinal harici işlemde ödediği tutardan daha azdır) kabul eder. Kısmi geri ödemelerde, geri ödenen vergi öncesi tutarı belirtmeniz gerekir.

API kotaları

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

Ayrıca, 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'ye yapılan çağrılar,1.200 QPM sınırına dahil değildir.