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 raporlanacağı açıklanmaktadır.

Arka uçtan harici işlemleri işlemek için gerekli olabilecek birkaç bileşen vardır. Bu API'leri oluşturmak için Google Play Developer API'yi yapılandırma bölümünde belirtildiği gibi arka uç entegrasyonunuzu ayarlamanız gerekir. Faturalandırma 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 harici içerik programları da buna dahildir.
  • Harici işlem API'leri: Uygun faturalandırma ve bağlantı programlarındaki işlemleri bildirmek için kullanılan API'ler.
  • Harici işlem: Alternatif faturalandırma ve harici içerik programlarında tanımlandığı şekilde uygulama dışında gerçekleşen uygun bir işlem.
  • Harici işlem jetonu: Kullanıcı harici bir işlem başlattığında kullanmanız için Google Play Faturalandırma Kitaplığı aracılığıyla sağlanan bir jetondur. Bu jeton, yetkilendirilmiş bir harici işlem hakkında Google Play'i bilgilendirmek 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 desteklenen ülkelerde bildirin (ücretsiz deneme satın alma işlemlerinden kaynaklanan 0 ABD doları tutarındaki işlemler ve uygulama yüklemeleri dahil). Faturalandırma ve bağlantı programlarında işlemleri yalnızca alternatif faturalandırma ve harici içerik programları kapsamında izin verilen uygun kullanıcı ülkeleri için başlatıp bildirmeniz gerekir. Aksi takdirde API çağrısı reddedilir. Yeni satın alma işlemleri, yenileme, para ekleme, yükseltme, eski sürüme geçme ve uygulama indirme gibi tüm işlemler bu kapsamdadır.

Harici işlem raporlama

Bir faturalandırma ve bağlantı programı aracılığıyla ödeme yetkilendirildikten sonra harici bir işlemi bildirmek için externaltransactions API'yi çağırmanız gerekir. İlk ödemeler, yenilemeler ve geri ödemeler dahil olmak üzere tüm işlemler bu kapsamdadır. Raporlama koşulları için ilgili faturalandırma ve bağlantı programının yönergelerini inceleyin.

Her harici işlem, harici işlem kimliğiyle bildirilir. Yinelenen satın alma işlemleri (ör. otomatik yenilenen abonelikler) için yinelenen satın alma işlemindeki ilk işlemle ilişkili harici işlem kimliğini, geri ödemeler de dahil olmak üzere sonraki tüm işlemler için parametre olarak 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 yetkilendirildiğinde externaltransactions API'sini çağırmanız gerekir.

Uygulamanın Google Play Faturalandırma Kitaplığı üzerinden aldığı externalTransactionToken; uygulama indirmeleri, tek seferlik satın alma işlemleri ve yinelenen satın alma işlemlerindeki (ör. abonelik) ilk 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. Daha fazla bilgi için Bir satın alma işlemi için sonraki işlemleri bildirme başlıklı makaleyi inceleyin.

Örnek:

  1. Geliştirici, uygulamasında alternatif faturalandırmayı yapılandırıp etkinleştirir.
  2. 1. kullanıcı, desteklenen bir ülke olan Güney Kore'de bulunuyor ve product1 satın almaya çalışıyor. Bu aboneliğin aylık ücreti 12.634,10 Güney Kore wonu ve bir aylık ücretsiz deneme teklifi sunuluyor.
  3. Uygulama, product1 için ProductDetails ve kullanıcının seçtiği teklifle satın alma sürecini 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ğeri ve satın alınan ürünler). Ardından, alternatif faturalandırma sisteminde product1 için satın alma sürecini başlatırlar. Bu işleme, geliştirici tarafında benzersiz bir işlem kimliği atanır. Bu kimlik, işlemi Google Play'e bildirmek için kullanılır: 123-456-789. Kullanıcı ücretsiz deneme sürümünden yararlanıyor olsa bile işlem kimliği gereklidir.
  7. Satın alma işlemi alternatif faturalandırma sisteminde gerçekleştiğinde geliştirici, işlemi aşağıdaki istekle Google Play'e bildirir. Kullanıcı bir ay ücretsiz hizmet aldığından başlangıçta sıfır ABD doları tutarında bir işlem olarak bildirilir.
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.
  • OtherRecurringProduct, birden fazla ödeme veya gecikmeli ödeme gerektiren tek seferlik satın alma işlemlerini temsil etmek için kullanılmalıdır. Örneğin, ön sipariş için ilk olarak 0 ABD doları tutarında bir işlem, daha sonra ise ön sipariş yerine getirildiğinde SKU fiyatı için ikinci bir işlem yapılabilir. Sonraki işlemleri bildirme hakkında daha fazla bilgi için Satın alma işlemine ait sonraki işlemleri bildirme başlıklı makaleyi inceleyin.
  • İlk harici teklif işlemlerini bildirirken ExternalOfferDetails değerini sağlamanız gerekir. Bu, sonraki işlemler için gerekli değildir.

