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 ucunuzdan harici işlemleri yönetmek 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. 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'ne bakın.
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ıyla ilgili 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şlemi Google Play'e bildirmek 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 bir tanımlayıcı.
Google Play Console izinlerini yapılandırma
Harici işlemleri bildirmek veya geri ödemek için externaltransactions API'yi çağırmak üzere Google Play Console'da hizmet hesabınıza Siparişleri ve abonelikleri yönetme izni verin. Bu izni hesap düzeyinde veya belirli uygulamalar için verebilirsiniz.
Hizmet hesabı oluşturma ve Google Play Console'da izin verme talimatları için Hizmet hesabı kullanma başlıklı makaleyi inceleyin. Google Play Console izinleri hakkında daha fazla bilgi için Geliştirici hesabı kullanıcıları ekleme ve izinleri yönetme konusunu inceleyin.
Yeni uygulama dışı işlemleri Google Play'e bildirme
Ücretsiz deneme satın alma işlemlerinden ve uygulama yüklemelerinden kaynaklanan 0 ABD doları tutarındaki işlemler de dahil olmak üzere desteklenen ülkelerde Google Play'in faturalandırma sistemi dışında gerçekleşen işlemleri bildirmek için externaltransactions API ile entegrasyon yapın. 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 ö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.
İlk ödemeler, yenilemeler, geri ödemeler ve diğerleri 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, bir harici işlem kimliğiyle raporlanır. 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, ilgili satın alma işlemine ait işlem serisini 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 yeni bir satın alma veya uygulama indirme işlemi her yetkilendirildiğinde externaltransactions API'yi çağırmanız gerekir.
Uygulamanın Google Play Faturalandırma Kitaplığı üzerinden aldığı externalTransactionToken; uygulama indirme, tek seferlik satın alma ve yinelenen satın alma işlemlerindeki (ör. abonelik) ilk işlemler için istek içeriğinin bir parçası olarak gereklidir. Buna ilk işlem denir. İlk işlemden sonra, yeni ve benzersiz bir externalTransactionId sağlayarak sonraki işlemleri (ör. abonelik yenilemeleri) raporlayın. Daha fazla bilgi için Bir satın alma işlemi için sonraki işlemleri bildirme başlıklı makaleyi inceleyin.
Örnek:
- Geliştirici, uygulamasında alternatif faturalandırmayı yapılandırıp etkinleştirir.
- 1. kullanıcı, desteklenen bir ülke olan Güney Kore'de bulunuyor ve bir aylık ücretsiz deneme teklifiyle aylık 12.634,10 Güney Kore wonu karşılığında
product1satın almaya çalışıyor. - Uygulama,
product1içinProductDetailsve kullanıcının seçtiği teklifle satın alma sürecini başlatır. - 1. kullanıcı, geliştiricinin alternatif faturalandırma sistemini seçer.
UserChoiceBillingListener,my_tokendeğeriniexternalTransactionTokenolarak alır.- Geliştirici daha sonra ilgili bilgileri (
externalTransactionTokendeğeri ve satın alınan ürünler) arka ucuna gönderir. Ardından, alternatif faturalandırma sistemindeproduct1için satın alma sürecini başlatırlar. 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 sürümünden yararlanıyor olsa bile işlem kimliği gereklidir. - Alternatif faturalandırma sisteminde satın alma işlemi gerçekleştikten sonra geliştirici, aşağıdaki istekle işlemi Google Play'e bildirir. Kullanıcı bir ay ücretsiz kullanım hakkı kazandığı için başlangıçta sıfır dolarlık 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) veyaPREPAID(ö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 raporlama hakkında daha fazla bilgi için Bir satın alma işlemi için sonraki işlemleri raporlama bölümünü inceleyin.- İlk harici teklif işlemlerini bildirirken
ExternalOfferDetailssağlamanız gerekir. Sonraki işlemler için bu gerekli değildir.
Hindistan'da verginin kullanıcının bağlı olduğu yere (ör. eyalet veya il) bağlı olduğu bir kullanıcıyla işlem yapıyorsanız bu bölgeyi userTaxAddress bölümüne ekleyin. Geçerli bağlı olduğu yerler için API Başvuru Kılavuzu'ndaki ö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 ve tek seferlik bir işlem veya yinelenen bir serinin ilk işlemiyse externalOfferDetails alanını ayarlamanız gerekir:
- Uygulama indirme işlemlerini raporlarken
linkTypedeğeriniLINK_TO_APP_DOWNLOADolarak ayarlayın veinstalledAppPackageileinstalledAppCategoryiçin uygun değerleri girin. Ayrıntılar için Uygulama indirme işlemi bildirme başlıklı makaleyi inceleyin. - Dijital içerik teklifi işlemlerini bildirirken
linkTypedeğeriniLINK_TO_DIGITAL_CONTENT_OFFERolarak 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
externalTransactionTokendeğerini sağlayın. externalOfferDetailsalanındaappDownloadEventExternalTransactionIddeğerini, uygulama indirme etkinliğininexternalTransactionIddeğerine ayarlayın.externalOfferDetailsiçindeki diğer alanlar zorunlu değildir.
- Uygulama indirme etkinliğinden
Dış kampanya üzerinden 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üncellenmiş Google 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 bölümünde 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ç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 ekleme işlemi için sorgu parametresi olarak yeni ve benzersiz bir externalTransactionId gönderilir. İlk işlemin kimliği ise initialExternalTransactionId alanına eklenir.
Önceki örneği ele alalım:
- 1. Kullanıcı'nın ilk yenileme işlemi alternatif faturalandırma sisteminde gerçekleşir. İlk işlem kimliği 123-456-789 idi.
- Geliştirici, URL sorgu parametresindeki işlem yinelemesini bu yeni işlemin harici işlem kimliği olarak bildirirken
initialExternalTransactionIdalanı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 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ır, 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şlemi 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 ücretsiz, tek seferlik bir işlem olarak bildirin. Bu işlem, ilk işlemi bildirmeye benzer. İstek içeriğine ExternalOfferDetails parametresini 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 raporlaması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 ücretsiz işlem oluşturun. transactionTime değerini, kullanıcının her bir etkin aboneliğe ilk kaydolduğu zamana ayarlayın. Ardından, bu abonelikler için sonraki her işlemi API'ler aracılığıyla 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, abonelikle ilgili sonraki işlemleri manuel olarak bildirmeniz gerekmez. Bu işlemler, bu sayfada açıklanan otomatik yöntemlerle bildirilir.
Abonelikleri taşırken, taşıma işleminin kota kesintisine neden olmadığını doğrulamak için geçerli kota sınırlarını göz önünde bulundurun. Ç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"
}
}
Google Play İş Ortağı Programları için şartlar
Google Play Medya Deneyim Programı gibi iş ortağı programlarına katılan geliştiriciler, harici işlemleri bildirirken transaction_program_code 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 geri ödenen 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 tarihinin externalTransactionId değerini referans alın.
Örnek: Bir aboneliğin aşağıdaki işlemlere sahip olduğunu varsayalım:
Harici işlem kimliği ABC.1234-5678-9012-34567 olan bir 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ğinde bulunmanız gerekir: biri ilk işlem için, ikisi de sonraki işlemler için.
Bu yöntem hem eksiksiz 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 dakikada 1.200 sorgu (QPM) sınırı vardır. Externaltransactions.getexternaltransaction çağrıları bu 1.200 QPM sınırına dahil edilmez.