Únete a ⁠ #Android11: The Beta Launch Show el 3 de junio.

Referencia del AIDL de Facturación Google Play

Advertencia: El AIDL ya no es compatible y se quitará en una versión futura. Usa la biblioteca de Facturación Google Play para implementar sus características.

En esta documentación, se proporciona información de referencia técnica para usar el AIDL de Facturación Google Play.

Códigos de respuesta del servidor

En la siguiente tabla, se enumeran todos los códigos de respuesta del servidor que se envían de Google Play a la aplicación. Google Play envía el código de respuesta de manera síncrona como un valor entero mapeado a la clave RESPONSE_CODE en el Bundle de respuesta. La aplicación debe gestionar todos estos códigos de respuesta.

Tabla 1: Resumen de códigos de respuesta para llamadas de AIDL de la Facturación Google Play

Código de respuesta Valor Descripción
BILLING_RESPONSE_RESULT_OK 0 Listo
BILLING_RESPONSE_RESULT_USER_CANCELED 1 El usuario presionó Atrás o Cancelar en un diálogo.
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 No hay conexión de red.
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 La versión de AIDL de la Facturación Google Play no es compatible con el tipo solicitado.
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 El producto solicitado no está disponible para la compra.
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Se proporcionaron argumentos no válidos a la API. Este error también puede indicar que la aplicación no se encuentra correctamente firmada o configurada para Facturación Google Play, o no tiene los permisos necesarios en su manifiesto.
BILLING_RESPONSE_RESULT_ERROR 6 Error grave durante la acción de la API.
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 No se concretó la compra porque ya se adquirió el artículo.
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 No se concretó el consumo porque no se adquirió el artículo.

Referencia de compatibilidad de AIDL de la Facturación Google Play

En esta sección, se describen los métodos para obtener información sobre los tipos de compatibilidad con Facturación Google Play disponibles para tu app.

Método isBillingSupported()

Este método indica lo siguiente:

  • Si la versión del AIDL es compatible con tu app.
  • Si Google Play admite la facturación en el país del usuario.
  • Si la Facturación Google Play está habilitada en el paquete de tu app.
  • Si tu app puede usar el tipo de artículo en cuestión con fines de facturación.

Tabla 2: Parámetros isBillingSupported()

Clave Tipo Descripción
apiVersion int El número de versión del AIDL de la Facturación Google Play que usa tu app.
packageName String El nombre del paquete de la app que invoca este método.
type String El valor debe ser inapp para un producto integrado en la aplicación, o bien subs para suscripciones.

Este método está disponible en la versión 3 del AIDL de la Facturación Google Play y en versiones posteriores.

Método isBillingSupportedExtraParams()

Este método es idéntico a isBillingSupported(), salvo por el hecho de que puedes pasar un cuarto argumento (un Bundle) con parámetros adicionales.

Tabla 3: Parámetros de isBillingSupportedExtraParams()

Clave Tipo Descripción
apiVersion int El número de versión del AIDL de la Facturación Google Play que usa tu app.
packageName String El nombre del paquete de la app que invoca este método.
type String El valor debe ser inapp para un producto integrado en la aplicación, o bien subs para suscripciones.
extraParams Bundle

Es un conjunto de parámetros adicionales que brinda más información sobre el tipo de Facturación Google Play compatible con la app.

Este paquete puede contener una clave opcional llamada vr que posee un valor booleano. Esta marca especifica si la app admite un flujo de compras en realidad virtual (RV).

Este método está disponible en la versión 7 del AIDL de la Facturación Google Play y en versiones posteriores.

Información detallada de referencia de compatibilidad del AIDL de la Facturación Google Play

El AIDL de Facturación Google Play se define en el archivo IInAppBillingService.aidl, que se incluye en la versión 3 de la aplicación de muestra.

Método getSkuDetails()

Usa el método getSkuDetails() para obtener detalles del producto y acceder a la lista correspondiente de los ID de producto.

Tabla 4: Parámetros GetSkuDetails()

