Register now for Android Dev Summit 2019!

Referencia del AIDL de Facturación Google Play

Advertencia: 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 enumeran 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 sincrónica como un valor entero asignado 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 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, no se configuró de manera adecuada para la 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 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 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 de 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 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 transmitir un cuarto argumento (un objeto Bundle) que puede contener 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 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. Esta marca especifica si la app admite un flujo de compra 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 de 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 de 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 El tipo de artículo integrado en la app ("inapp" para compras únicas y "subs" para suscripciones).
skusBundle Bundle 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 Bundle como respuesta. Los resultados de la consulta se almacenan en el Bundle dentro de una ArrayList de strings asignadas 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 Corresponde al ID del producto.
type El valor debe ser inapp para un producto integrado en la aplicación o 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 el price es "€7.99", el price_amount_micros es "7990000". Este valor representa el precio localizado y redondeado para una moneda en particular.
price_currency_code Código de moneda ISO 4217 para price. Por ejemplo, si price está especificado en libras esterlinas británicas, el price_currency_code es "GBP".
title Título del producto.
description Descripción del producto.
subscriptionPeriod Período de suscripción especificado en formato ISO 8601. Por ejemplo, P1W equivale a una semana, P1M equivale a un mes, P3M equivale a tres meses, P6M equivale a seis meses y P1Y equivale a un año.

Nota: Solo se muestra para suscripciones.

freeTrialPeriod 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 Precio de lanzamiento de una suscripción con formato, incluido su símbolo de moneda, como €3.99. El precio no incluye impuestos.

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

introductoryPriceAmountMicros Precio de lanzamiento en microunidades. La moneda es igual al 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 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 asignado a la clave RESPONSE_CODE y un objeto PendingIntent a fin de iniciar el flujo de compra para el artículo integrado en la aplicación asignado a la clave BUY_INTENT, como se describe en Cómo implementar la Facturación Google Play. Cuando recibe el objeto PendingIntent, Google Play envía un Intent de respuesta con los datos para 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 la compra se realiza correctamente. De lo contrario, se produce un error.
INAPP_PURCHASE_DATA 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 ese momento, a menos que vuelva a habilitar la renovación automática (o la renueve 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 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 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 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 permitirá volver a comprar los artículos del mismo SKU.

Tabla 8. Parámetros de 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 el valor RESULT_OK(0) para indicar que el consumo se realizó correctamente, y los códigos de respuesta correspondientes si se producen errores.

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 de las SKU ya compradas que deben reemplazarse por la 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 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 de AIDL isBillingSupported.

Nota: Solo puedes usar este método para compras de suscripciones. Si el parámetro type transmitido 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 asignado 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 asignado a la clave BUY_INTENT, como se describe en Cómo implementar la Facturación Google Play. Cuando recibe el objeto PendingIntent, Google Play envía un Intent de respuesta con los datos para 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 la compra se realiza correctamente. Si esta falla, contiene un código de error.
INAPP_PURCHASE_DATA 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 inicia una solicitud de compra y es una variante del método getBuyIntent() que incluye un parámetro extraParams adicional. Este parámetro es un objeto 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 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 transmites el valor skusToReplace.

accountId String

String oculta opcional que se asocia de manera única a la cuenta del usuario en tu app. Si transmites este valor, Google Play puede usarlo para detectar actividades irregulares, como el hecho de que muchos dispositivos hagan compras con la misma cuenta durante un período breve.

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 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, este campo 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 enumeran los datos de respuesta que se muestran en el objeto 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 StringArrayList que contiene la lista de productIds de las compras de esta app.
INAPP_PURCHASE_DATA_LIST StringArrayList que contiene los detalles de las compras de esta app. Consulta la tabla 13 para ver la lista de información detallada almacenada en cada artículo de la lista.
INAPP_DATA_SIGNATURE_LIST 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 un token de continuación se encuentra presente en la respuesta, 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 dicha compra venció, se canceló o se realizó. En la tabla 12, se enumeran los datos de respuesta que se muestran en el objeto Bundle:

Tabla 12. Datos de respuesta de una solicitud getPurchaseHistory.

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 StringArrayList que contiene la lista de productIds de las compras de esta app.
INAPP_PURCHASE_DATA_LIST StringArrayList que contiene los detalles de las compras recientes de esta app. Consulta la tabla 6 para obtener una lista de la información detallada guardada en cada elemento INAPP_PURCHASE_DATA de la lista.
INAPP_DATA_SIGNATURE_LIST 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 un token de continuación se encuentra presente en la respuesta, 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 para el 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 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 Token que identifica una compra de manera única para un par específico de artículo y usuario.

Nota: El método getPurchaseHistory() posee una sobrecarga superior a getPurchases(), ya que requiere una llamada al servidor de Google Play. Debes usar el método getPurchases() si 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.