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

Interfejs Google Play Developer API zawiera dodatkowe funkcje do raportowania transakcji z programów rozliczeniowych i programów linków. W tym przewodniku opisujemy, jak raportować transakcje z tych programów rozliczeniowych.

Do obsługi transakcji zewnętrznych z backendu może być potrzebnych kilka komponentów. Aby je utworzyć, musisz skonfigurować integrację z backendem zgodnie z instrukcjami w artykule Konfigurowanie interfejsu Google Play Developer API. Aby utworzyć funkcje backendu dewelopera, które nie są specyficzne dla programów rozliczeniowych i programów linków , zapoznaj się z artykułem System rozliczeniowy 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 treści zewnętrznych.
• Interfejsy API transakcji zewnętrznych: interfejsy API używane do raportowania transakcji w ramach 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 rozliczeń alternatywnych i treści zewnętrznych.
• Token transakcji zewnętrznej: token udostępniany przez Bibliotekę Płatności w Play , którego możesz użyć, gdy użytkownik zainicjuje transakcję zewnętrzną. Ten token służy do powiadamiania Google Play o autoryzowanej transakcji zewnętrznej.
• Identyfikator zewnętrzny transakcji: unikalny identyfikator wygenerowany przez Ciebie w celu identyfikacji transakcji zewnętrznej.

Zgłaszanie nowych transakcji zewnętrznych do Google Play

Zintegruj się z interfejsem externaltransactions API, aby zgłaszać transakcje, które mają miejsce 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. Możesz rozpoczynać i zgłaszać transakcje w ramach programów rozliczeniowych i programów linków tylko w przypadku kwalifikujących się krajów uprawnionych użytkowników, zgodnie z zasadami programów rozliczeń alternatywnych i treś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 pobierania aplikacji.

Raportowanie transakcji zewnętrznych

Po autoryzacji płatności w ramach programu rozliczeniowego lub programu linków należy wywołać interfejs externaltransactions API, 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 lub 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ć zewnętrzny identyfikator transakcji powiązany z pierwszą transakcją w ramach zakupu cyklicznego jako parametr wszystkich kolejnych transakcji, w tym zwrotów środków. Rejestruje to serię transakcji związanych z tym zakupem. W przypadku zakupów, gdy produkt się zmienia (np. uaktualnienie lub przejście na niższą wersję) albo gdy transakcja cykliczna zostanie anulowana lub wygaśnie, a ten sam produkt zostanie kupiony ponownie, należy wysłać nowy identyfikator zewnętrzny transakcji. W ramach tego identyfikatora nie wolno podawać żadnych informacji umożliwiających identyfikację, informacji zastrzeżonych ani poufnych.

Zgłaszanie transakcji początkowej

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

W przypadku pobierania aplikacji, zakupów jednorazowych i pierwszych transakcji w ramach zakupu cyklicznego (np. subskrypcji) wymagany jest externalTransactionToken otrzymany przez aplikację za pomocą Biblioteki Płatności w Google Play. Nazywamy to transakcją początkową. Po transakcji początkowej zgłaszaj kolejne transakcje (np. odnowienia subskrypcji), podając nowy, unikalny externalTransactionId. Więcej informacji znajdziesz w artykule Zgłaszanie kolejnych transakcji związanych z zakupem.

Przykład:

1. Deweloper konfiguruje i włącza w swojej aplikacji rozliczenia alternatywne.
2. Użytkownik 1 mieszka w Korei Południowej, czyli w obsługiwanym kraju, i próbuje kupić product1 za 12634,10 KRW miesięcznie w ramach bezpłatnego okresu próbnego trwającego miesiąc.
3. Aplikacja uruchamia proces zakupu z użyciem ProductDetails dla product1 i oferty wybranej przez użytkownika.
4. Użytkownik 1 wybiera alternatywny system rozliczeniowy dewelopera.
5. Element UserChoiceBillingListener otrzymuje wartość my_token jako externalTransactionToken.
6. Deweloper wysyła odpowiednie informacje do swojego backendu (wartość externalTransactionToken i kupowane produkty). Następnie uruchamia proces zakupu product1 w alternatywnym systemie rozliczeniowym. Ta transakcja otrzymuje po stronie dewelopera unikalny identyfikator transakcji, który jest używany 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. Gdy w alternatywnym systemie rozliczeniowym dojdzie do transakcji zakupu, deweloper zgłasza ją do Google Play za pomocą tego żądania. Początkowo jest ona zgłaszana 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 transakcji początkowej pamiętaj o tych kwestiach:

• Wartość subscriptionType może być RECURRING (w przypadku subskrypcji z automatycznym odnawianiem) lub PREPAID (w przypadku subskrypcji przedpłaconych).
• Element OtherRecurringProduct musi być używany do reprezentowania jednorazowych zakupów, które wymagają wielu płatności lub płatności z opóźnieniem. Na przykład w przypadku zamówienia w przedsprzedaży może wystąpić początkowa transakcja o wartości 0 USD, a następnie druga transakcja w późniejszym terminie za cenę SKU, gdy zamówienie w przedsprzedaży zostanie zrealizowane. Więcej informacji o zgłaszaniu kolejnych transakcji znajdziesz w artykule Zgłaszanie kolejnych transakcji związanych z zakupem.
• Podczas zgłaszania początkowych transakcji ofert zewnętrznych musisz podać ExternalOfferDetails. Nie jest to wymagane w przypadku kolejnych transakcji.

