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

Interfejs Google Play Developer API zawiera teraz dodatkowe funkcje do raportowania transakcji z systemu rozliczeń alternatywnych lub ofert zewnętrznych. Z tego przewodnika dowiesz się, jak zgłaszać transakcje z użyciem alternatywnego sposobu płatności lub ofert zewnętrznych.

Aby obsługiwać zakupy w aplikacji, możesz potrzebować kilku komponentów na zapleczu. Aby je utworzyć, musisz skonfigurować integrację z backendem zgodnie z instrukcjami w artykule Konfigurowanie interfejsu Google Play Developer API. W przypadku wszystkich funkcji backendu dewelopera, które nie są związane z rozliczeniami alternatywnymi ani interfejsami API ofert zewnętrznych, obowiązują instrukcje z dokumentacji systemu rozliczeniowego Google Play.

Zgłaszanie nowych transakcji zewnętrznych do Google Play

Zintegruj się z Externaltransactions APIs, aby raportować 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łatnych okresów próbnych. Transakcje w systemach rozliczeń alternatywnych lub ofert zewnętrznych powinny być inicjowane i raportowane tylko w odpowiednich krajach, w których jest to dozwolone w ramach programów 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ń, uaktualnień, obniżek i innych.

Raportowanie transakcji zewnętrznych

Aby zgłosić transakcję zewnętrzną, zadzwoń pod numer Externaltransactions API po autoryzacji płatności za pomocą alternatywnego systemu rozliczeniowego lub systemu ofert zewnętrznych. Dotyczy to wszystkich transakcji, w tym początkowych obciążeń, odnowień, zwrotów środków i innych. Wszystkie transakcje należy zgłosić w ciągu 24 godzin od ich dokonania.

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. Zapisują one serię transakcji dotyczących danego zakupu. W przypadku zakupów wysyłasz nowy zewnętrzny identyfikator transakcji, gdy produkt ulega zmianie (np. awansuje lub obniża się), lub gdy transakcja cykliczna zostaje anulowana lub wygasa, a ten sam produkt jest kupowany ponownie w późniejszym terminie. W ramach tego zewnętrznego identyfikatora transakcji nie wolno podawać żadnych informacji umożliwiających identyfikację osoby, informacji zastrzeżonych ani informacji poufnych.

Zgłaszanie nowego zakupu

Za każdym razem, gdy w systemie rozliczeń alternatywnych lub ofert zewnętrznych zostanie dokonany nowy zakup, wymagane jest wywołanie interfejsu Externaltransactions API. W przypadku tych nowych zakupów musisz podać wyjątkowy parametr externalTransactionId powiązany z kupnem na zapleczu jako parametr zapytania. Identyfikator externalTransactionId nie może być używany ponownie w ramach tego samego identyfikatora pakietu aplikacji.

Wartość externalTransactionToken otrzymana przez aplikację w wyniku wywołania funkcji UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener lub ExternalOfferReportingDetailsListener jest też wymagana w ciele żądania w przypadku zakupów jednorazowych i pierwszych transakcji w ramach zakupu cyklicznego (np. subskrypcji). W obu przypadkach jest to pierwsza transakcja. Po pierwszej transakcji externalTransactionToken nie jest już potrzebny. Kolejne transakcje (np. odnowienie subskrypcji) możesz raportować, podając nowy unikalny externalTransactionId. Więcej informacji o sposobie zgłaszania kolejnych transakcji znajdziesz w artykule Zgłaszanie kolejnych transakcji związanych z zakupem.

Przykład:

1. Deweloperzy konfigurują i włączają rozliczenia alternatywne w swojej aplikacji.
2. Użytkownik 1 znajduje się w obsługiwanym kraju (Korea Południowa) i próbuje kupić product1 za 12634,10 KRW miesięcznie w ramach 1-miesięcznego bezpłatnego okresu próbnego.
3. Aplikacja uruchamia proces zakupu z ProductDetails dla product1 i ofertą wybraną przez użytkownika.
4. Użytkownik 1 wybiera alternatywny system rozliczeniowy dewelopera.
5. Funkcja UserChoiceBillingListener otrzymuje wartość my_token jako externalTransactionToken.
6. Następnie deweloper wysyła odpowiednie informacje do backendu (wartość externalTransactionToken i kupowane produkty). Następnie uruchamiają proces zakupu product1 w alternatywnym systemie rozliczeniowym. Ta transakcja ma przypisany 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.
7. Po zrealizowaniu transakcji w systemie rozliczeń alternatywnych deweloper zgłasza ją do Google Play za pomocą tej prośby. 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"
 }
}

Uwaga: subscriptionType może być RECURRING (w przypadku subskrypcji automatycznie odnawianych) lub PREPAID (w przypadku subskrypcji przedpłaconych).

Uwaga: OtherRecurringProduct może być używane do reprezentowania jednorazowych zakupów, które wymagają wielu płatności lub opóźnionej płatności. Na przykład w przypadku zamówienia w przedsprzedaży może wystąpić początkowa transakcja o wartości 0 zł, a następnie w późniejszym terminie transakcja o wartości odpowiadającej cenie kodu SKU, gdy zamówienie zostanie zrealizowane. Więcej informacji o raportowaniu kolejnych transakcji znajdziesz w artykule Raportowanie kolejnych transakcji związanych z zakupem.

Uwaga: raportowanie transakcji związanej z zakupem przy użyciu tylko płatności alternatywnych lub ofert zewnętrznych odbywa się w ten sam sposób, co opisano powyżej, z tym że externalTransactionToken jest uzyskiwany zgodnie z instrukcjami podanymi w przewodniku dotyczącym tylko płatności alternatywnych lub ofert zewnętrznych.

