Interfejs Google Play Developer API zawiera teraz dodatkowe funkcje do raportowania transakcji z systemu płatności alternatywnych lub ofert zewnętrznych. Z tego przewodnika dowiesz się, jak zgłaszać transakcje w ramach rozliczeń alternatywnych lub transakcje z ofertami zewnętrznymi.
Do obsługi zakupów w aplikacji z backendu może być potrzebnych kilka komponentów. Aby je utworzyć, musisz skonfigurować integrację backendu zgodnie z opisem w artykule Konfigurowanie interfejsu Google Play Developer API. W przypadku wszystkich funkcji backendu dla programistów, które nie są związane z alternatywnymi rozliczeniami ani interfejsami API ofert zewnętrznych, obowiązują instrukcje z dokumentacji systemu rozliczeniowego Google Play.
Zgłoś nowe transakcje zewnętrzne w Google Play
Integracja z Externaltransactions APIs pozwala raportować transakcje w obsługiwanych krajach poza systemem rozliczeniowym Google Play, w tym transakcje za 0 USD wynikające z zakupów w ramach bezpłatnego okresu próbnego. Transakcje dotyczące rozliczeń alternatywnych i ofert zewnętrznych powinny być inicjowane i raportowane w przypadku kwalifikujących się krajów użytkowników tylko w ramach programów alternatywnych rozliczeń 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ższą lub niższą wersję usługi.
Zewnętrzne raportowanie transakcji
Aby zgłosić transakcję zewnętrzną, wywołaj Externaltransactions API po autoryzacji płatności za pomocą alternatywnego systemu rozliczeniowego lub systemu ofert zewnętrznych. Dotyczy to wszystkich transakcji, w tym opłat początkowych, odnowień, zwrotów środków i innych. Wszystkie transakcje należy zgłaszać w ciągu 24 godzin od ich wystąpienia.
Każda transakcja zewnętrzna jest raportowana z użyciem zewnętrznego identyfikatora transakcji. W przypadku zakupów cyklicznych (np. subskrypcji odnawianych automatycznie) musisz wysyłać zewnętrzny identyfikator transakcji powiązany z pierwszą transakcją w ramach zakupu cyklicznego jako parametr przy kolejnych transakcjach, w tym zwrotach środków. Rejestruje serię transakcji związanych z danym zakupem. Nowy zewnętrzny identyfikator transakcji wysyłasz w przypadku zakupów, gdy produkt się zmieni (np. zmiana na wyższą lub niższą wersję) albo gdy transakcja cykliczna zostanie anulowana lub wygasła, a później ten sam produkt zostanie ponownie kupiony. W zewnętrznym identyfikatorze transakcji nie możesz podawać żadnych informacji umożliwiających identyfikację osoby ani informacji zastrzeżonych ani poufnych.
Zgłaszanie nowego zakupu
Za każdym razem, gdy nowy zakup w systemie rozliczeń alternatywnych lub ofert zewnętrznych zakończy się sukcesem, wymagane jest wywołanie interfejsu API Externaltransactions. W przypadku tych nowych zakupów musisz podać jako parametr zapytania unikalny identyfikator externalTransactionId powiązany z zakupem w backendzie. Elementu externalTransactionId nie można użyć ponownie w ramach identyfikatora pakietu tej samej aplikacji.
Element externalTransactionToken otrzymany przez aplikację za pomocą wywołań zwrotnych UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener lub ExternalOfferReportingDetailsListener jest też wymagany jako część treści żądania w przypadku zakupów jednorazowych i pierwszych transakcji w przypadku zakupu cyklicznego (np. subskrypcji). W obu przypadkach jest to początkowa transakcja. Po początkowej transakcji parametr externalTransactionToken nie jest już potrzebny, a kolejne transakcje (np. odnowienia subskrypcji) są raportowane przez podanie nowego unikalnego parametru externalTransactionId. Więcej informacji o zgłaszaniu kolejnych transakcji znajdziesz w sekcji Raportowanie kolejnych transakcji zakupu.
Przykład:
- Deweloper konfiguruje w aplikacji rozliczenia alternatywne i włącza je.
- Użytkownik 1 znajduje się w obsługiwanym kraju Korei Południowej i próbuje kupić usługę
product1za 12 634,10 KRW miesięcznie w ramach miesięcznej oferty bezpłatnego okresu próbnego. - Aplikacja uruchamia proces zakupu za pomocą
ProductDetailsproduct1i 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 kupione produkty). Następnie rozpoczyna proces zakupu usługiproduct1w alternatywnym systemie rozliczeniowym. Do tej transakcji po stronie dewelopera jest przypisywany unikalny identyfikator, który służy do zgłaszania jej w Google Play: 123-456-789. Identyfikator transakcji jest wymagany, mimo że użytkownik korzysta z bezpłatnej wersji próbnej. - Gdy transakcja zakupu ma miejsce w alternatywnym systemie rozliczeniowym, deweloper zgłasza ją do Google Play za pomocą następującego żądania. Początkowo jest ona podawana jako transakcja za 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"
}
}
W przypadku transakcji z użytkownikiem mieszkającym w Indiach, gdzie podatki różnią się w zależności od obszaru administracyjnego (np. stanu lub prowincji), pamiętaj, by uwzględnić ten obszar w polu userTaxAddress. Zapoznaj się ze wstępnie zdefiniowanymi ciągami znaków w przewodniku po interfejsie API dla odpowiednich obszarów administracyjnych.
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"
}
}
Raportowanie kolejnych transakcji zakupu
W niektórych przypadkach z tym samym zakupem zewnętrznym jest powiązana więcej niż 1 płatność za użytkownika (np. odnowienie subskrypcji lub doładowanie abonamentu przedpłaconego).
Możesz zgłaszać te kolejne transakcje, korzystając z tego samego interfejsu API w Externaltransactions. Zgodnie z opisem w sekcji Zgłaszanie nowego zakupu klucz externalTransactionToken nie jest potrzebny do kolejnych transakcji. Zamiast tego jako parametr zapytania dla każdej transakcji odnowienia lub doładowania wysyłany jest nowy unikalny identyfikator externalTransactionId, a identyfikator początkowej transakcji podany w polu initialExternalTransactionId.
Nawiązując do poprzedniego przykładu:
- Pierwsze odnowienie konta użytkownika 1 ma miejsce w alternatywnym systemie rozliczeniowym. Początkowy identyfikator transakcji to 123-456-789.
- Deweloper zgłasza powtarzanie transakcji w parametrze zapytania adresu URL jako zewnętrzny identyfikator tej nowej transakcji, a w polu
initialExternalTransactionIdpodaje zewnętrzny identyfikator transakcji początkowej.
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ę usługi, gdy użytkownik jest właścicielem subskrypcji w alternatywnym systemie rozliczeniowym, użyj tego samego punktu końcowego i funkcji w interfejsie API Externaltransactions, wysyłając externalTransactionToken, który został przekazany aplikacji na potrzeby transakcji przejścia na wyższą lub niższą wersję usługi. Działa to podobnie do zgłaszania nowego zakupu.
Przejście z ręcznego raportowania transakcji w ramach rozliczeń alternatywnych
Aby przenieść aktywne subskrypcje, które rozpoczęły się w czasie, gdy oferowano rozliczenia alternatywne bez automatycznego raportowania, utwórz nową transakcję zerową za pomocą pola migratedTransactionProgram, zamiast podawać wartość initialExternalTransactionId lub externalTransactionToken. Ustaw transactionTime na godzinę, w której użytkownik po raz pierwszy zarejestrował się w każdej aktywnej subskrypcji. Następnie zgłoś każdą kolejną transakcję dotyczącą tych subskrypcji za pomocą interfejsów API, podając przy tym wartość initialExternalTransactionId używaną powyżej do utworzenia transakcji odnowienia.
Po przeniesieniu subskrypcji nie musisz już ręcznie raportować kolejnych transakcji związanych z subskrypcją, o ile są one raportowane za pomocą zautomatyzowanych metod opisanych na tej stronie.
Podczas przenoszenia subskrypcji zwróć uwagę na obowiązujące limity, aby mieć pewność, że migracja nie spowoduje przerw w działaniu limitów. 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 przechodzenia z raportowania ręcznego. Zostanie ona wycofana, gdy ręczne raportowanie 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"
}
}
Zgłaszanie zwrotów za zakupy do Google Play
Zintegruj interfejs API Externaltransactions, aby raportować transakcje, których środki zostały zwrócone użytkownikom spoza systemu rozliczeniowego Google Play. Aby usługa Google Play mogła poprawnie zidentyfikować transakcję, za którą został przyznany zwrot środków, w parametrach adresu URL musisz podać odpowiednią wartość externalTransactionId w przypadku wcześniej zgłoszonej transakcji.
Zgłaszając zwroty środków za zakup subskrypcji, podaj externalTransactionId konkretnego powtórzenia subskrypcji, za którą przysługuje zwrot środków.
Przykład: załóżmy, że subskrypcja obejmuje te transakcje:
- Pierwsza transakcja z zewnętrznym identyfikatorem transakcji ABC.1234-5678-9012-34567
- Pierwsza transakcja cykliczna o zewnętrznym identyfikatorze transakcji ABC.1234-5678-9012-34567..0
- druga transakcja cykliczna o zewnętrznym identyfikatorze transakcji ABC.1234-5678-9012-34567..1.
Aby zgłosić zwrot środków za wszystkie transakcje dotyczące subskrypcji, musisz przesłać 3 osobne prośby o zwrot środków: jedną za pierwszą transakcję i dwa za kolejne.
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 (jeśli kwota jest niższa niż kwota, którą użytkownik zapłacił w pierwotnej transakcji zewnętrznej). W przypadku częściowego zwrotu środków musisz określić kwotę, która została zwrócona przed naliczeniem podatku.
Limity interfejsu API
Interfejs Externaltransactions API podlega dziennym limitom interfejsu API w przypadku wszystkich wywołań, tak jak każdy inny punkt końcowy w interfejsie Google Play Developer API.
Dodatkowo w interfejsie API Externaltransactions obowiązuje limit 1200 zapytań na minutę w przypadku wywołań do Externaltransactions.createexternaltransaction lub Externaltransactions.refundexternaltransaction. Wywołania Externaltransactions.getexternaltransaction nie wliczają się do limitu 1200 QPM.