Guía de integración de backend para monetización fuera de la Facturación Google Play

La API de Google Play Developer incluye funciones adicionales para informar transacciones de programas de facturación y vínculos. En esta guía, se describe cómo informar transacciones de estos programas de facturación.

Hay algunos componentes que pueden ser necesarios para controlar las transacciones externas desde tu backend. Para compilarlos, debes configurar la integración de backend como se indica en Configura la API de Google Play Developer. Para compilar funciones de backend del desarrollador que no sean específicas de los programas de facturación y vínculos, consulta el sistema de facturación de Google Play.

Glosario de términos

Convenciones de términos que se siguen en esta guía:

  • Programas de facturación y vínculos: Son programas que facilitan las compras de contenido digital o las descargas de apps fuera de Google Play. Esto incluye los programas de facturación alternativa y de contenido externo.
  • APIs de transacciones externas: Son APIs que se usan para informar transacciones de programas de facturación y vínculos aptos.
  • Transacción externa: Es una transacción apta que se produce fuera de la app, según lo definen los programas de facturación alternativa y de contenido externo.
  • Token de transacción externa: Es un token que se proporciona a través de la Biblioteca de Facturación Play para que lo uses cuando el usuario inicia una transacción externa. Este token se usa para notificar a Google Play sobre una transacción externa autorizada.
  • ID de transacción externa: Es un identificador único que generas para identificar una transacción externa.

Cómo informar nuevas transacciones externas a Google Play

Integra con la API de externaltransactions para informar transacciones que ocurran fuera del sistema de facturación de Google Play en países admitidos, incluidas las transacciones de USD 0 que resulten de compras de pruebas gratuitas y de instalaciones de apps. Solo debes iniciar e informar transacciones en programas de facturación y vinculación para los países de los usuarios que cumplen con los requisitos según lo permitido en los programas de facturación alternativa y de contenido externo; de lo contrario, se rechazará la llamada a la API. Esto se aplica a todas las transacciones, incluidas las compras nuevas, las renovaciones, las recargas, las actualizaciones, los cambios a versiones inferiores y las descargas de apps.

Informes de transacciones externas

Debes llamar a la API de externaltransactions para informar una transacción externa después de que se autorizó el pago a través de un programa de facturación y vínculos. Esto se aplica a todas las transacciones, incluidos los cargos iniciales, las renovaciones, los reembolsos y otros. Consulta los lineamientos del programa de facturación y vínculos correspondiente para conocer los requisitos de informes.

Cada transacción externa se informa con un ID de transacción externo. En el caso de las compras recurrentes (como las suscripciones con renovación automática), debes enviar el ID de transacción externo asociado con la primera transacción en la compra recurrente como un parámetro para las transacciones posteriores, incluidos los reembolsos. Esto registra la serie de transacciones para esa compra. Envías un nuevo ID de transacción externo para las compras cuando cambia el producto (como una actualización o un cambio a una versión inferior) o si la transacción recurrente se cancela o vence, y el mismo producto se vuelve a comprar más tarde. No debes incluir información de identificación personal ni información confidencial o de propiedad como parte de este ID de transacción externo.

Cómo informar una transacción inicial

Cada vez que se autoriza una compra nueva o una descarga de app en programas de facturación y vínculos, debes llamar a la API de externaltransactions.

El externalTransactionToken que recibe la app a través de la Biblioteca de Facturación Google Play es obligatorio como parte del cuerpo de la solicitud para descargas de apps, compras únicas y transacciones por primera vez en una compra recurrente (como una suscripción). Esto se denomina transacción inicial. Después de la transacción inicial, informa las transacciones posteriores (como las renovaciones de suscripción) si proporcionas un nuevo externalTransactionId único. Para obtener más información, consulta Cómo informar transacciones posteriores de una compra.

