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

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

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

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

В этом руководстве используются следующие условные обозначения:

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

Как настроить разрешения Play Console

Чтобы вызывать externaltransactions API для передачи данных о внешних транзакциях или возврата средств за них, предоставьте сервисному аккаунту разрешение Управление заказами и подписками в Google Play Console. Это разрешение можно предоставить на уровне аккаунта или для отдельных приложений.

Инструкции по созданию сервисного аккаунта и предоставлению разрешений в Play Console можно найти в статье Как использовать сервисный аккаунт. Дополнительную информацию о разрешениях Play Console можно найти в статье Как добавлять пользователей аккаунта разработчика и управлять разрешениями.

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

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

Отчеты о внешних транзакциях

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

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

Как сообщить о первой транзакции

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

Токен externalTransactionToken, полученный приложением через библиотеку Google Play Платежей, должен быть включен в тело запроса для скачивания приложений, разовых покупок и первых транзакций в рамках регулярных покупок (например, подписок). Это называется первоначальной транзакцией. После первой транзакции сообщайте о последующих (например, о продлении подписки), указывая новый уникальный параметр externalTransactionId. Подробнее о том, как регистрировать последующие транзакции для покупки…

Примеры:

  1. Разработчик настраивает и включает альтернативную платежную систему в своем приложении.
  2. Пользователь 1 находится в Южной Корее, где поддерживается альтернативная платежная система, и пытается купить product1 за 12 634,10 южнокорейской воны в месяц с бесплатным пробным периодом на один месяц.
  3. Приложение запускает процесс покупки с идентификатором ProductDetails для product1 и выбранным пользователем предложением.
  4. Пользователь 1 выбирает альтернативную платежную систему разработчика.
  5. UserChoiceBillingListener получает значение my_token в качестве externalTransactionToken.
  6. Затем разработчик отправляет соответствующую информацию в свой бэкенд (значение externalTransactionToken и приобретаемые товары). Затем они запускают процесс покупки product1 в альтернативной платежной системе. Этой транзакции присваивается уникальный идентификатор транзакции на стороне разработчика, который используется для передачи данных в Google Play: 123-456-789. Идентификатор транзакции обязателен, даже если пользователь получает бесплатную пробную версию.
  7. После того как транзакция будет выполнена в альтернативной платежной системе, разработчик сообщает о ней в Google Play с помощью следующего запроса: Изначально она регистрируется как транзакция с нулевой стоимостью, поскольку пользователь получает бесплатный месяц.
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 долларов США, а затем, когда предзаказ будет выполнен, – вторая транзакция на сумму, равную цене SKU. Подробнее о том, как регистрировать последующие транзакции…
  • При отправке отчетов о первых транзакциях по внешним предложениям необходимо указывать 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_OFFER.
  • После того как пользователь установит внешнее приложение в рамках программы внешних предложений, вы должны сообщать о транзакциях, совершенных в этом приложении. При этом связывайте транзакции с исходным событием скачивания приложения:
    • Укажите externalTransactionToken из события скачивания приложения.
    • В поле externalOfferDetails задайте для параметра appDownloadEventExternalTransactionId значение externalTransactionId события скачивания приложения. Другие поля в externalOfferDetails не являются обязательными.

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

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

Обновленные сведения о комиссионном сборе сервисов Google 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", # 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"
 }
}

Как сообщить о переходе на другую версию

Чтобы сообщить о переходе на другой тарифный план, когда у пользователя есть подписка в альтернативной платежной системе, используйте ту же конечную точку и функцию в Externaltransactions API, отправляя 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"
 }
}

Требования для участия в партнерских программах Google Play

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

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

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

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

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

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

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

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

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

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

Квоты API

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

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