Clave Tipo Descripción
apiVersion int El número de versión del AIDL de la Facturación Google Play que usa tu app.
packageName String El nombre del paquete de la app que invoca este método.
type String Es el tipo de artículo integrado en la app ("inapp" para compras únicas y "subs" para suscripciones).
skusBundle Bundle Es el paquete que contiene una StringArrayList de SKU con la clave ITEM_ID_LIST.

Si el método getSkuDetails() tiene éxito, Google Play envía un Bundle como respuesta. Los resultados de la consulta se almacenan en el Bundle dentro de una ArrayList de string mapeada a la clave DETAILS_LIST. Cada string en la lista de detalles contiene los detalles del producto para un único producto en formato JSON. Los campos de la string JSON con los detalles del producto están resumidos en la tabla 5.

Tabla 5: Descripción de los campos JSON con los detalles del producto que se muestran a partir de una solicitud getSkuDetails()

Clave Descripción
productId Es el ID del producto.
type El valor debe ser inapp para un producto integrado en la aplicación, o bien subs para suscripciones.
price Precio del artículo con formato, incluido su símbolo de moneda. El precio no incluye impuestos.
price_amount_micros Precio en microunidades, donde 1,000,000 de microunidades equivalen a una unidad de moneda. Por ejemplo, si price es "€7.99", entonces price_amount_micros debe expresarse como "7990000". Este valor representa el precio localizado y redondeado para una moneda en particular.
price_currency_code Es el código de moneda ISO 4217 de price. Por ejemplo, si price está especificado en libras esterlinas, entonces price_currency_code es "GBP".
title Es el título del producto.
description Es la descripción del producto.
subscriptionPeriod Es el período de suscripción especificado en formato ISO 8601. Por ejemplo, P1W equivale a una semana, P1M a un mes, P3M a tres meses, P6M a seis meses y P1Y a un año.

Nota: Solo se muestra para suscripciones.

freeTrialPeriod Es el período de prueba configurado en Google Play Console, especificado en formato ISO 8601. Por ejemplo, P7D equivale a siete días. Para obtener más información sobre la elegibilidad de una prueba gratuita, consulta la sección Suscripciones integradas en la aplicación.

Nota: Solo se muestra para las suscripciones que tienen configurado un período de prueba.

introductoryPrice Es el precio de lanzamiento de una suscripción con formato, incluido el símbolo de moneda, como €3.99. No incluye impuestos.

Nota: Solo se muestra para las suscripciones que tienen configurado un período de lanzamiento.

introductoryPriceAmountMicros Es el precio de lanzamiento en microunidades. La moneda es la misma que price_currency_code.

Nota: Solo se muestra para las suscripciones que tienen configurado un período de lanzamiento.

introductoryPricePeriod Es el período de facturación del precio de lanzamiento, que se especifica en formato ISO 8601.

Nota: Solo se muestra para las suscripciones que tienen configurado un período de lanzamiento.

introductoryPriceCycles La cantidad de períodos de facturación de la suscripción en los que el usuario recibirá un precio de lanzamiento (por ejemplo, 3).

Nota: Solo se muestra para las suscripciones que tienen configurado un período de lanzamiento.

Método getBuyIntent()

Este método muestra un valor entero del código de respuesta mapeado a la clave RESPONSE_CODE y un objeto PendingIntent, a fin de iniciar el flujo de compra para el elemento integrado en la app que está mapeado a la clave BUY_INTENT, como se describe en la sección Cómo implementar la Facturación Google Play. Cuando recibe el PendingIntent, Google Play envía un Intent de respuesta con los datos de esa orden de compra. Los datos que se muestran en el Intent de respuesta se resumen en la tabla 6.

Nota: En lugar de utilizar este método, te recomendamos usar getBuyIntentExtraParams(), que proporciona funciones adicionales.

Tabla 6: Datos de respuesta de una solicitud de compra de la Facturación Google Play