Ejemplo:

  1. Un desarrollador configura y habilita la facturación alternativa en su app.
  2. El Usuario 1 se encuentra en Corea del Sur, un país admitido, y está intentando comprar product1 por KRW 12, 634.10 al mes, con una oferta de prueba gratuita de un mes.
  3. La app inicia el flujo de compra con el ProductDetails para product1 y la oferta que seleccionó el usuario.
  4. El Usuario 1 selecciona el sistema alternativo de facturación del desarrollador.
  5. UserChoiceBillingListener recibe el valor my_token como externalTransactionToken.
  6. Luego, el desarrollador envía la información pertinente a su backend (valor de externalTransactionToken y los productos que están comprando). Luego, inicia el flujo de compra de product1 en el sistema alternativo de facturación. A esta transacción se le asigna un ID de transacción único del lado del desarrollador que se usa para informarlo a Google Play: 123-456-789. El ID de transacción es obligatorio, aunque el usuario esté recibiendo una prueba gratuita.
  7. Una vez realizada la transacción en el sistema alternativo de facturación, el desarrollador informa la transacción a Google Play con la siguiente solicitud. Inicialmente, se informa como una transacción sin costo, ya que el usuario obtiene un mes gratis.
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"
 }
}

Cuando informes una transacción inicial, ten en cuenta lo siguiente:

  • subscriptionType puede ser RECURRING (para suscripciones con renovación automática) o PREPAID (para suscripciones prepagadas).
  • Se debe usar OtherRecurringProduct para representar compras únicas que requieren varios pagos o un pago diferido. Por ejemplo, un pedido anticipado podría tener una transacción inicial de USD 0 seguida de una segunda transacción en una fecha posterior por el precio de la SKU cuando se cumpla el pedido anticipado. Consulta Cómo informar transacciones posteriores de una compra para obtener más detalles sobre cómo informar transacciones posteriores.
  • Debes proporcionar ExternalOfferDetails cuando informes transacciones iniciales de ofertas externas. Esto no es obligatorio para las transacciones posteriores.

Si realizas transacciones con un usuario en India, donde el impuesto depende de su área administrativa (como un estado o una provincia), incluye esa área en userTaxAddress. Consulta la lista predefinida de cadenas en la guía de referencia de la API para conocer las áreas administrativas aplicables.

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

Ofertas externas

Si la transacción que se informa está en el programa de ofertas externas, debes establecer el campo externalOfferDetails si la transacción es única o la primera de una serie recurrente:

  • Cuando informes transacciones de descarga de apps, establece linkType en LINK_TO_APP_DOWNLOAD y proporciona los valores adecuados para installedAppPackage y installedAppCategory. Consulta Cómo informar una descarga de app para obtener más detalles.
  • Cuando informes transacciones de ofertas de contenido digital, establece linkType en LINK_TO_DIGITAL_CONTENT_OFFER.
  • Después de instalar una app externa a través del programa de ofertas externas, debes informar las transacciones realizadas en la app externa. Cuando informes estas transacciones, vincúlalas al evento de descarga de la app original:
    • Proporciona el externalTransactionToken del evento de descarga de la app.
    • En el campo externalOfferDetails, establece appDownloadEventExternalTransactionId en el externalTransactionId del evento de descarga de la app. No se requieren otros campos en externalOfferDetails.

Ejemplo de solicitud de transacción en una app externa descargada a través de ofertas externas:

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

Puedes encontrar los detalles actualizados de la tarifa de servicio de Play para diferentes tipos de transacciones en Cambios en el programa de ofertas externas para usuarios del Espacio Económico Europeo (EEE).

Cómo informar transacciones posteriores de una compra

En algunos casos, hay más de un pago del usuario asociado con la misma compra externa, por ejemplo, renovaciones de suscripciones o recargas de planes prepagados. Puedes informar estas transacciones posteriores con la misma API en Externaltransactions. Como se describe en Cómo informar una compra nueva, no se necesita externalTransactionToken para las transacciones posteriores. En su lugar, se envía un nuevo externalTransactionId único como el parámetros de consulta para cada transacción de renovación o recarga, con el ID de la transacción inicial incluido en el campo initialExternalTransactionId.

Siguiendo el ejemplo anterior:

  1. La primera renovación del Usuario 1 ocurre en el sistema alternativo de facturación. El ID de transacción original era 123-456-789.
  2. El desarrollador informa la recurrencia de la transacción en el parámetro de consulta de URL como el ID de transacción externo para esta nueva transacción, mientras hace referencia al ID de transacción externo de la transacción inicial en el campo initialExternalTransactionId.

Ejemplo de solicitud:

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

