Guía de integración en la app para pagos externos

En este documento, se describe cómo integrar las APIs de la Biblioteca de Facturación Play para ofrecer pagos externos en 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 método enableBillingProgram(EnableBillingProgramParams) nuevo para indicar que quieres ofrecer pagos externos.
• Debes registrar un DeveloperProvidedBillingListener para 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:

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(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build()
    )
    .build()
Integration.kt

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 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 es apto para el programa de pagos externos llamando al isBillingProgramAvailableAsync() método. Este método muestra BillingResponseCode.OK si el usuario es apto. En el siguiente ejemplo, se muestra cómo verificar la elegibilidad:

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.EXTERNAL_PAYMENTS,
    object : BillingProgramAvailabilityListener {
        override fun onBillingProgramAvailabilityResponse(
            billingResult: BillingResult,
            billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails
        ) {
            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.
        }
    }
)
Integration.kt

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 utilizas 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 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 Cómo iniciar el 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 Facturación Play. Se debe generar un token de transacción externa nuevo 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 createBillingProgramReportingDetailsAsync API. El token debe generarse inmediatamente antes de que se llame a launchBillingFlow.

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.
        }
    }
)
Integration.kt

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 utilizas 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

Para iniciar el flujo de pagos externos, llama a launchBillingFlow() de manera similar a como se inicia un flujo de compra con una integración del sistema de Facturación Google Play, pero con un parámetro adicional DeveloperBillingOptionParams que indica que tu app desea habilitar el flujo de pagos externos para esta compra.

DeveloperBillingOptionParams debe contener lo siguiente:

• billingProgram configurado en el programa de facturación EXTERNAL_PAYMENTS
• linkURI configurado en el destino del vínculo
• launchMode configurado en LAUNCH_IN_EXTERNAL_BROWSER_OR_APP si Google Play debe iniciar el vínculo o CALLER_WILL_LAUNCH_LINK si tu app iniciará el vínculo

Cuando tu app llama a launchBillingFlow() con DeveloperBillingOptionParams, el sistema de Facturación 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 los pagos externos están habilitados según la configuración de BillingClient y si se proporciona DeveloperBillingOptionParams.
  • Si se habilitaron los pagos externos, el flujo de compra muestra la UX con elección del usuario.
  • Si no están habilitados los pagos externos, el flujo de compra muestra 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.

En el siguiente fragmento, se muestra cómo construir DeveloperBillingOptionParams:

val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("https://www.example.com/external/purchase".toUri())
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()
Integration.kt

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri(Uri.parse("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 manera en la que el resto del flujo de compra se diferencia en función de si el usuario seleccionó el sistema de Facturación 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 la 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 descubrir cómo procesar las nuevas compras directas desde la aplicación a través del sistema de Facturación 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

Para los desarrolladores que usan pagos externos, las compras deben procesarse a través del sistema de Facturación 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 el plan 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 Google Play o a través 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. Para otros complementos, los usuarios deben poder elegir qué sistema de facturación desean usar. Para iniciar una nueva experiencia de compra, usa 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 SubscriptionUpdateParams objeto, 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 inferiores. 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 anterior del sitio web del desarrollador o una app de pagos, debes informar una nueva transacción mediante el token de transacción externo 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, a los usuarios que compraron su suscripción actual a través del sistema de Facturación Google Play después de su elección se les mostrará el flujo estándar de Facturación Google Play. No se debe configurar DeveloperBillingOptionParams 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 pago. 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 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 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 Google Play's, el usuario puede elegir deshacer la cancelación mientras la suscripción está activa con la función Volver a suscribirse de Google Play's. 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 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 Google Play desde la app. Consulta Antes de que venza la suscripción (en la app) para aprender a hacer esto. 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 estado de compra nuevo 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. launchBillingFlow() se puede llamar en este caso, 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(), launchBillingFlow() pueden proporcionar un BillingResponseCode que no sea BillingResponseCode.OK. Considera controlar estos códigos de respuesta de la siguiente manera:

• BillingResponseCode.ERROR: Es un error interno. No continúes con la transacción ni abras el sitio web externo. Vuelve a llamar a la API para reintentarlo.
• 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: Hay 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 a launchBillingFlow() 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 compatible 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 de SERVICE_DISCONNECTED, restablece una conexión con Google Play antes de reintentarlo.

Prueba los vínculos de pagos externos

Se deben usar verificadores de licencias para probar la integración de pagos externos. No se te facturarán las transacciones que hayan iniciado las 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 los verificadores de licencias.

Próximos pasos

Una vez que termines la integración en la app, tendrás todo listo para integrar tu backend.