Clave Descripción
RESPONSE_CODE El valor es 0 si la compra se realiza correctamente. De lo contrario, se produce un error.
INAPP_PURCHASE_DATA Es una string en formato JSON que contiene detalles de la orden de compra. Consulta la tabla 7 para obtener una descripción de los campos JSON.
INAPP_DATA_SIGNATURE String que contiene la firma de los datos de compra firmados con la clave privada del desarrollador. La firma de datos usa el esquema RSASSA-PKCS1-v1_5.

La tabla 7 describe los campos JSON que se muestran en los datos de respuesta para una orden de compra.

Tabla 7: Descripciones de los campos JSON para INAPP_PURCHASE_DATA

Campo Descripción
autoRenewing Indica si la suscripción se renueva automáticamente. Si el valor es true, la suscripción se encuentra activa y se renovará automáticamente en la siguiente fecha de facturación. Si el valor es false, indica que el usuario canceló la suscripción. El usuario tiene acceso al contenido de la suscripción hasta la siguiente fecha de facturación, y perderá el acceso en esa fecha, a menos que vuelva a habilitar la renovación automática (o renueve la suscripción manualmente, como se describe en la sección Renovación manual). Si ofreces un período de gracia, este valor seguirá configurado como true para todas las suscripciones mientras no venza ese período. La siguiente fecha de facturación se extiende dinámicamente cada día hasta el final del período de gracia o hasta que el usuario fije su forma de pago.
orderId Identificador de pedido único para la transacción. Este identificador corresponde al ID de pedido de Google Payments.
packageName El paquete de la aplicación desde el que se originó la compra.
productId El identificador de producto del artículo. Todos los artículos poseen un ID de producto que debes especificar en la lista de productos de la aplicación de Google Play Console.
purchaseTime La hora a la que se compró el producto en milisegundos a partir del epoch (1 de enero de 1970).
purchaseState El estado de compra del pedido. Siempre muestra 0 (compras).
developerPayload Es la string especificada por el desarrollador que contiene información adicional sobre un pedido. Puedes especificar un valor para este campo cuando envías una solicitud de getBuyIntent.
purchaseToken Es un token que identifica una compra de manera única para un par específico de artículo y usuario.

Método consumePurchase()

Compra correspondiente al token específico. Como resultado, se quitará este artículo de todas las respuestas posteriores de getPurchases() y se podrán volver a comprar los artículos con el mismo SKU.

Tabla 8: Parámetros consumePurchase()

Clave Tipo Descripción
apiVersion int El número de versión del AIDL de la Facturación Google Play que usa tu app.
packageName String El nombre del paquete de la app que invoca este método.
purchaseToken String El token en el archivo JSON de información que identifica la compra que se consumirá.

Este método muestra un RESULT_OK(0) de consumo exitoso y los códigos de respuesta correspondientes en caso de fallas.

Método getBuyIntentToReplaceSkus()

Este método se usa para actualizar una suscripción o para pasarla a una versión anterior. El método es similar a getBuyIntent(), con la excepción de que toma una lista con solo un SKU ya comprado, que debe reemplazarse por el SKU que se comprará. Cuando el usuario completa la compra, Google Play intercambia los SKU anteriores y acredita al usuario el valor no usado del tiempo de su suscripción de manera prorrateada. Google Play adjudica este crédito a la nueva suscripción y no comienza a emitir facturación para el usuario por la nueva suscripción hasta que se haya consumido el crédito.

Nota: En lugar de utilizar este método, te recomendamos usar getBuyIntentExtraParams(), que proporciona funciones adicionales.

Se agregó este método con la versión 5 del AIDL de Facturación Google Play. Para verificar que se informe el método, envía una solicitud isBillingSupported del AIDL.

Nota: Solo puedes usar este método para compras de suscripciones. Si el parámetro type que se pasa no es "subs", el método mostrará BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. Además, es posible que los SKU transmitidos no incluyan SKU para suscripciones temporales.

