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 para informar transacciones desde una facturación alternativa o de ofertas externas. En esta guía, se describe cómo informar alternativas de facturación o de ofertas externas.

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 son específicas de la facturación alternativa o las APIs de ofertas externas, las instrucciones de la Se aplica la documentación del sistema de Facturación Google Play.

Cómo informar nuevas transacciones externas a Google Play

Cómo realizar la integración con Externaltransactions APIs para informar transacciones que ocurran fuera del sistema de facturación de Google Play en países admitidos, incluidas las transacciones por USD 0 que resulten de la prueba gratuita compras. Transacciones en sistemas alternativos de facturación o de ofertas externas Solo se deben iniciar e informar para los países de los usuarios aptos según lo permitido con la facturación alternativa o programas de ofertas externas; de lo contrario, se realizará la llamada a la API rechazadas. Esto se aplica a todas las transacciones, incluidas las compras nuevas, las renovaciones, recargas, actualizaciones, cambios a versiones inferiores y mucho más.

Informes de transacciones externas

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

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 datos de identificación personal información confidencial o exclusiva como parte de esta ID de transacción.

Cómo denunciar una compra nueva

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

El externalTransactionToken que recibe la app mediante el UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener o ExternalOfferReportingDetailsListener también se requieren como parte de el cuerpo de la solicitud para compras únicas y transacciones por primera vez en un compra recurrente (como una suscripción). En cualquier caso, esto se denomina una transacción inicial. Después de la transacción inicial, el externalTransactionToken ya no es necesario, y debes informar las posteriores transacciones (como renovaciones de suscripciones) proporcionando un nuevo ID único externalTransactionId Consulta Cómo informar transacciones posteriores de una compra. para obtener más información sobre cómo informar las 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 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 muchas suscripciones necesitan que se migrarán, distribuirlas en varios días o solicitar un aumento de la cuota de Google Cloud.

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 denunciar los programas de socios de Play

Los desarrolladores que participan en programas de socios, como el El Programa Play Media Experience debe proporcionar la transaction_program_code cuando se informen transacciones externas. Si eres 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 transacciones) y los reembolsos parciales (cuando el importe es inferior al que pagó el usuario en la oferta transacción). 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, como con 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.