Wskazówki dotyczące integracji backendu na potrzeby zarabiania poza Płatnościami w Google Play

Google Play Developer API zawiera dodatkowe funkcje do raportowania transakcji z programów rozliczeniowych i programów linków. Z tego przewodnika dowiesz się, jak zgłaszać transakcje z tych programów rozliczeniowych.

Do obsługi transakcji zewnętrznych z poziomu backendu może być potrzebnych kilka komponentów. Aby je utworzyć, musisz skonfigurować integrację backendu zgodnie z instrukcjami w artykule Konfigurowanie interfejsu Google Play Developer API. Aby utworzyć funkcje backendu dewelopera, które nie są związane z programami rozliczeniowymi i programami linków, zapoznaj się z informacjami o systemie rozliczeniowym Google Play.

Słowniczek terminów

Konwencje terminologiczne stosowane w tym przewodniku:

  • Programy płatności i linków: programy, które ułatwiają kupowanie treści cyfrowych lub pobieranie aplikacji poza Google Play. Obejmuje to programy rozliczeń alternatywnych i treści zewnętrznych.
  • Interfejsy API transakcji zewnętrznych: interfejsy API używane do zgłaszania transakcji w przypadku kwalifikujących się programów rozliczeniowych i programów linków.
  • Transakcja zewnętrzna: kwalifikująca się transakcja, która ma miejsce poza aplikacją, zgodnie z definicją w programach alternatywnych rozliczeń i treści zewnętrznych.
  • Token transakcji zewnętrznej: token udostępniany przez Bibliotekę Płatności w Google Play, którego możesz użyć, gdy użytkownik zrealizuje transakcję zewnętrzną. Ten token służy do powiadamiania Google Play o pomyślnej transakcji zewnętrznej.
  • Zewnętrzny identyfikator transakcji: niepowtarzalny identyfikator wygenerowany przez Ciebie w celu identyfikacji zewnętrznej transakcji.

Zgłaszanie nowych transakcji zewnętrznych do Google Play

Zintegruj interfejs API externaltransactions, aby zgłaszać transakcje dokonywane poza systemem rozliczeniowym Google Play w obsługiwanych krajach, w tym transakcje o wartości 0 USD wynikające z zakupów w ramach bezpłatnego okresu próbnego i instalacji aplikacji. Transakcje w programach rozliczeniowych i linków możesz rozpoczynać i zgłaszać tylko w przypadku krajów użytkowników, które kwalifikują się do tych programów zgodnie z wytycznymi dotyczącymi rozliczeń alternatywnych, ofert zewnętrznych lub płatności zewnętrznych. W przeciwnym razie wywołanie interfejsu API zostanie odrzucone. Dotyczy to wszystkich transakcji, w tym nowych zakupów, odnowień, doładowań, uaktualnień, przejść na niższy poziom i pobrań aplikacji.

Raportowanie transakcji zewnętrznych

Po autoryzacji płatności w ramach programu rozliczeniowego i programu linków należy wywołać interfejs API externaltransactions, aby zgłosić transakcję zewnętrzną. Dotyczy to wszystkich transakcji, w tym opłat początkowych, odnowień, zwrotów środków i innych. Wymagania dotyczące raportowania znajdziesz w wytycznych dotyczących odpowiedniego programu rozliczeniowego i programu linków.

Każda transakcja zewnętrzna jest zgłaszana z identyfikatorem transakcji zewnętrznej. W przypadku zakupów cyklicznych (np. automatycznie odnawianych subskrypcji) musisz wysłać identyfikator transakcji zewnętrznej powiązany z pierwszą transakcją w zakupie cyklicznym jako parametr wszystkich kolejnych transakcji, w tym zwrotów środków. Rejestruje to serię transakcji związanych z tym zakupem. W przypadku zakupu nowego produktu (np. uaktualnienia lub obniżenia wersji) albo anulowania lub wygaśnięcia transakcji cyklicznej i ponownego zakupu tego samego produktu należy wysłać nowy zewnętrzny identyfikator transakcji. W ramach tego zewnętrznego identyfikatora transakcji nie możesz podawać żadnych informacji umożliwiających identyfikację osób, informacji zastrzeżonych ani poufnych.

