Referencia del AIDL de Facturación Google Play

Advertencia: El AIDL ya no es compatible y se quitará en una versión futura. Para implementar las funciones de la Facturación Google Play, usa la biblioteca de la Facturación Google Play.

Esta documentación proporciona información de referencia técnica para usar el AIDL de la Facturación Google Play.

Códigos de respuesta del servidor

En la siguiente tabla, se muestran todos los códigos de respuesta del servidor que se envían de Google Play a tu 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. Tu aplicación debe gestionar todos estos códigos de respuesta.

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

Código de respuesta Valor Descripción
BILLING_RESPONSE_RESULT_OK 0 Correcto
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 del AIDL de la Facturación Google Play no es compatible con el tipo solicitado.
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 No se puede comprar el producto seleccionado.
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Se proporcionaron argumentos no válidos a la API. Este error también puede indicar que no se firmó correctamente la aplicación, que no se la configuró de manera adecuada para la Facturación Google Play o que no tiene los permisos necesarios en su manifiesto.
BILLING_RESPONSE_RESULT_ERROR 6 Es un error grave que se produce 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 del AIDL de la Facturación Google Play

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

Método isBillingSupported()

Este método indica lo siguiente:

  • Si la versión específica 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 Es el número de versión del AIDL de la Facturación Google Play que usa tu app.
packageName String Es 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 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(), excepto que puedes pasar un cuarto argumento (un objeto Bundle) que puede contener parámetros adicionales.

Tabla 3. Parámetros isBillingSupportedExtraParams()

Clave Tipo Descripción
apiVersion int Es el número de versión del AIDL de la Facturación Google Play que usa tu app.
packageName String Es 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 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 que admite la app.

Este paquete puede contener una clave opcional llamada vr que posee un valor booleano. Este indicador especifica si esta app admite un flujo de compras de 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 la Facturación Google Play se define en el archivo IInAppBillingService.aidl, que se incluye en la versión 3 del ejemplo de aplicación.

Método getSkuDetails()

Usa el método getSkuDetails() con el fin de obtener detalles del producto para una lista correspondiente de ID de productos.

Tabla 4. Parámetros GetSkuDetails()

Clave Tipo Descripción
apiVersion int Es el número de versión del AIDL de la Facturación Google Play que usa tu app.
packageName String Es 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 de la lista contiene los detalles del producto correspondiente a 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 subs para suscripciones.
price Es el precio del artículo con formato, incluido su símbolo de moneda. No incluye impuestos.
price_amount_micros Es el precio en microunidades, donde 1,000,000 microunidades equivalen a una unidad de moneda. Por ejemplo, si price es "€7.99", entonces price_amount_micros debe expresarse "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 acerca de los criterios de elegibilidad, consulta 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 su 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 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 Es 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 la suscripción integrada en la aplicación mapeado a la clave BUY_INTENT, como se describe en 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 incluye 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 se realiza correctamente la compra. 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 Es la 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 de una orden de compra.

Tabla 7. Descripciones de los campos JSON de 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 Renovación manual). Si ofreces un período de gracia, este valor continuará siendo true para todas las suscripciones mientras no venza ese período. La siguiente fecha de facturación se extenderá dinámicamente cada día hasta el final del período de gracia o hasta que el usuario corrija la forma de pago.
orderId Es el identificador de pedido único de la transacción. Este identificador corresponde al ID de pedido de pagos mediante Google.
packageName Es el paquete de la aplicación desde el que se originó la compra.
productId Es 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 en Google Play Console.
purchaseTime Es la hora (expresada en milisegundos) en que se compró el producto a partir de la época ("epoch"; es decir, desde el 1 de enero de 1970).
purchaseState Es el estado de compra del pedido. Siempre muestra 0 (se compró).
developerPayload Es la string especificada por el desarrollador que contiene información adicional sobre un pedido. Puedes especificar un valor para este campo cuando haces una solicitud getBuyIntent.
purchaseToken Es el token que identifica una compra de manera única para un par específico de artículo y usuario.

Método consumePurchase()

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

Tabla 8. Parámetros consumePurchase()

Clave Tipo Descripción
apiVersion int Es el número de versión del AIDL de la Facturación Google Play que usa tu app.
packageName String Es el nombre del paquete de la app que invoca este método.
purchaseToken String Es 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 un SKU ya comprado que debe reemplazarse por el SKU que se comprará. Cuando el usuario completa la compra, Google Play intercambia el SKU anterior 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 incluye funciones adicionales.

Se agregó este método con la versión 5 del AIDL de la 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 mapeada a la clave BUY_INTENT, como se describe en 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 la Facturación Google Play

Clave Descripción
RESPONSE_CODE El valor es 0 si se realiza correctamente la compra. Si falla, contendrá 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 Es una 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 getBuyIntentExtraParams() adicionales

Clave Tipo Descripción
skusToReplace List<String> Es una lista opcional con exactamente un SKU que corresponde al que el usuario tiene al momento de pasar a otro con más beneficios o más básico. Transmite este campo si la compra actualiza una suscripción existente o cambia a un plan inferior. 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 un plan inferior. Si configuras este campo como verdadero, 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 de tiempo 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 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 oculta 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 la 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 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 de esta app. Consulta la tabla 13 para ver 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 Es una 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 lo establece 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 a getPurchases posterior 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 esa compra venció, se canceló o se consumió. 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. Consulta la tabla 6 para ver 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 Es una 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 lo establece 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 a getPurchases posterior 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 Es 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 en Google Play Console.
purchaseTime Es la hora (expresada en milisegundos) en que se compró el producto a partir de la época ("epoch"; es decir, desde el 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 haces una solicitud getBuyIntent.
purchaseToken Es el 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.