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 rozliczeniowe i programy linków: programy, które ułatwiają zakupy treści cyfrowych lub pobieranie aplikacji poza Google Play. Obejmuje to programy rozliczeń alternatywnych i ofert zewnętrznych.
• Interfejsy API transakcji zewnętrznych: interfejsy API używane do raportowania 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 wymaganiami programu. Dotyczy to zakupów treści cyfrowych i pobrań aplikacji.
• 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 transakcji zewnętrznej.

Zgłaszanie nowych transakcji zewnętrznych do Google Play

Zintegruj się z interfejsem API externaltransactions, aby zgłaszać transakcje przeprowadzane poza systemem rozliczeniowym Google Play w obsługiwanych krajach, w tym transakcje o wartości 0 PLN wynikające z zakupu bezpłatnego okresu próbnego i instalacji aplikacji. Transakcje w programach rozliczeniowych i programach linków należy 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 lub ofert zewnętrznych. W przeciwnym razie wywołanie interfejsu API zostanie odrzucone. Dotyczy to wszystkich transakcji, w tym nowych zakupów, odnowień, doładowań, przejść na wyższy lub niższy poziom wspierania oraz pobrań aplikacji.

Raportowanie transakcji zewnętrznych

Aby zgłosić transakcję zewnętrzną po autoryzacji płatności w ramach programu rozliczeniowego i programu linków, wywołaj interfejs API externaltransactions. 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. subskrypcji z automatycznym odnawianiem) 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 w programach rozliczeniowych i linkujących zakończy się powodzeniem, musisz wywołać interfejs API externaltransactions.

externalTransactionToken otrzymany przez aplikację za pomocą wywołań zwrotnych UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener lub BillingProgramReportingDetailsListener jest wymagany w treści żądania pobrania aplikacji, zakupu jednorazowego i pierwszej transakcji w ramach zakupu cyklicznego (np. subskrypcji). Jest to tzw. transakcja początkowa. Po pierwszej transakcji zgłaszaj kolejne transakcje (np. odnowienia subskrypcji), podając nowy, niepowtarzalny externalTransactionId. Więcej informacji o zgłaszaniu kolejnych transakcji 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. 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 rozpoczynają 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 ją 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 najpierw nastąpić transakcja o wartości 0 PLN, a później druga transakcja na kwotę kodu SKU, gdy zamówienie w przedsprzedaży zostanie zrealizowane. Więcej informacji o raportowaniu kolejnych transakcji znajdziesz w artykule Raportowanie kolejnych transakcji dotyczących zakupu.
• Podczas zgłaszania początkowych transakcji dotyczących ofert zewnętrznych 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.
• Po zainstalowaniu aplikacji zewnętrznej w ramach programu ofert zewnętrznych musisz raportować transakcje dokonane w tej aplikacji. Podczas raportowania tych transakcji połącz je z wydarzeniem pobrania oryginalnej aplikacji:
  • Podaj externalTransactionToken ze zdarzenia 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.

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. Zgodnie z opisem 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 początkowej transakcji 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ę

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 rozliczanych w ramach alternatywnego systemu rozliczeniowego

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ń funkcji Externaltransactions.createexternaltransaction lub Externaltransactions.refundexternaltransaction. Połączenia na numer Externaltransactions.getexternaltransaction nie wliczają się do limitu 1200 zapytań na minutę.