Zgłaszanie transakcji początkowej

Za każdym razem, gdy nowy zakup lub pobranie aplikacji zostanie zrealizowane w ramach programów rozliczeniowych i linków, musisz wywołać interfejs API externaltransactions.

Wartość externalTransactionToken otrzymana przez aplikację za pomocą Biblioteki Płatności Google Play jest wymagana w treści żądania pobrania aplikacji, jednorazowych zakupów i pierwszych transakcji w ramach zakupu cyklicznego (np. subskrypcji). Jest to tzw. transakcja początkowa. Po pierwszej transakcji raportuj kolejne transakcje (np. odnowienia subskrypcji), podając nowy, unikalny externalTransactionId. Więcej informacji znajdziesz w artykule Zgłaszanie kolejnych transakcji dotyczących zakupu.

Przykład:

  1. Deweloper konfiguruje i włącza rozliczenia alternatywne w aplikacji.
  2. Użytkownik 1 mieszka w Korei Południowej, czyli w kraju, w którym usługa jest dostępna, i próbuje kupić product1 za 12 634, 10 KRW miesięcznie z 1-miesięcznym bezpłatnym okresem próbnym.
  3. Aplikacja uruchamia proces zakupu z parametrem ProductDetails dla product1 i wybraną przez użytkownika ofertą.
  4. Użytkownik 1 wybiera alternatywny system rozliczeniowy dewelopera.
  5. Zmienna UserChoiceBillingListener otrzymuje wartość my_token jako externalTransactionToken.
  6. Następnie deweloper przesyła odpowiednie informacje do swojego backendu (wartość externalTransactionToken i kupowane produkty). Następnie uruchamiają proces zakupu product1 w alternatywnym systemie rozliczeniowym. Po stronie dewelopera transakcji przypisywany jest unikalny identyfikator, który służy do zgłaszania jej do Google Play: 123-456-789. Identyfikator transakcji jest wymagany, nawet jeśli użytkownik korzysta z bezpłatnego okresu próbnego.
  7. Po przeprowadzeniu transakcji zakupu w alternatywnym systemie rozliczeniowym deweloper zgłasza transakcję do Google Play za pomocą tego żądania. Początkowo jest ona raportowana jako transakcja o wartości 0 USD, ponieważ użytkownik otrzymuje bezpłatny miesiąc.
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"
 }
}

Podczas zgłaszania pierwszej transakcji pamiętaj o tych kwestiach:

  • subscriptionType może być RECURRING (w przypadku subskrypcji odnawianych automatycznie) lub PREPAID (w przypadku subskrypcji przedpłaconych).
  • OtherRecurringProduct musi być używany w przypadku zakupów jednorazowych, które wymagają wielu płatności lub płatności odroczonej. Na przykład w przypadku zamówienia w przedsprzedaży może wystąpić początkowa transakcja o wartości 0 PLN, a następnie druga transakcja w późniejszym terminie na kwotę kodu SKU po zrealizowaniu zamówienia w przedsprzedaży. Więcej informacji o zgłaszaniu kolejnych transakcji znajdziesz w artykule Zgłaszanie kolejnych transakcji dotyczących zakupu.
  • Podczas zgłaszania początkowych transakcji w ramach oferty zewnętrznej musisz podać wartość ExternalOfferDetails. Nie jest to wymagane w przypadku kolejnych transakcji.

Jeśli dokonujesz transakcji z użytkownikiem w Indiach, gdzie podatek zależy od obszaru administracyjnego (np. stanu lub prowincji), podaj ten obszar w sekcji userTaxAddress. Odpowiednie obszary administracyjne znajdziesz na wstępnie zdefiniowanej liście ciągów znaków w przewodniku po interfejsie API.

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

Oferty zewnętrzne

