En este documento, se describe cómo integrar las APIs de la Biblioteca de Play Billing para ofrecer pagos externos en las apps aptas. Para obtener más información sobre este programa, consulta los requisitos del programa.
Configuración de la Biblioteca de Facturación Play
Agrega la dependencia de la Biblioteca de Facturación Play a tu app para Android. Si quieres usar las APIs de pagos externos, debes utilizar la versión 8.3 o una posterior. Si necesitas migrar desde una versión anterior, sigue las instrucciones de la guía de migración para actualizar antes de comenzar la integración.
Inicializa el cliente de facturación
Los primeros pasos del proceso de integración son los mismos que los descritos en la Guía de integración de la Facturación Google Play, con algunas modificaciones cuando inicializas tu BillingClient:
- Debes llamar a un nuevo método
enableBillingProgram(EnableBillingProgramParams)para indicar que quieres ofrecer pagos externos. - Debes registrar un
DeveloperProvidedBillingListenerpara manejar los casos en los que el usuario elige pagar en tu sitio web o en una app de pagos.
En el siguiente ejemplo, se muestra cómo inicializar un objeto BillingClient con estas modificaciones:
Kotlin
val purchasesUpdatedListener =
PurchasesUpdatedListener { billingResult, purchases ->
// Handle new Google Play purchase.
}
val developerProvidedBillingListener =
DeveloperProvidedBillingListener { details ->
// Handle user selection for developer provided billing option.
}
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(developerProvidedBillingListener)
.build())
.build()
Java
private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
@Override
public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
// Handle new Google Play purchase.
}
};
private DeveloperProvidedBillingListener developerProvidedBillingListener =
new DeveloperProvidedBillingListener() {
@Override
public void onUserSelectedDeveloperBilling(
DeveloperProvidedBillingDetails details) {
// Handle user selection for developer provided billing option.
}
};
private BillingClient billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases()
.enableBillingProgram(
EnableBillingProgramParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setDeveloperProvidedBillingListener(developerProvidedBillingListener)
.build())
.build();
Cómo conectarse a Google Play
Después de inicializar el objeto BillingClient, conéctate a Google Play como se describe en Cómo conectarse a Google Play.
Verifica la elegibilidad del usuario
Después de conectarte a Google Play, puedes verificar si el usuario cumple con los requisitos para participar en el programa de pagos externos llamando al método isBillingProgramAvailableAsync(). Este método devuelve BillingResponseCode.OK si el usuario cumple con los requisitos.
En el siguiente ejemplo, se muestra cómo verificar la elegibilidad:
Kotlin
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_PAYMENTS,
object : BillingProgramAvailabilityListener {
override fun onBillingProgramAvailabilityResponse(
billingProgram: Int, billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external payments unavailable, etc.
return
}
// External payments are available. Can proceed with generating an
// external transaction token.
})
Java
billingClient.isBillingProgramAvailableAsync(
BillingProgram.EXTERNAL_PAYMENTS,
new BillingProgramAvailabilityListener() {
@Override
public void onBillingProgramAvailabilityResponse(
int billingProgram, BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external payments unavailable, etc.
return;
}
// External payments are available. Can proceed with generating an external transaction token.
}
});
Consulta la sección de manejo de respuestas para obtener detalles sobre cómo tu app debe responder a otros códigos de respuesta. Si usas extensiones de Kotlin, puedes usar corrutinas de Kotlin para no tener que definir un objeto de escucha independiente.
Cómo mostrar los productos disponibles
Puedes mostrar los productos disponibles al usuario de la misma manera que con una integración del sistema de facturación de Google Play. Cuando el usuario vea los productos disponibles y seleccione uno para comprar, se iniciará el flujo de pagos externos, como se describe en la sección sobre el inicio del flujo de pagos externos.
Prepara un token de transacción externa
Para informar una transacción externa a Google Play, debes tener un token de transacción externa generado a partir de la Biblioteca de Play Billing. Se debe generar un nuevo token de transacción externa cada vez que el usuario visite un sitio web o una app externos a través de la API de pagos externos. Para ello, llama a la API de createBillingProgramReportingDetailsAsync. El token se debe generar inmediatamente antes de que se llame a launchBillingFlow.
Kotlin
val params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.build()
billingClient.createBillingProgramReportingDetailsAsync(
params,
object : BillingProgramReportingDetailsListener {
override fun onCreateBillingProgramReportingDetailsResponse(
billingResult: BillingResult,
billingProgramReportingDetails: BillingProgramReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
billingProgramReportingDetails?.externalTransactionToken
// Persist the external transaction token locally. Pass it to
// the external website using DeveloperBillingOptionParams when
// launchBillingFlow is called.
}
})
Java
BillingProgramReportingDetailsParams params =
BillingProgramReportingDetailsParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.build();
billingClient.createBillingProgramReportingDetailsAsync(
params,
new BillingProgramReportingDetailsListener() {
@Override
public void onCreateBillingProgramReportingDetailsResponse(
BillingResult billingResult,
@Nullable BillingProgramReportingDetails
billingProgramReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
billingProgramReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to
// the external website using DeveloperBillingOptionParams when
// launchBillingFlow is called.
}
});
Si usas extensiones de Kotlin, puedes usar corrutinas de Kotlin para no tener que definir un objeto de escucha independiente.
Cómo iniciar el flujo de pagos externos
Llama a launchBillingFlow() para iniciar el flujo de pagos externos, de forma similar a iniciar un flujo de compra con una integración del sistema de facturación de Google Play, pero con un parámetro adicional DeveloperBillingOptionParams que indica que tu app quiere habilitar el flujo de pagos externos para esta compra.
DeveloperBillingOptionParams debe contener lo siguiente:
billingProgramconfigurado en el programa de facturaciónEXTERNAL_PAYMENTSlinkURIestablecido en el destino del vínculolaunchModese establece enLAUNCH_IN_EXTERNAL_BROWSER_OR_APPsi Google Play debe iniciar el vínculo o enCALLER_WILL_LAUNCH_LINKsi tu app iniciará el vínculo.
Cuando tu app llama a launchBillingFlow() con el parámetro DeveloperBillingOptionParams proporcionado, el sistema de facturación de Google Play realiza la siguiente verificación:
- El sistema verifica si el país de Google Play del usuario es un país que admite pagos externos (es decir, un país compatible). Si el país de Google Play del usuario es compatible, Google Play verifica si se habilitaron los pagos externos según la configuración de BillingClient y si se proporcionó
DeveloperBillingOptionParams.- Si se habilitaron los pagos externos, el flujo de compra muestra la UX a elección del usuario.
- Si no están habilitados los pagos externos, el flujo de compra mostrará la UX estándar del sistema de Facturación Google Play, sin la elección del usuario.
- Si el país de Google Play del usuario no es compatible, el flujo de compra mostrará la UX estándar del sistema de Facturación Google Play, sin la elección del usuario.
El país del usuario de Play es compatible |
El país del usuario de Play no es compatible |
|
Pagos externos habilitados (configuración de BillingClient y launchBillingFlow) |
La persona ve la UX con elección del usuario |
El usuario ve la UX estándar del sistema de Facturación Google Play |
No se habilitaron los pagos externos (no se habilitaron durante la configuración de BillingClient o no se proporcionaron DeveloperBillingOptionParams a launchBillingFlow) |
El usuario ve la UX estándar del sistema de Facturación Google Play |
El usuario ve la UX estándar del sistema de Facturación Google Play |
En el siguiente fragmento, se muestra cómo construir DeveloperBillingOptionParams:
Kotlin
val developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri("https://www.example.com/external/purchase")
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build()
Java
DeveloperBillingOptionParams developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri("https://www.example.com/external/purchase")
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build();
Cómo controlar la selección de usuarios
La forma en que manejas el resto del flujo de compra difiere según si el usuario seleccionó el sistema de facturación de Google Play o pagar en tu sitio web.
Cuando el usuario selecciona pagar en tu sitio web o en una app de pagos
Si el usuario elige pagar en tu sitio web, Google Play llama a DeveloperProvidedBillingListener para notificarle a la app que el usuario eligió pagar en tu sitio web o en una app de pagos. En particular, se llama al método onUserSelectedDeveloperBilling().
Si tu app establece launchMode en LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, Google Play iniciará el vínculo. Si launchMode se configuró como CALLER_WILL_LAUNCH_LINK, tu app es responsable de iniciar el vínculo.
Cuando vinculas a los usuarios a una app de pagos, eres responsable de verificar que el usuario ya tenga instalada la app de pagos en su dispositivo.
Usa este token para informar cualquier transacción que resulte de esta opción, como se explica en la guía de integración del backend.
Cuando el usuario selecciona el sistema de Facturación Google Play
Si el usuario elige el sistema de Facturación Google Play, continúa con la compra a través de Google Play.
- Consulta la sección sobre cómo procesar compras en la guía de integración de bibliotecas para obtener más información sobre cómo controlar las nuevas compras directas desde la aplicación a través del sistema de facturación de Google Play.
- Consulta la sección sobre nuevas suscripciones en la guía de administración de suscripciones para obtener información adicional sobre las compras de suscripciones.
Controla los cambios en la suscripción
En el caso de los desarrolladores que usan pagos externos, las compras deben procesarse a través del sistema de facturación de Google Play o informarse con un externalTransactionId, según la elección del usuario. Los cambios en las suscripciones existentes que se procesaron a través del sitio web del desarrollador se pueden realizar a través del mismo sistema de facturación hasta el vencimiento.
En esta sección, se describe cómo abordar algunas situaciones comunes de cambio de suscripción.
Flujos de actualización y de cambio a una versión inferior
Los cambios en los planes de suscripción, incluidos los flujos de actualización y de cambio a una versión inferior, deben manejarse de forma diferente según si la suscripción se compró originalmente a través del sistema de facturación de Google Play o del sitio web del desarrollador.
Los complementos que dependen de una suscripción existente, comparten la misma forma de pago y alinean los cargos recurrentes se manejan como actualizaciones. En el caso de otros complementos, los usuarios deben poder elegir qué sistema de facturación desean usar. Inicia una nueva experiencia de compra con launchBillingFlow(), como se describe en cómo iniciar el flujo de pagos externos.
Suscripciones compradas a través del sitio web del desarrollador o una app de pagos
Para las suscripciones que se compraron originalmente a través del sitio web del desarrollador o una app de pagos después de la elección del usuario, los usuarios que solicitan una actualización o un cambio a una versión inferior deben pasar por el sitio web del desarrollador o una app de pagos sin volver a pasar por la experiencia de elección del usuario.
Para ello, llama a launchBillingFlow() cuando el usuario solicite una actualización o una versión anterior. En lugar de especificar otros parámetros en el objeto SubscriptionUpdateParams, usa setOriginalExternalTransactionId() y proporciona el ID de transacción externo para la compra original.
También se debe proporcionar DeveloperBillingOptionParams en esta llamada. Esto no muestra la pantalla de elección del usuario, ya que la elección del usuario para la compra original se conserva para actualizaciones y cambios a versiones anteriores. Debes generar un nuevo token de transacción externa para esta transacción, como se describe aquí.
Cuando se completa la actualización o el cambio a una versión inferior con el sitio web del desarrollador o una app de pagos, debes informar una nueva transacción con el token de transacción externa que obtuviste en la llamada anterior para la compra de la nueva suscripción.
Suscripciones compradas a través del sistema de facturación de Google Play
Del mismo modo, los usuarios que compraron su suscripción actual a través del sistema de facturación de Google Play después de su elección deberían pasar por el flujo estándar de Facturación Google Play. DeveloperBillingOptionParams no se debe establecer en la llamada a launchBillingFlow.
Cancelaciones y restauraciones de suscripciones
Los usuarios deben poder cancelar su suscripción en cualquier momento. Cuando un usuario cancela una suscripción, es posible que se resuelva el derecho de acceso una vez finalizado el período pagado. Por ejemplo, si un usuario cancela una suscripción mensual a mitad de mes, puede seguir accediendo al servicio durante las 2 semanas restantes, aproximadamente, hasta que se quite su acceso. Durante este período, la suscripción sigue estando técnicamente activa, por lo que el usuario puede usar el servicio.
No es inusual que los usuarios decidan revertir la cancelación durante este período activo. En esta guía, ese proceso se denomina restablecimiento. En las siguientes secciones, se describe cómo manejar situaciones de restablecimiento en tu integración de la API de pagos externos.
Suscripciones compradas a través del sitio web del desarrollador
Si tienes un ID de transacción externo para una suscripción cancelada, no es necesario llamar a launchBillingFlow() para restablecer la suscripción, por lo que no se debe usar para este tipo de activación. Si un usuario restablece su suscripción mientras aún está en el período activo de una suscripción cancelada, no se realizará ninguna transacción en ese momento. Puede continuar informando sobre las renovaciones cuando venza el ciclo actual y se produzca la próxima renovación. Esto incluye los casos en los que el usuario recibe un crédito o un precio de renovación especial como parte del restablecimiento (por ejemplo, una promoción para motivar al usuario a continuar con la suscripción).
Suscripciones compradas a través del sistema de facturación de Google Play
Por lo general, los usuarios pueden restablecer las suscripciones en el sistema de Facturación Google Play. En el caso de las suscripciones canceladas que se compraron originalmente en el sistema de facturación de Google Play, el usuario puede elegir deshacer la cancelación mientras la suscripción esté activa con la función Volver a suscribirse de Google Play. En ese caso, recibirás una notificación para desarrolladores en tiempo real de SUBSCRIPTION_RESTARTED en tu backend y no se emitirá un token de compra nuevo. El token original se usará para continuar con la suscripción. Para obtener información sobre cómo administrar la restauración en el sistema de facturación de Google Play, consulta Restauraciones en la guía de administración de suscripciones.
También puedes llamar a launchBillingFlow() para activar una restauración en el sistema de facturación de Google Play desde la app. Consulta Antes del vencimiento de la suscripción (en la app) para obtener una explicación sobre cómo hacerlo. En el caso de los usuarios que realizaron el proceso de elección de usuario para la compra original (que se canceló, pero aún está activo), el sistema detecta automáticamente su elección y muestra la interfaz de usuario para restablecer esas compras. Se le solicita que confirme su recompra de la suscripción a través de Google Play, pero no es necesario que vuelva a completar el proceso de elección del usuario. En este caso, se emite un nuevo token de compra para el usuario.
Tu backend recibe una notificación para desarrolladores en tiempo real de SUBSCRIPTION_PURCHASED, y el valor de linkedPurchaseToken para el nuevo estado de compra se establece como en el caso de una actualización o el cambio a una versión inferior, con el token de compra anterior de la suscripción que se canceló.
Cómo volver a suscribirse
Si una suscripción vence por completo, ya sea debido a una cancelación o el rechazo del pago sin recuperación (una suspensión vencida de la cuenta), el usuario debe volver a suscribirse si desea reiniciar el derecho a utilizarla.
La suscripción nueva también se puede habilitar a través de la app. Para ello, se la procesa de manera similar a un registro estándar. Los usuarios deben poder elegir qué sistema de facturación desean usar. En este caso, se puede llamar a launchBillingFlow(), como se describe en cómo iniciar el flujo de pagos externos.
Control de respuestas
Cuando se produce un error, los métodos isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() y launchBillingFlow() pueden proporcionar un BillingResponseCode distinto de BillingResponseCode.OK. Considera controlar estos códigos de respuesta de la siguiente manera:
BillingResponseCode.ERROR: Se produjo un error interno. No continúes con la transacción ni abras el sitio web externo. Vuelve a intentarlo llamando a la API de nuevo.BillingResponseCode.FEATURE_NOT_SUPPORTED: Play Store no admite las APIs de pagos externos en el dispositivo actual. No continúes con la transacción ni abras el sitio web externo.BillingResponseCode.DEVELOPER_ERROR: Se produjo un error con la solicitud. Usa el mensaje de depuración para identificar y corregir el error antes de continuar.BillingResponseCode.USER_CANCELED: No continúes con la apertura del sitio web o la app externos. Vuelve a llamar alaunchBillingFlow()para mostrarle al usuario el diálogo de información la próxima vez que intentes dirigirlo fuera de la app.BillingResponseCode.BILLING_UNAVAILABLE: La transacción no es apta para pagos externos y, por lo tanto, la facturación del desarrollador no estará disponible en este programa. Esto se debe a que el usuario no está en un país apto para este programa o a que tu cuenta no se inscribió correctamente en el programa. Si es la última opción, verifica el estado de inscripción en Play Console.BillingResponseCode.NETWORK_ERROR,BillingResponseCode.SERVICE_DISCONNECTED,BillingResponseCode.SERVICE_UNAVAILABLE: Son errores transitorios que se deben controlar con una política de reintentos adecuada. En el caso deSERVICE_DISCONNECTED, restablece una conexión con Google Play antes de reintentarlo.
Prueba los vínculos de pagos externos
Los verificadores de licencias se deben usar para probar la integración de pagos externos. No se te facturarán las transacciones que se hayan iniciado desde cuentas de verificadores de licencias. Consulta Prueba la facturación integrada con licencias de aplicaciones para obtener más información sobre cómo configurar verificadores con licencia.
Próximos pasos
Una vez que termines la integración en la app, tendrás todo listo para integrar tu backend.