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 vinculación. En esta guía, se describe cómo informar las 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 vinculación, 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 vinculación y facturación: 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 ofertas externas.
  • APIs de transacciones externas: APIs que se usan para informar transacciones de programas de vinculación y facturación aptos.
  • Transacción externa: Es una transacción apta que se realiza fuera de la app, según se define en los requisitos del programa. Esto incluye las compras de contenido digital y las descargas de apps.
  • 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 complete una transacción externa. Este token se usa para notificar a Google Play sobre una transacción externa exitosa.
  • 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 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 aptos según lo permitido en los lineamientos de facturación alternativa o ofertas externas; de lo contrario, se rechazará la llamada a la API. Esto se aplica a todas las transacciones, incluidas las compras nuevas, renovaciones, recargas, actualizaciones, cambios a versiones inferiores y 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 vinculación y facturación. Esto se aplica a todas las transacciones, incluidos los cargos iniciales, las renovaciones, los reembolsos y otros. Consulta los lineamientos del programa de vinculación y facturación 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. Debes enviar 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.

Informa una transacción inicial

Cada vez que se realiza una compra nueva o se descarga una app con éxito en los programas de facturación y vinculación, debes llamar a la API de externaltransactions.

El externalTransactionToken que recibe la app a través de las devoluciones de llamada UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener o BillingProgramReportingDetailsListener se requiere 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) proporcionando un nuevo externalTransactionId único. Consulta Cómo informar transacciones posteriores de una compra para obtener más detalles sobre cómo informar transacciones posteriores.

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).
  • OtherRecurringProduct se debe usar para representar compras únicas que requieren varios pagos o un pago demorado. Por ejemplo, un pedido por adelantado puede tener una transacción inicial de USD 0 seguida de una segunda transacción en una fecha posterior por el precio del SKU cuando se complete el pedido por adelantado. 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 las transacciones de ofertas externas iniciales. Esto no es necesario 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 pertenece al programa de ofertas externas, debes establecer el campo externalOfferDetails si la transacción es única o es la primera de una serie recurrente:

  • Cuando informes transacciones de descargas de aplicaciones, establece linkType en LINK_TO_APP_DOWNLOAD y proporciona los valores adecuados para installedAppPackage y installedAppCategory. Consulta Cómo informar la descarga de una app para obtener más detalles.
  • Cuando informes transacciones de ofertas de contenido digital, establece linkType en LINK_TO_DIGITAL_CONTENT.
  • Después de instalar una app externa a través del programa de ofertas externas, debes informar las transacciones realizadas en ella. Cuando informes estas transacciones, vincúlalas al evento de descarga original de la app:
    • Proporciona el valor de 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": "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"
 }
}

Los detalles actualizados de los cargos por servicio de Play para diferentes tipos de transacciones se pueden encontrar 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",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "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 registrar la descarga de una app

Para informar una instalación de la app en el sistema de facturación de ofertas externas, debes llamar a Externaltransactions.createexternaltransaction y enviar el externalTransactionToken que se proporcionó a la app. Informa esto como una transacción única y sin costo. Este proceso es similar al de 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"
 }
}

Migra desde los 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 para socios, como el Programa Play Media Experience, deben proporcionar el transaction_program_code cuando informen transacciones externas. Si eres un desarrollador apto, comunícate con tu gerente 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 tanto reembolsos completos (cuando el importe es el mismo que pagó el usuario en la transacción externa original) como 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.