Hindistan'da verginin kullanıcının bağlı olduğu yere (ör. eyalet veya il) göre değiştiği bir kullanıcıyla işlem yapıyorsanız bu bölgeyi userTaxAddress alanına ekleyin. Geçerli bağlı olduğu yerler için API Başvuru 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"
 }
}

Harici teklifler

Bildirilen işlem dış kampanya programı kapsamındaysa işlem 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 sağlayın. Ayrıntılar için Uygulama indirme bildirme başlıklı makaleyi inceleyin.
  • Dijital içerik teklifi işlemlerini bildirirken linkType değerini LINK_TO_DIGITAL_CONTENT_OFFER olarak ayarlayın.
  • Dış kampanya programı aracılığıyla harici bir uygulama yüklendikten sonra harici uygulamada yapılan işlemleri bildirmeniz gerekir. Bu işlemleri bildirirken 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 değerine ayarlayın. externalOfferDetails içindeki diğer alanlar zorunlu değildir.

Dış kampanya aracılığıyla indirilen harici bir uygulamadaki işlem için örnek istek:

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

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "990000", # 0.99 EUR
   "currency" : "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros" : "90000", # 0.09 EUR
   "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.

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

Bazı durumlarda, aynı harici satın alma işlemiyle ilişkili birden fazla kullanıcı ödemesi (ör. abonelik yenilemeleri veya ön ödemeli plan para eklemeleri) olabilir. Bu sonraki işlemleri Externaltransactions içindeki 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 ekleme işlemi için sorgu parametresi olarak yeni ve benzersiz bir externalTransactionId gönderilir ve ilk işlemin kimliği initialExternalTransactionId alanına eklenir.

Önceki örneği ele alalım:

  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", # 12634 KRW
   "currency" : "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros" : "1263000000", # 1263 KRW
   "currency" : "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId" : "123-456-789",

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

Yükseltme veya düşürme işlemlerini bildirme

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

Uygulama indirme işlemini bildirme

Dış kampanya faturalandırma sisteminde bir uygulama yükleme işlemini bildirmek için Externaltransactions.createexternaltransaction yöntemini çağırarak uygulamaya sağlanan externalTransactionToken değerini göndermeniz gerekir. Bu işlemi, sıfır maliyetli ve tek seferlik bir işlem olarak bildirin. Bu süreç, 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, yenileme işlemlerini oluşturmak için daha önce kullanılan initialExternalTransactionId ile birlikte API'ler üzerinden normal şekilde bildirin. 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 olmadığını doğrulamak için geçerli kota sınırlarına dikkat edin. Çok sayıda aboneliğin taşınması gerekiyorsa bunları birkaç 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 de kullanımdan kaldırılacak.

Ö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 Deneyimi Programı gibi iş ortağı programlarına katılan geliştiriciler, harici işlemleri raporlarken transaction_program_code değerini sağlamalıdır. Uygun bir geliştiriciyseniz bu alanı nasıl ayarlayacağınız hakkında daha fazla bilgi için İş Geliştirme Yöneticinizle iletişime geçin.

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

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

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

Örnek: Bir abonelikte aşağıdaki işlemlerin olduğunu 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şlemler için geri ödeme bildirmek istiyorsanız üç ayrı geri ödeme isteği göndermeniz gerekir: biri ilk işlem için, ikisi de sonraki işlemler için.

Bu yöntem hem eksiksiz geri ödemeleri (tutarın, kullanıcının orijinal uygulama dışı işlemde ödediği tutarla aynı olduğu) hem de kısmi geri ödemeleri (tutarın, kullanıcının orijinal uygulama dışı işlemde ödediği tutardan daha az olduğu) 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 dakikada 1.200 sorgu (QPM) sınırı vardır. Externaltransactions.getexternaltransaction için yapılan çağrılar bu 1.200 QPM sınırına dahil edilmez.