Jeśli transakcja jest przeprowadzana z użytkownikiem w Indiach, gdzie podatek zależy od jego obszaru administracyjnego (np. stanu lub prowincji), uwzględnij ten obszar w polu 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 w serii cyklicznej:

• Podczas zgłaszania transakcji pobierania aplikacji ustaw linkType na LINK_TO_APP_DOWNLOAD i podaj odpowiednie wartości dla installedAppPackage i installedAppCategory. Więcej informacji znajdziesz w artykule Zgłaszanie pobrania aplikacji.
• Podczas zgłaszania transakcji ofert treści cyfrowych ustaw 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 externalTransactionToken ze zdarzenia pobrania aplikacji.
  • W polu externalOfferDetails ustaw 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" : "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"
 }
}

Zaktualizowane informacje o opłacie za obsługę Usług Google Play w przypadku różnych typów transakcji można znaleźć w artykule Zmiany w programie ofert zewnętrznych dla użytkowników z Europejskiego Obszaru Gospodarczego.

Zgłaszanie kolejnych transakcji związanych z zakupem

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

Kontynuacja poprzedniego przykładu:

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

Przykładowe żądanie:

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

Zgłaszanie uaktualnienia lub przejścia na niższą wersję

Aby zgłosić uaktualnienie lub przejście na niższą wersję, gdy użytkownik ma subskrypcję w alternatywnym systemie rozliczeniowym, użyj tego samego punktu końcowego i funkcji w interfejsie Externaltransactions API, wysyłając externalTransactionToken, który został udostępniony aplikacji w przypadku transakcji uaktualnienia lub przejścia na niższą wersję. Działa to podobnie jak zgłaszanie nowego zakupu.

Zgłaszanie pobrania aplikacji

Aby zgłosić instalację aplikacji w systemie rozliczeniowym ofert zewnętrznych, musisz wywołać Externaltransactions.createexternaltransaction, wysyłając externalTransactionToken który został udostępniony aplikacji. Zgłoś to jako transakcję jednorazową o zerowym koszcie. Ten proces jest podobny do zgłaszania transakcji początkowej. Pamiętaj, aby w treści żądania uwzględnić 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"
 }
}

Migracja 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 zerowym koszcie, używając pola migratedTransactionProgram zamiast określać initialExternalTransactionId lub externalTransactionToken. Ustaw 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ę związaną z tymi subskrypcjami w normalny sposób za pomocą interfejsów API, podając initialExternalTransactionId użyty wcześniej do utworzenia transakcji odnowienia. Po przeniesieniu subskrypcji nie musisz już ręcznie zgłaszać kolejnych transakcji związanych z subskrypcją, o ile są one zgłaszane za pomocą zautomatyzowanych metod opisanych na tej stronie.

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

Pola migratedTransactionProgram można używać tylko podczas migracji z ręcznego raportowania. Zostanie ono wycofane, gdy ręczne raportowanie nie będzie już 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 Play

Deweloperzy uczestniczący w programach partnerskich, takich jak program Media Experience w Play, muszą podać transaction_program_code podczas zgłaszania transakcji zewnętrznych. Jeśli jesteś deweloperem kwalifikującym się do udziału w programie, 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 do Google Play

Zintegruj się z interfejsem externaltransactions API, aby zgłaszać transakcje, za które użytkownicy otrzymali zwrot środków poza systemem rozliczeniowym Google Play. Aby Google Play mogło prawidłowo zidentyfikować transakcję, za którą został zwrócony koszt, w parametrach adresu URL należy uwzględnić odpowiedni externalTransactionId wcześniej zgłoszonej transakcji.

Podczas zgłaszania zwrotów środków za zakupy subskrypcji odwołuj się do externalTransactionId konkretnego cyklu subskrypcji, za który zwracasz środki.

Przykład: załóżmy, że subskrypcja ma te transakcje:

• Transakcja początkowa 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 wysłać 3 osobne prośby o zwrot środków: jedną w przypadku transakcji początkowej i 2 w przypadku kolejnych transakcji.

Ta metoda akceptuje zarówno pełne zwroty środków (gdzie kwota jest taka sama jak kwota, którą użytkownik zapłacił w pierwotnej transakcji zewnętrznej), jak i częściowe zwroty środków (gdzie kwota jest mniejsza niż kwota, którą użytkownik zapłacił 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ę (QPM) w przypadku wywołań Externaltransactions.createexternaltransaction lub Externaltransactions.refundexternaltransaction. Wywołania Externaltransactions.getexternaltransaction nie są wliczane do tego limitu 1200 zapytań na minutę.