Cómo informar un cambio a una versión posterior o anterior

Para informar una actualización o un cambio a una versión anterior cuando el usuario es propietario de una suscripción en el sistema alternativo de facturación, debes usar el mismo extremo y la misma función en la API de Externaltransactions mediante el envío del externalTransactionToken a la app para realizar la transacción de actualización o de cambio a una versión anterior. Esto funciona de manera similar a cómo informar una compra nueva.

Cómo informar una descarga de app

Para informar una instalación de app en el sistema de facturación de ofertas externas, debes llamar a Externaltransactions.createexternaltransaction, enviando el externalTransactionToken que se proporcionó a la app. Informa esto como una transacción única y sin costo. Este proceso es similar a informar una transacción inicial. Asegúrate de incluir ExternalOfferDetails en el cuerpo de la solicitud.

Ejemplo de solicitud:

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

Cómo migrar desde informes manuales de transacciones de facturación alternativa

Para migrar las suscripciones activas que comenzaron mientras ofrecías una facturación alternativa sin informes automatizados, crea una nueva transacción de costo cero con el campo migratedTransactionProgram en lugar de especificar un initialExternalTransactionId o externalTransactionToken. Establece el transactionTime en la hora en la que el usuario se registró inicialmente para cada suscripción activa. Luego, informa cada transacción posterior de estas suscripciones como de costumbre a través de las APIs y proporciona el initialExternalTransactionId que se usó anteriormente para crear las transacciones de renovación. Una vez migrada la suscripción, ya no necesitarás informar manualmente las transacciones posteriores de la suscripción, siempre que se informen a través de los métodos automatizados que se describen en esta página.

Durante la migración de suscripciones, ten en cuenta los límites de cuota establecidos para verificar que la migración no cause una interrupción de la cuota. Si se deben migrar muchas suscripciones, distribúyelas en varios días o solicita un aumento de la cuota.

El campo migratedTransactionProgram solo se puede usar cuando se migra desde informes manuales. Se dará de baja cuando ya no se admitan los informes manuales.

Ejemplo de solicitud:

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

Requisitos para los programas de socios de Play

Los desarrolladores que participan en programas de socios, como el Programa de Experiencia de Medios de Play deben proporcionar el transaction_program_code cuando informan transacciones externas. Si eres un desarrollador apto, comunícate con tu administrador de desarrollo empresarial para obtener más información sobre cómo configurar este campo.

Cómo informar reembolsos de compras a Google Play

Integra la API de externaltransactions para informar las transacciones reembolsadas a los usuarios fuera del sistema de Facturación Google Play Para que Play identifique de forma correcta qué transacción se reembolsó, debes incluir el externalTransactionId correspondiente de la transacción informada anteriormente como parte de los parámetros de URL.

Cuando informes el reembolso de compras de suscripciones, consulta el externalTransactionId de la recurrencia específica de la suscripción que se está reembolsando.

Ejemplo: Supongamos que una suscripción tiene las siguientes transacciones:

  • Una transacción inicial con ID de transacción externo ABC.1234-5678-9012-34567

  • La primera transacción recurrente con el ID de transacción externo ABC.1234-5678-9012-34567..0

  • La segunda transacción recurrente con el ID de transacción externo ABC.1234-5678-9012-34567..1

Para informar un reembolso de todas las transacciones de la suscripción, debes realizar tres solicitudes de reembolso separadas: una para la transacción inicial y dos para las transacciones posteriores.

Este método acepta ambos reembolsos completos (cuando el importe es el mismo que pagó el usuario en la transacción original) y reembolsos parciales (cuando el importe es inferior al que pagó el usuario en la transacción externa original). Para los reembolsos parciales, debes especificar el importe antes de impuestos que se reembolsó.

Cuotas de API

La API de Externaltransactions está sujeta a cuotas de API para todas las llamadas, al igual que cualquier otro extremo de la API de Google Play Developer.

Además, la API de Externaltransactions tiene un límite de 1,200 consultas por minuto (QPM) en las llamadas a Externaltransactions.createexternaltransaction o Externaltransactions.refundexternaltransaction. Las llamadas a Externaltransactions.getexternaltransaction no cuentan para este límite de 1,200 QPM.