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

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

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

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

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

• Billing and link programs : Programs which facilitate digital content purchases or app downloads outside of Google Play. This includes the alternative billing and external offers programs.
• Внешние API для транзакций : API, используемые для формирования отчетов о транзакциях в рамках соответствующих программ выставления счетов и привязки.
• Внешняя транзакция : Квалифицированная транзакция, совершаемая вне приложения в соответствии с требованиями программы . Сюда входят покупки цифрового контента и загрузки приложений.
• Токен внешней транзакции : токен, предоставляемый библиотекой Play Billing, который вы можете использовать, когда пользователь совершает внешнюю транзакцию. Этот токен используется для уведомления Google Play об успешной внешней транзакции.
• Идентификатор внешней транзакции : уникальный идентификатор, сгенерированный вами для идентификации внешней транзакции.

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

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

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

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

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

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

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

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

Пример :

1. Разработчик настраивает и включает альтернативные способы оплаты в своем приложении.
2. User 1 is in South Korea, a supported country, and is attempting to buy product1 , for 12634.10KRW per month, with a one month free trial offer.
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": "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"
 }
}

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

To report an upgrade or a downgrade when the user owns a subscription in the alternative billing system you use the same endpoint and function in the Externaltransactions API, sending the externalTransactionToken that was provided to the app for the upgrade or downgrade transaction. This works similarly to reporting a new purchase .

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

To report an app install in the external offers billing system, you must call Externaltransactions.createexternaltransaction , sending the externalTransactionToken that was provided to the app. Report this as a zero-cost, one-time transaction; this process is similar to reporting an initial transaction . Be sure to include ExternalOfferDetails in the request body.

Example request :

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

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

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

• An initial transaction with external transaction ID ABC.1234-5678-9012-34567

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

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

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

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

квоты API

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

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