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

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

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

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

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

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

Как сообщать в 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 мог правильно определить, какая транзакция была возвращена, вам нужно добавить соответствующий параметр externalTransactionId для ранее зарегистрированной транзакции в параметры URL.

При возврате средств за подписку указывайте 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 не учитываются в этом ограничении.