Руководство по внутренней интеграции для монетизации за пределами Google Play Billing

API разработчика Google Play включает дополнительные функции для отчётности по транзакциям из биллинговых и связующих программ. В этом руководстве описывается, как отчётность по транзакциям из этих биллинговых программ.

Для обработки внешних транзакций из вашего бэкенда может потребоваться несколько компонентов. Для их реализации необходимо настроить интеграцию с бэкендом, как указано в разделе «Настройка API разработчика Google Play» . Чтобы реализовать функциональность бэкенда для разработчиков, не связанную с биллингом и связыванием программ, см. раздел «Биллинговая система Google Play» .

Глоссарий терминов

Условные обозначения, используемые в данном руководстве:

• Программы выставления счетов и ссылок : программы, облегчающие покупку цифрового контента или загрузку приложений вне Google Play. Сюда входят альтернативные программы выставления счетов и внешние предложения .
• API внешних транзакций : API, используемые для сообщения о транзакциях для соответствующих программ выставления счетов и связей.
• Внешняя транзакция : транзакция, соответствующая условиям программы и происходящая вне приложения. Сюда входят покупка цифрового контента и загрузка приложений.
• Токен внешней транзакции : токен, предоставляемый через Play Billing Library, который вы можете использовать при завершении пользователем внешней транзакции. Этот токен используется для уведомления Google Play об успешной внешней транзакции.
• Внешний идентификатор транзакции : уникальный идентификатор, сгенерированный вами для идентификации внешней транзакции.

Сообщить о новых внешних транзакциях в Google Play

Интеграция с API externaltransactions позволяет сообщать о транзакциях, происходящих вне биллинговой системы Google Play в поддерживаемых странах, включая транзакции без оплаты, связанные с покупками бесплатных пробных версий и установками приложений. Вам следует запускать и сообщать о транзакциях в биллинговых и связующих программах только в странах, соответствующих требованиям к пользователям, в соответствии с правилами альтернативного биллинга или внешних предложений ; в противном случае вызов API будет отклонен. Это относится ко всем транзакциям, включая новые покупки, продления, пополнения, обновления, понижения и загрузки приложений.

Внешняя отчетность по транзакциям

После авторизации платежа через программу выставления счетов и привязки подписки необходимо вызвать API externaltransactions , чтобы сообщить о внешней транзакции. Это относится ко всем транзакциям, включая первоначальные списания, продления, возвраты и т.д. Требования к отчетности см. в руководстве по соответствующей программе выставления счетов и привязки подписки.

Каждая внешняя транзакция регистрируется с внешним идентификатором транзакции. Для повторяющихся покупок (например, автоматически продлеваемых подписок) необходимо отправлять внешний идентификатор транзакции, связанный с первой транзакцией в повторяющейся покупке, в качестве параметра для всех последующих транзакций, включая возвраты. При этом регистрируется серия транзакций для данной покупки. Вам следует отправлять новый внешний идентификатор транзакции при изменении продукта (например, при переходе на более высокую или более низкую версию), а также в случае отмены или истечения срока действия повторяющейся транзакции и повторной покупки того же продукта. В этот внешний идентификатор транзакции нельзя включать никакую персональную информацию, служебную или конфиденциальную информацию.

Сообщить о первоначальной транзакции

Каждый раз, когда новая покупка или загрузка приложения успешно завершается в программах выставления счетов и ссылок, необходимо вызвать API externaltransactions .

Токен externalTransactionToken полученный приложением через обратные вызовы UserChoiceBillingListener , AlternativeBillingOnlyReportingDetailsListener или BillingProgramReportingDetailsListener требуется в качестве части тела запроса для загрузки приложения, разовых покупок и первых транзакций в рамках повторяющейся покупки (например, подписки). Это называется начальной транзакцией (initial transaction ). После начальной транзакции сообщайте о последующих транзакциях (например, о продлении подписки), предоставляя новый уникальный идентификатор externalTransactionId . Подробнее о том, как сообщать о последующих транзакциях, см. в разделе «Сообщение о последующих транзакциях для покупки» .

Пример :