Este método muestra un valor entero del código de respuesta mapeado a la clave RESPONSE_CODE y un objeto PendingIntent, a fin de iniciar el flujo de compra de la suscripción integrada en la aplicación que está mapeada a la clave BUY_INTENT, como se describe en la sección Cómo implementar la Facturación Google Play. Cuando recibe el PendingIntent, Google Play envía un Intent de respuesta con los datos de esa orden de compra. Los datos que se muestran en el Intent de respuesta se resumen en la tabla 9.

Tabla 9: Datos de respuesta de una solicitud de compra con la versión 5 del AIDL de Facturación Google Play

Clave Descripción
RESPONSE_CODE El valor es 0 si la compra se realiza correctamente. Si esta falla, contiene un código de error.
INAPP_PURCHASE_DATA Es una string en formato JSON que contiene detalles de la orden de compra. Consulta la tabla 6 para obtener una descripción de los campos JSON.
INAPP_DATA_SIGNATURE String que contiene la firma de los datos de compra que el desarrollador firmó con su clave privada. La firma de datos usa el esquema RSASSA-PKCS1-v1_5.

Método getBuyIntentExtraParams()

Este método comienza una solicitud de compra. Es una variante del método getBuyIntent() que incluye un parámetro extraParams adicional. Este parámetro es un Bundle de claves y valores opcionales que afectan la operación del método, como se muestra en la tabla 10.

Tabla 10: Parámetros adicionales de getBuyIntentExtraParams()

Clave Tipo Descripción
skusToReplace List<String> Una lista opcional con exactamente un SKU desde el que el usuario realiza una actualización o pasa a una versión anterior. Transmite este campo si la compra actualiza una suscripción existente o pasa a una versión anterior. El SKU especificado se reemplaza con el SKU que está comprando el usuario. Google Play reemplaza el SKU especificado al comienzo del siguiente ciclo de facturación.
replaceSkusProration boolean

Especifica si el usuario debe recibir una compensación por el período de suscripción sin usar de los SKU en los que realizan una actualización o pasan a una versión anterior. Si configuras este campo como "true", Google Play intercambia los SKU anteriores y acredita al usuario el valor no usado del tiempo de su suscripción de manera prorrateada. Google Play adjudica este crédito a la nueva suscripción y no comienza a emitir facturación para el usuario por la nueva suscripción hasta que se haya consumido el crédito.

Si configuras este campo como falso, el usuario no recibirá ningún crédito por el tiempo de suscripción no usado y la fecha de recurrencia no se cambiará.

El valor predeterminado es verdadero. Se ignora si no pasas un skusToReplace.

accountId String

Es una string ofuscada opcional que está asociada de forma exclusiva con la cuenta del usuario en tu app. Si pasas este valor, Google Play podrá usarlo para detectar actividad irregular, como muchos dispositivos que realizan compras desde la misma cuenta en un período corto.

Este campo es similar a developerId, ya que representa a un solo usuario. Sin embargo, ten en cuenta que si tienes varias apps, el mismo usuario puede tener diferentes accountId para cada app, mientras que developerId debería identificar a un solo usuario de manera única en todas tus apps.

No uses el ID de desarrollador de Google Play Console ni el ID de Google para este campo. Además, este campo no debe incluir el ID del usuario en Cleartext. Te recomendamos usar un hash unidireccional para generar una string a partir del ID del usuario y que almacenes la string con hash en este campo.

developerId String

Es una string ofuscada opcional que se asocia de manera única con la cuenta del usuario en todas tus apps. Este campo es similar a accountId, ya que representa a un solo usuario. Sin embargo, debería ser el mismo en todas tus apps para el mismo usuario, mientras que accountId puede ser único por app, incluso para el mismo usuario.

No uses el ID de desarrollador de Google Play Console ni el ID de Google para este campo. Además, este campo no debe incluir el ID del usuario en Cleartext. Te recomendamos usar un hash unidireccional para generar una string a partir del ID del usuario y que almacenes la string con hash en este campo.

vr boolean

Especifica si el intent proporcionado representa el comienzo de un flujo de compra de realidad virtual (RV).

