Google Play Developer API zawiera dodatkowe funkcje do raportowania transakcji z programów rozliczeniowych i linków. Z tego przewodnika dowiesz się, jak zgłaszać 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ę backendu zgodnie z instrukcjami podanymi w artykule Konfigurowanie interfejsu Google Play Developer API. Aby utworzyć funkcje backendu dewelopera, które nie są związane z rozliczeniami i programami linków, zapoznaj się z informacjami o systemie rozliczeniowym Google Play.
Słowniczek terminów
Konwencje terminologiczne stosowane w tym przewodniku:
- Programy dotyczące płatności i 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 dostarczany przez Bibliotekę płatności Play, którego możesz użyć, gdy użytkownik inicjuje transakcję zewnętrzną. Ten token służy do powiadamiania Google Play o autoryzowanej transakcji zewnętrznej.
- Identyfikator transakcji zewnętrznej: unikalny identyfikator wygenerowany przez Ciebie w celu identyfikacji transakcji zewnętrznej.
Konfigurowanie uprawnień w Konsoli Play
Aby wywołać interfejs API externaltransactions w celu zgłoszenia transakcji zewnętrznych lub zwrócenia za nie środków, przyznaj swojemu kontu usługi uprawnienie Zarządzanie zamówieniami i subskrypcjami w Konsoli Google Play. Możesz przyznać to uprawnienie na poziomie konta lub w przypadku konkretnych aplikacji.
Instrukcje tworzenia konta usługi i przyznawania uprawnień w Konsoli Play znajdziesz w artykule Używanie konta usługi. Więcej informacji o uprawnieniach w Konsoli Play znajdziesz w artykule Dodawanie użytkowników konta dewelopera i zarządzanie uprawnieniami.
Zgłaszanie nowych transakcji zewnętrznych do Google Play
Zintegruj się z interfejsem API externaltransactions, aby raportować transakcje realizowane 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 programach linków należy rozpoczynać i zgłaszać tylko w przypadku krajów, w których użytkownicy są uprawnieni do korzystania z tych programó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 pobrań aplikacji.
Raportowanie transakcji zewnętrznych
Aby zgłosić transakcję zewnętrzną, po autoryzacji płatności w ramach programu rozliczeń i linków należy wywołać 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 raportowana z identyfikatorem transakcji zewnętrznej. W przypadku zakupów cyklicznych (takich jak automatycznie odnawiane subskrypcje) musisz wysłać identyfikator transakcji zewnętrznej powiązany z pierwszą transakcją w ramach zakupu cyklicznego jako parametr wszystkich kolejnych transakcji, w tym zwrotów środków. Spowoduje to zarejestrowanie serii transakcji związanych z tym zakupem. W przypadku zakupów, gdy produkt się zmienia (np. następuje przejście na wyższą lub niższą wersję) albo gdy transakcja cykliczna zostanie anulowana lub wygaśnie, a ten sam produkt zostanie później kupiony ponownie, należy wysłać nowy identyfikator transakcji zewnętrznej. Identyfikator transakcji zewnętrznej nie może zawierać ż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 API externaltransactions.
Parametr externalTransactionToken otrzymany przez aplikację z Biblioteki płatności w Google Play jest wymagany w treści żądania w przypadku pobrań aplikacji, zakupów jednorazowych i pierwszych transakcji w ramach zakupów cyklicznych (np. subskrypcji). Jest to tzw. transakcja początkowa. Po pierwszej transakcji zgłaszaj kolejne transakcje (np. odnowienia subskrypcji), podając nowy unikalny parametr externalTransactionId. Więcej informacji znajdziesz w artykule Raportowanie kolejnych transakcji po zakupie.
Przykład:
- Deweloper konfiguruje i włącza rozliczenia alternatywne w swojej aplikacji.
- Użytkownik 1 znajduje się w Korei Południowej, czyli w obsługiwanym kraju, i próbuje kupić
product1za 12 634,10 KRW miesięcznie z ofertą miesięcznego bezpłatnego okresu próbnego. - Aplikacja uruchamia proces zakupu z użyciem
ProductDetailsdlaproduct1i oferty wybranej przez użytkownika. - Użytkownik 1 wybiera alternatywny system rozliczeniowy dewelopera.
UserChoiceBillingListenerotrzymuje wartośćmy_tokenjakoexternalTransactionToken.- Następnie deweloper wysyła odpowiednie informacje do swojego backendu (wartość
externalTransactionTokeni kupowane produkty). Następnie uruchamia proces zakupu produktuproduct1w alternatywnym systemie rozliczeniowym. Tej transakcji przypisano unikalny identyfikator transakcji po stronie dewelopera, 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. - Po dokonaniu 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 raportowania pierwszej transakcji pamiętaj o tych kwestiach:
subscriptionTypemoże mieć wartośćRECURRING(w przypadku subskrypcji odnawianych automatycznie) lubPREPAID(w przypadku subskrypcji przedpłaconych).- Atrybut
OtherRecurringProductmusi być używany do reprezentowania jednorazowych zakupów, które wymagają wielu płatności lub płatności odroczonej. Na przykład zamówienie w przedsprzedaży może mieć początkową transakcję o wartości 0 USD, po której następuje druga transakcja w późniejszym terminie, w cenie SKU, gdy zamówienie w przedsprzedaży zostanie zrealizowane. Więcej informacji o raportowaniu kolejnych transakcji znajdziesz w sekcji Raportowanie kolejnych transakcji dotyczących zakupu. - Podczas zgłaszania początkowych transakcji z ofert zewnętrznych musisz podać
ExternalOfferDetails. Nie jest to wymagane w przypadku kolejnych transakcji.
Jeśli przeprowadzasz transakcję z użytkownikiem w Indiach, gdzie podatek zależy od regionu administracyjnego (np. stanu lub prowincji), podaj ten region w polu userTaxAddress. W przewodniku po interfejsie API znajdziesz wstępnie zdefiniowaną listę ciągów znaków dla odpowiednich regionów.
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 transakcja jest jednorazowa lub jest pierwszą transakcją z serii cyklicznej:
- Podczas raportowania transakcji pobrania aplikacji ustaw parametr
linkTypenaLINK_TO_APP_DOWNLOADi podaj odpowiednie wartości parametrówinstalledAppPackageiinstalledAppCategory. Więcej informacji znajdziesz w artykule Zgłaszanie pobrania aplikacji. - Podczas raportowania transakcji dotyczących ofert treści cyfrowych ustaw parametr
linkTypenaLINK_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
externalTransactionTokenze zdarzenia pobrania aplikacji. - W polu
externalOfferDetailsustawappDownloadEventExternalTransactionIdnaexternalTransactionIdzdarzenia pobrania aplikacji. Inne pola w plikuexternalOfferDetailsnie są wymagane.
- Podaj
Przykładowa prośba o transakcję 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 Usługi Google Play w przypadku różnych typów transakcji znajdziesz w artykule Zmiany w programie ofert zewnętrznych dotyczące użytkowników z Europejskiego Obszaru Gospodarczego.
Raportowanie kolejnych transakcji związanych z zakupem
W niektórych przypadkach z tym samym zakupem zewnętrznym jest powiązanych kilka płatności użytkownika, np. odnowienia subskrypcji lub doładowania abonamentu przedpłaconego.
Możesz zgłaszać te kolejne transakcje, używając tego samego interfejsu API w Externaltransactions. Jak opisano w sekcji Zgłaszanie nowego zakupu, parametr externalTransactionToken nie jest wymagany w przypadku kolejnych transakcji. Zamiast tego dla każdej transakcji odnowienia lub doładowania wysyłany jest nowy unikalny parametr externalTransactionId jako parametr zapytania, a identyfikator początkowej transakcji jest zawarty w polu initialExternalTransactionId.
Wracając do poprzedniego przykładu:
- Pierwsze odnowienie subskrypcji użytkownika 1 następuje w alternatywnym systemie rozliczeniowym. Identyfikator pierwszej transakcji to 123-456-789.
- Deweloper zgłasza powtarzanie transakcji w parametrze zapytania adresu URL jako identyfikator transakcji zewnętrznej dla tej nowej transakcji, odwołując się jednocześnie do identyfikatora transakcji zewnętrznej początkowej transakcji w polu
initialExternalTransactionId.
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 przejścia na wyższą lub niższą wersję
Aby zgłosić przejście na wyższą lub niższą wersję, gdy użytkownik ma subskrypcję w alternatywnym systemie rozliczeniowym, użyj tego samego punktu końcowego i funkcji w interfejsie API Externaltransactions, wysyłając parametr externalTransactionToken, który został przekazany aplikacji na potrzeby transakcji przejścia na wyższą lub 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ć metodę Externaltransactions.createexternaltransaction, wysyłając parametr externalTransactionToken, który został przekazany aplikacji. Zgłoś to jako bezpłatną transakcję jednorazową. 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 zrealizowanych przy użyciu rozliczeń alternatywnych
Aby przenieść aktywne subskrypcje, które rozpoczęły się w okresie, gdy oferowano rozliczenia alternatywne bez automatycznego raportowania, utwórz nową bezpłatną transakcję, używając pola migratedTransactionProgram zamiast podawać initialExternalTransactionId lub externalTransactionToken. Ustaw parametr transactionTime na czas, w którym użytkownik po raz pierwszy zarejestrował się w ramach każdej aktywnej subskrypcji. Następnie zgłaszaj każdą kolejną transakcję dotyczącą tych subskrypcji w zwykły sposób za pomocą interfejsów API, podając parametr initialExternalTransactionId użyty wcześniej do utworzenia transakcji odnowienia.
Po przeniesieniu subskrypcji nie musisz już ręcznie raportować kolejnych transakcji, pod warunkiem że są one raportowane za pomocą metod automatycznych opisanych na tej stronie.
Podczas migracji subskrypcji pamiętaj o obowiązujących limitach limitów, aby upewnić się, że migracja nie spowoduje przerwy w działaniu usługi z powodu przekroczenia limitu. Jeśli musisz przenieść wiele subskrypcji, rozłóż ten proces na kilka dni lub poproś o zwiększenie limitu.
Pola migratedTransactionProgram można używać tylko podczas migracji z raportowania ręcznego. Zostanie wycofana, gdy raportowanie ręczne 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 Google Play
Deweloperzy biorący udział w programach partnerskich, takich jak Play Media Experience, muszą podawać parametr transaction_program_code podczas raportowania transakcji zewnętrznych. Jeśli jesteś kwalifikującym się deweloperem, skontaktuj się z menedżerem ds. rozwoju biznesowego, aby dowiedzieć się, jak ustawić to pole.
Zgłaszanie zwrotów środków za zakupy do Google Play
Zintegruj się z interfejsem API externaltransactions, aby zgłaszać transakcje, za które zwrócono środki użytkownikom poza systemem rozliczeniowym Google Play. Aby usługa Google Play mogła prawidłowo zidentyfikować transakcję, za którą zwrócono środki, w parametrach adresu URL musisz podać odpowiedni parametr externalTransactionId dla wcześniej zgłoszonej transakcji.
Podczas zgłaszania zwrotów środków za zakupy subskrypcji podaj externalTransactionId konkretnego odnowienia subskrypcji, za które zwracane są ś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 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 API Externaltransactions podlega limitom interfejsu API w przypadku wszystkich wywołań, podobnie 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 z Externaltransactions.getexternaltransaction nie wliczają się do limitu 1200 zapytań na minutę.