1. Разработчик настраивает и включает альтернативный биллинг в своем приложении.
2. Пользователь 1 находится в Южной Корее, поддерживаемой стране, и пытается купить product1 за 12634,10 KRW в месяц с предложением на один месяц бесплатной пробной версии.
3. Приложение запускает процесс покупки с ProductDetails для product1 и предложения, которое выбрал пользователь.
4. Пользователь 1 выбирает альтернативную биллинговую систему разработчика.
5. UserChoiceBillingListener получает значение my_token как externalTransactionToken .
6. Затем разработчик отправляет соответствующую информацию в свой бэкенд (значение externalTransactionToken и список приобретаемых товаров). После этого он запускает процесс покупки product1 в альтернативной биллинговой системе. На стороне разработчика этой транзакции присваивается уникальный идентификатор, который используется для отправки данных в Google Play: 123-456-789 . Указание идентификатора транзакции обязательно, даже если пользователь получает бесплатную пробную версию.
7. После того, как транзакция покупки совершается в альтернативной платежной системе, разработчик отправляет в Google Play следующий запрос. Изначально транзакция регистрируется как транзакция на сумму 0 долларов, поскольку пользователь получает бесплатный месяц.

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

При сообщении о первоначальной транзакции имейте в виду следующее:

• subscriptionType может быть RECURRING (для автоматически продлеваемых подписок) или PREPAID (для предоплаченных подписок).
• Для представления разовых покупок, требующих нескольких платежей или отложенного платежа, необходимо использовать OtherRecurringProduct . Например, предварительный заказ может включать первоначальную транзакцию на сумму 0 долларов США, за которой после завершения предзаказа может последовать вторая транзакция по цене товара, указанной в заказе. Подробнее об отчёте о последующих транзакциях см. в разделе «Отчёт о последующих транзакциях для покупки» .
• При отчёте о первоначальных транзакциях по внешнему предложению необходимо предоставить сведения ExternalOfferDetails . Для последующих транзакций это не требуется.

Если вы взаимодействуете с пользователем из Индии, где налог зависит от административного района (например, штата или провинции), укажите этот район в поле userTaxAddress . Сведения о применимых административных районах см. в предварительно заданном списке строк в справочном руководстве по 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"
 }
}

Внешние предложения

Если сообщаемая транзакция относится к программе внешних предложений, необходимо задать поле externalOfferDetails , если транзакция является разовой транзакцией или первой транзакцией повторяющейся серии:

• При отчёте о загрузках приложений установите для linkType LINK_TO_APP_DOWNLOAD и укажите соответствующие значения для installedAppPackage и installedAppCategory . Подробнее см. в разделе «Отчёт о загрузке приложения» .
• При сообщении о транзакциях по предложению цифрового контента установите linkType на LINK_TO_DIGITAL_CONTENT .
• После установки внешнего приложения через программу внешних предложений необходимо сообщить о транзакциях, совершённых во внешнем приложении. При этом необходимо связать эти транзакции с событием загрузки исходного приложения:
  • Предоставьте externalTransactionToken из события загрузки приложения.
  • В поле externalOfferDetails укажите appDownloadEventExternalTransactionId равным externalTransactionId события загрузки приложения. Остальные поля в externalOfferDetails не обязательны для заполнения.

Пример запроса на транзакцию во внешнем приложении, загруженном через внешние предложения:

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

Обновленную информацию о комиссии за обслуживание Play для различных типов транзакций можно найти в разделе Изменения в программе внешних предложений для пользователей в Европейской экономической зоне (ЕЭЗ).

Сообщить о последующих транзакциях по покупке

В некоторых случаях с одной и той же внешней покупкой связано несколько платежей пользователя, например, продление подписки или пополнение предоплаченного тарифа. Вы можете сообщить об этих последующих транзакциях, используя тот же API в разделе Externaltransactions . Как описано в разделе «Сообщение о новой покупке» , externalTransactionToken не требуется для последующих транзакций. Вместо этого в качестве параметра запроса для каждой транзакции продления или пополнения отправляется новый уникальный externalTransactionId , при этом идентификатор начальной транзакции включается в поле initialExternalTransactionId .

Следуя предыдущему примеру :

1. Первое продление подписки Пользователя 1 происходит в альтернативной биллинговой системе. Первоначальный идентификатор транзакции — 123-456-789 .
2. Разработчик сообщает о повторении транзакции в параметре запроса URL как о внешнем идентификаторе транзакции для этой новой транзакции, при этом ссылаясь на внешний идентификатор транзакции исходной транзакции в поле initialExternalTransactionId .