Jeśli prowadzisz transakcję z użytkownikiem mieszkającym w Indiach, gdzie podatek zależy od regionu administracyjnego (np. stanu lub prowincji), pamiętaj, aby podać ten region w polu userTaxAddress. Aby poznać listę zdefiniowanych wstępnie ciągów tekstowych w odpowiednich obszarach administracyjnych, zapoznaj się z przewodnikiem 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"
 }
}

Zgłaszanie kolejnych transakcji dotyczących zakupu

W niektórych przypadkach z jednym zakupem zewnętrznym może być powiązanych więcej niż jedno płatne konto użytkownika (np. odnowienia subskrypcji lub doładowania przedpłaconego abonamentu). Możesz zgłaszać te kolejne transakcje, używając tego samego interfejsu API w sekcji Externaltransactions. Jak opisano w artykule Zgłoś nowy zakup, externalTransactionToken nie jest wymagany w przypadku kolejnych transakcji. Zamiast tego nowy niepowtarzalny identyfikator externalTransactionId jest wysyłany jako parametr zapytania w przypadku każdej transakcji odnowienia lub doładowania, a identyfikator pierwotnej transakcji jest dołączany w polu initialExternalTransactionId.

W przykładzie z poprzedniego akapitu:

1. Pierwsze odnowienie subskrypcji przez Użytkownika 1 odbywa się w ramach alternatywnego systemu rozliczeniowego. Początkowy identyfikator transakcji to 123-456-789.
2. Deweloper zgłasza powtórzenie transakcji w parametrze zapytania adresu URL jako identyfikator zewnętrzny nowej transakcji, a w polu initialExternalTransactionId odwołuje się do identyfikatora zewnętrznego pierwotnej transakcji.

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 tej samej funkcji w interfejsie API Externaltransactions, wysyłając externalTransactionToken, który został podany w aplikacji w celu przeprowadzenia transakcji przejścia na wyższą lub niższą wersję. Działa to podobnie do raportowania nowego zakupu.

Przejście z ręcznego raportowania transakcji zrealizowanych za pomocą rozliczeń alternatywnych

Uwaga: ręczne zgłaszanie rozliczeń alternatywnych i systemu rozliczeniowego opartego na wyborze użytkownika jest wycofywane. Więcej informacji o terminach migracji znajdziesz w artykule System rozliczeniowy oparty na wyborze użytkownika w Google Play. Zanim wyłączysz raportowanie ręczne, pamiętaj, aby przenieść wszystkie aktywne subskrypcje, które rozpoczęły się w czasie, gdy oferowano rozliczenia alternatywne bez automatycznego raportowania, za pomocą interfejsu ExternalTransactions API.

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 za pomocą pola migratedTransactionProgram zamiast pola initialExternalTransactionId lub externalTransactionToken. Ustaw parametr transactionTime na czas, w którym użytkownik po raz pierwszy zarejestrował się w przypadku każdej aktywnej subskrypcji. Następnie raportuj każdą kolejną transakcję dotyczącą tych subskrypcji w zwykły sposób za pomocą interfejsów API, podając wartośćinitialExternalTransactionId użytą powyżej do utworzenia transakcji odnowienia. Po przeniesieniu subskrypcji nie musisz już ręcznie raportować kolejnych transakcji dotyczących tej subskrypcji, o ile są one raportowane za pomocą automatycznych metod opisanych na tej stronie.

Podczas przenoszenia subskrypcji pamiętaj o limitach limitów, aby mieć pewność, że migracja nie spowoduje przerwy w dostępie do limitów. Jeśli trzeba przenieść wiele subskrypcji, rozłóż je na kilka dni lub poproś o zwiększenie limitu.

Uwaga: ustawienie pola migratedTransactionProgram będzie możliwe tylko dla deweloperów, którzy oferują alternatywny system rozliczeniowy bez automatycznego raportowania. Jeśli oferujesz rozliczenia alternatywne bez automatyzacji i pojawia się błąd podczas próby przesłania prośby o przeniesienie subskrypcji, skontaktuj się z naszym zespołem pomocy.

Pola migratedTransactionProgram można używać tylko podczas migracji z raportowania manualnego. Zostanie on wycofany, gdy przestanie być obsługiwany raport ręczny.

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 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ś deweloperem kwalifikującym się do korzystania z tej funkcji, skontaktuj się z menedżerem ds. rozwoju biznesu, aby uzyskać więcej informacji o sposobie ustawienia tego pola.

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

Integracja z interfejsem API Externaltransactions w celu raportowania transakcji zwróconych użytkownikom poza systemem rozliczeniowym Google Play. Aby Google Play mogło poprawnie zidentyfikować, która transakcja została zwrócona, w parametrach adresu URL należy podać odpowiedni parametr externalTransactionId dla wcześniej zgłoszonej transakcji.

Podczas zgłaszania zwrotów środków za zakupione subskrypcje podaj identyfikator externalTransactionId konkretnej subskrypcji cyklicznej, za którą ma zostać przyznany zwrot środków.

Przykład: zakładamy, że abonament ma te transakcje:

• Początkowa transakcja z identyfikatorem zewnętrznym ABC.1234-5678-9012-34567
• Pierwsza transakcja cykliczna z identyfikatorem transakcji zewnętrznej ABC.1234-5678-9012-34567..0
• Druga transakcja cykliczna z identyfikatorem zewnętrznym 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ą za pierwszą transakcję i 2 za kolejne transakcje.

Ta metoda umożliwia zarówno pełne zwroty środków (gdzie kwota jest taka sama jak kwota zapłacona przez użytkownika w pierwotnej transakcji zewnętrznej), jak i częściowe zwroty środków (gdzie 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 do dziennych limitów interfejsu API dla wszystkich wywołań, tak jak każdy inny punkt końcowy w interfejsie Google Play Developer API.

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