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

La API de Google Play Developer ahora incluye funciones adicionales para informar transacciones desde un sistema de facturación alternativa o de ofertas externas. En esta guía, se describe cómo informar transacciones de ofertas externas o de facturación alternativa.

Hay algunos componentes que pueden ser necesarios para controlar las compras directas desde la aplicación desde tu backend. Para compilarlos, debes configurar la integración de backend como se indica en Configura la API de Google Play Developer. Para todas las funciones de backend del desarrollador que no sean específicas de las APIs de ofertas externas o facturación alternativa, se aplican las instrucciones de la documentación del sistema de Facturación Google Play.

Cómo informar nuevas transacciones externas a Google Play

Integra con Externaltransactions APIs para informar transacciones que ocurran fuera del sistema de Facturación Google Play en países admitidos, incluidas las transacciones de USD 0 que resulten de compras de pruebas gratuitas. Las transacciones de sistemas alternativos de ofertas o facturación solo se deben iniciar e informar para los países de los usuarios aptos según lo permitido en los programas de facturación alternativa o de 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 otras.

Informes de transacciones externas

Debes llamar al Externaltransactions API para informar una transacción externa después de que se autorizó el pago a través del sistema de ofertas externas o la facturación alternativa. Esto se aplica a todas las transacciones, incluidos los cargos iniciales, las renovaciones, los reembolsos y otros. Todas las transacciones deben informarse en un plazo de 24 horas después de que se produzca.

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 denunciar una compra nueva

Cada vez que se realiza una compra nueva con éxito en el sistema alternativo de facturación o de ofertas externas, se requiere una llamada a la API de Externaltransactions. Para estas compras nuevas, debes proporcionar un externalTransactionId único asociado con la compra en tu backend como parámetro de consulta. Este externalTransactionId no se puede volver a usar dentro del ID de paquete de la misma app.

También se requiere el externalTransactionToken que recibe la app mediante las devoluciones de llamada UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener o ExternalOfferReportingDetailsListener como parte del cuerpo de la solicitud para compras únicas y transacciones por primera vez en una compra recurrente (como una suscripción). En cualquier caso, esto se denomina transacción inicial. Después de la transacción inicial, ya no se necesita el externalTransactionToken, y debes informar 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"
 }
}

Si realizas transacciones con un usuario que reside en India, donde los impuestos varían según su área administrativa (como el estado o la provincia), asegúrate de incluir 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"
 }
}

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

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 externa 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 diarias 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.