Пример запроса :

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

Сообщить об обновлении или понижении

Чтобы сообщить об обновлении или понижении тарифного плана, если у пользователя есть подписка в альтернативной системе оплаты, вы используете ту же конечную точку и функцию в API Externaltransactions , отправляя externalTransactionToken , который был предоставлен приложению для транзакции обновления или понижения тарифного плана. Это работает аналогично сообщению о новой покупке .

Сообщить о загрузке приложения

Чтобы сообщить об установке приложения в системе выставления счетов за внешние предложения, необходимо вызвать метод Externaltransactions.createexternaltransaction , отправив предоставленный приложению externalTransactionToken . Сообщите об этом как о разовой транзакции с нулевой стоимостью; этот процесс аналогичен сообщению о первоначальной транзакции . Обязательно включите ExternalOfferDetails в тело запроса.

Пример запроса :

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

Переход от ручной отчетности по альтернативным платежным транзакциям

Чтобы перенести активные подписки, начатые в период, когда вы предлагали альтернативный биллинг без автоматической отчётности, создайте новую транзакцию с нулевой стоимостью, используя поле migratedTransactionProgram вместо указания initialExternalTransactionId или externalTransactionToken . Установите для transactionTime время первоначальной регистрации пользователя для каждой активной подписки. После этого сообщайте о каждой последующей транзакции по этим подпискам как обычно через API, предоставляя initialExternalTransactionId который использовался ранее для создания транзакций продления. После переноса подписки вам больше не придётся вручную сообщать о последующих транзакциях по подписке, при условии, что они сообщаются с помощью автоматизированных методов, описанных на этой странице.

При переносе подписок учитывайте установленные квоты , чтобы убедиться, что миграция не приведёт к сбою квоты. Если необходимо перенести много подписок, распределите их на несколько дней или запросите увеличение квоты .

Поле migratedTransactionProgram можно использовать только при переходе с ручного создания отчётов. Оно будет упразднено после прекращения поддержки ручного создания отчётов.

Пример запроса :

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

Требования к партнерским программам Play

Разработчики, участвующие в партнерских программах, таких как Play Media Experience Program, обязаны предоставлять поле transaction_program_code при отчёте о внешних транзакциях. Если вы являетесь соответствующим разработчиком, обратитесь к своему менеджеру по развитию бизнеса за дополнительной информацией о настройке этого поля.

Сообщить о возврате средств за покупку в Google Play

Интегрируйтесь с API externaltransactions , чтобы сообщать о транзакциях, возврат средств пользователям, не являющимся пользователями Google Play. Чтобы Google Play правильно определял, какая транзакция была возвращена, необходимо включить соответствующий externalTransactionId для ранее зарегистрированной транзакции в параметры URL.

При сообщении о возврате средств за подписку указывайте externalTransactionId конкретного повторения подписки, по которой производится возврат.

Пример : Предположим, что подписка имеет следующие транзакции:

• Первоначальная транзакция с внешним идентификатором транзакции ABC.1234-5678-9012-34567

• Первая повторяющаяся транзакция с внешним идентификатором транзакции ABC.1234-5678-9012-34567..0

• Вторая повторяющаяся транзакция с внешним идентификатором транзакции ABC.1234-5678-9012-34567..1

Чтобы сообщить о возврате средств по всем транзакциям за подписку, вам необходимо подать три отдельных запроса на возврат средств: один по первоначальной транзакции и два по последующим транзакциям.

Этот метод допускает как полный возврат средств (сумма которого равна сумме, уплаченной пользователем в исходной внешней транзакции), так и частичный возврат средств (сумма которого меньше суммы, уплаченной пользователем в исходной внешней транзакции). Для частичного возврата необходимо указать сумму возврата до вычета налогов.

API-квоты

API Externaltransactions подчиняется квотам API для всех вызовов, как и любая другая конечная точка в API разработчика Google Play.

Кроме того, API Externaltransactions имеет ограничение в 1200 запросов в минуту (QPM) для вызовов Externaltransactions.createexternaltransaction или Externaltransactions.refundexternaltransaction . Вызовы Externaltransactions.getexternaltransaction не учитываются в этом ограничении в 1200 запросов в минуту (QPM).