Jeśli zgłaszana transakcja jest objęta programem ofert zewnętrznych, musisz ustawić pole externalOfferDetails, jeśli jest to transakcja jednorazowa lub pierwsza transakcja z serii cyklicznej:

  • Podczas raportowania transakcji pobierania aplikacji ustaw wartość parametru linkType na LINK_TO_APP_DOWNLOAD i podaj odpowiednie wartości parametrów installedAppPackage i installedAppCategory. Szczegółowe informacje znajdziesz w sekcji Zgłaszanie pobrania aplikacji.
  • Podczas raportowania transakcji dotyczących ofert treści cyfrowych ustaw wartość parametru linkType na LINK_TO_DIGITAL_CONTENT_OFFER.
  • Po zainstalowaniu aplikacji zewnętrznej w ramach programu ofert zewnętrznych musisz zgłaszać transakcje dokonane w tej aplikacji. Podczas zgłaszania tych transakcji połącz je z pierwotnym zdarzeniem pobrania aplikacji:
    • Podaj wartość externalTransactionToken z wydarzenia pobrania aplikacji.
    • W polu externalOfferDetails ustaw wartość appDownloadEventExternalTransactionId na externalTransactionId zdarzenia pobrania aplikacji. Pozostałe pola w externalOfferDetails nie są wymagane.

Przykładowe żądanie transakcji w aplikacji zewnętrznej pobranej w ramach ofert zewnętrznych:

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

Zaktualizowane szczegóły opłaty za obsługę w Google Play w przypadku różnych typów transakcji znajdziesz w sekcji Zmiany w programie ofert zewnętrznych dotyczące użytkowników z Europejskiego Obszaru Gospodarczego (EOG).

Zgłaszanie kolejnych transakcji dotyczących zakupu

W niektórych przypadkach z tym samym zakupem zewnętrznym jest powiązanych więcej niż 1 płatność użytkownika, np. odnowienie subskrypcji lub doładowanie abonamentu przedpłaconego. Możesz zgłaszać te kolejne transakcje za pomocą tego samego interfejsu API w Externaltransactions. Jak opisano w artykule Zgłaszanie nowego zakupu, symbol externalTransactionToken nie jest potrzebny w przypadku kolejnych transakcji. Zamiast tego w przypadku każdej transakcji odnowienia lub doładowania jako parametr zapytania wysyłany jest nowy, niepowtarzalny identyfikator externalTransactionId, a identyfikator transakcji początkowej jest uwzględniany w polu initialExternalTransactionId.

W nawiązaniu do poprzedniego przykładu:

  1. Pierwsze odnowienie subskrypcji użytkownika 1 następuje w alternatywnym systemie rozliczeniowym. Identyfikator pierwotnej transakcji to 123-456-789.
  2. Deweloper zgłasza cykliczność transakcji w parametrze zapytania URL jako zewnętrzny identyfikator transakcji dla tej nowej transakcji, odwołując się do zewnętrznego identyfikatora transakcji początkowej w polu initialExternalTransactionId.

Przykładowe żądanie:

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

Zgłaszanie przejścia na wyższą lub niższą wersję usługi

Aby zgłosić przejście na wyższą lub niższą wersję subskrypcji, gdy użytkownik ma subskrypcję w systemie rozliczeń alternatywnych, użyj tego samego punktu końcowego i funkcji w interfejsie Externaltransactions API, wysyłając parametr externalTransactionToken, który został przekazany do aplikacji w przypadku transakcji przejścia na wyższą lub niższą wersję. Działa to podobnie do zgłaszania nowego zakupu.

Zgłaszanie pobrania aplikacji

Aby zgłosić instalację aplikacji w systemie rozliczeń ofert zewnętrznych, musisz wywołać funkcję Externaltransactions.createexternaltransaction, wysyłając externalTransactionToken, który został przekazany do aplikacji. Zgłoś to jako jednorazową transakcję o zerowym koszcie. Ten proces jest podobny do zgłaszania transakcji początkowej. Pamiętaj, aby w treści żądania umieścić element ExternalOfferDetails.

Przykładowe żądanie:

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

Przejście z ręcznego raportowania transakcji rozliczeń alternatywnych