Nota: Para que este parámetro adicional tenga un efecto en tu app, debes usar la versión 7 del AIDL de Facturación Google Play o una API más reciente.

Este método está disponible en la versión 6 del AIDL de la Facturación Google Play y en versiones posteriores.

Método getPurchases()

Este método muestra los productos actuales no consumidos que posee el usuario, incluidos los artículos comprados y los adquiridos mediante el canje de un código promocional. En la tabla 11, se indican los datos de respuesta que se muestran en el Bundle:

Tabla 11: Datos de respuesta de una solicitud getPurchases

Clave Descripción
RESPONSE_CODE El valor es 0 si la solicitud se realiza correctamente. De lo contrario, se produce un error.
INAPP_PURCHASE_ITEM_LIST Es una StringArrayList que contiene la lista de productIds de las compras de esta app.
INAPP_PURCHASE_DATA_LIST Es una StringArrayList que contiene los detalles de las compras de esta app. En la tabla 13, está la lista de información detallada que se almacena en cada elemento de la lista.
INAPP_DATA_SIGNATURE_LIST Es una StringArrayList que contiene las firmas de las compras de esta app.
INAPP_CONTINUATION_TOKEN String que contiene un token de continuación para obtener el siguiente conjunto de productos integrados en la aplicación que posee el usuario. Solo se establece mediante el servicio de Google Play si la cantidad de productos que posee el usuario es muy grande. Cuando la respuesta contiene un token de continuación, debes hacer otra llamada a getPurchases y pasar el token de continuación que recibiste. La llamada de getPurchases subsiguiente muestra más compras y, posiblemente, otro token de continuación.

Método getPurchaseHistory()

Este método muestra la compra más reciente que hizo el usuario para cada SKU, incluso si dicha compra venció, se canceló o se realizó. En la tabla 12, se indican los datos de respuesta que se muestran en el Bundle:

Tabla 12: Datos de respuesta de una solicitud getPurchaseHistory

Clave Descripción
RESPONSE_CODE El valor es 0 si se realiza correctamente la solicitud. De lo contrario, se produce un error.
INAPP_PURCHASE_ITEM_LIST Es una StringArrayList que contiene la lista de productIds de las compras de esta app.
INAPP_PURCHASE_DATA_LIST Es una StringArrayList que contiene los detalles de las compras recientes de esta app. En la tabla 6, está la lista de información detallada que se almacena en cada INAPP_PURCHASE_DATA de la lista.
INAPP_DATA_SIGNATURE_LIST Es una StringArrayList que contiene las firmas de las compras de esta app.
INAPP_CONTINUATION_TOKEN String que contiene un token de continuación para obtener el siguiente conjunto de productos integrados en la aplicación que posee el usuario. Solo se establece mediante el servicio de Google Play si la cantidad de productos que posee el usuario es muy grande. Cuando la respuesta contiene un token de continuación, debes hacer otra llamada a getPurchases y pasar el token de continuación que recibiste. La llamada de getPurchases subsiguiente muestra más compras y, posiblemente, otro token de continuación.

Tabla 13: Descripciones de los campos JSON del historial de compras que muestra getPurchaseHistory()

Campo Descripción
productId El identificador de producto del artículo. Todos los artículos poseen un ID de producto que debes especificar en la lista de productos de la aplicación de Google Play Console.
purchaseTime La hora a la que se compró el producto en milisegundos a partir del epoch (1 de enero de 1970).
developerPayload Es la string especificada por el desarrollador que contiene información adicional sobre un pedido. Puedes especificar un valor para este campo cuando envías una solicitud de getBuyIntent.
purchaseToken Es un token que identifica una compra de manera única para un par específico de artículo y usuario.

Nota: El método getPurchaseHistory() tiene una sobrecarga superior a getPurchases(), ya que requiere una llamada al servidor de Google Play. Debes usar getPurchases() si realmente no necesitas acceder al historial de compras del usuario.

Este método está disponible en la versión 6 del AIDL de la Facturación Google Play y en versiones posteriores.