Aby przenieść aktywne subskrypcje, które rozpoczęły się w okresie, gdy oferowano rozliczenia alternatywne bez automatycznego raportowania, utwórz nową transakcję o zerowej wartości, używając pola migratedTransactionProgram zamiast określać initialExternalTransactionId lub externalTransactionToken. Ustaw wartość transactionTime na czas, w którym użytkownik po raz pierwszy zarejestrował się w każdej aktywnej subskrypcji. Następnie zgłaszaj każdą kolejną transakcję dotyczącą tych subskrypcji w normalny sposób za pomocą interfejsów API, podając wartość initialExternalTransactionId używaną wcześniej do tworzenia transakcji odnowienia. Po przeniesieniu subskrypcji nie musisz już ręcznie raportować kolejnych transakcji związanych z subskrypcją, o ile są one raportowane za pomocą automatycznych metod opisanych na tej stronie.

Podczas przenoszenia subskrypcji pamiętaj o limitach, aby sprawdzić, czy migracja nie spowoduje wyczerpania limitu. Jeśli musisz przenieść wiele subskrypcji, rozłóż je na kilka dni lub poproś o zwiększenie limitu.

Pola migratedTransactionProgram można używać tylko podczas migracji z raportowania ręcznego. Zostanie on wycofany, gdy raportowanie ręczne przestanie być obsługiwane.

Przykładowe żądanie:

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

Wymagania dotyczące programów partnerskich Google Play

Deweloperzy biorący udział w programach partnerskich, takich jak Play Media Experience, muszą podać transaction_program_code podczas raportowania transakcji zewnętrznych. Jeśli jesteś kwalifikującym się deweloperem, skontaktuj się z menedżerem ds. rozwoju biznesu, aby uzyskać więcej informacji o tym, jak ustawić to pole.

Zgłaszanie zwrotów środków za zakupy w Google Play

Zintegruj się z interfejsem externaltransactions API, aby raportować transakcje zwrócone użytkownikom poza systemem rozliczeniowym Google Play. Aby Google Play prawidłowo identyfikował transakcję, w przypadku której nastąpił zwrot środków, w parametrach adresu URL musisz uwzględnić odpowiedni parametr externalTransactionId dla wcześniej zgłoszonej transakcji.

Podczas zgłaszania zwrotów środków za zakupione subskrypcje odwołuj się do externalTransactionId konkretnego cyklu subskrypcji, za który przyznawany jest zwrot środków.

Przykład: założmy, że w przypadku subskrypcji występują te transakcje:

  • Początkowa transakcja z zewnętrznym identyfikatorem transakcji ABC.1234-5678-9012-34567

  • Pierwsza transakcja cykliczna z zewnętrznym identyfikatorem transakcji ABC.1234-5678-9012-34567..0

  • Druga transakcja cykliczna z zewnętrznym identyfikatorem transakcji ABC.1234-5678-9012-34567..1

Aby zgłosić zwrot środków za wszystkie transakcje związane z subskrypcją, musisz przesłać 3 osobne prośby o zwrot środków: jedną dotyczącą transakcji początkowej i 2 dotyczące kolejnych transakcji.

Ta metoda akceptuje zarówno pełne zwroty środków (gdy kwota jest taka sama jak kwota zapłacona przez użytkownika w pierwotnej transakcji zewnętrznej), jak i częściowe zwroty środków (gdy kwota jest mniejsza niż kwota zapłacona przez użytkownika w pierwotnej transakcji zewnętrznej). W przypadku częściowych zwrotów środków musisz podać kwotę przed opodatkowaniem, która została zwrócona.

Limity interfejsu API

Interfejs Externaltransactions API podlega limitom interfejsu API w przypadku wszystkich wywołań, tak jak każdy inny punkt końcowy w interfejsie Google Play Developer API.

Dodatkowo interfejs Externaltransactions API ma limit 1200 zapytań na minutę w przypadku wywołań Externaltransactions.createexternaltransaction lub Externaltransactions.refundexternaltransaction. Połączenia na numer Externaltransactions.getexternaltransaction nie wliczają się do limitu 1200 zapytań na minutę.