Orientações de integração no app para pagamentos externos

Este documento descreve como integrar as APIs da biblioteca Play Faturamento para oferecer pagamentos externos em apps qualificados. Para saber mais sobre esse programa, consulte os requisitos.

Configuração da Biblioteca Play Faturamento

Adicione a dependência da Biblioteca Play Faturamento ao seu app Android. Para usar as APIs de pagamentos externos, você precisa usar a versão 8.3 ou mais recente. Se precisar migrar de uma versão anterior, siga as instruções no guia de migração para fazer upgrade antes de iniciar a integração.

Inicializar o cliente de faturamento

As primeiras etapas do processo de integração são as mesmas descritas no Guia de integração do Google Play Faturamento, com algumas modificações ao inicializar o BillingClient:

O exemplo abaixo demonstra a inicialização de um BillingClient com estas modificações:

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();

Conectar ao Google Play

Depois de inicializar o BillingClient, conecte-se ao Google Play conforme descrito em Conectar ao Google Play.

Verificar a qualificação do usuário

Depois de se conectar ao Google Play, você pode verificar se o usuário está qualificado para o programa de pagamentos externos chamando o método isBillingProgramAvailableAsync(). Esse método retorna BillingResponseCode.OK se o usuário estiver qualificado. A amostra a seguir demonstra como verificar a qualificação:

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.
      }

    });

Consulte a seção Processamento de respostas para mais detalhes sobre como seu app precisa responder a outros códigos de resposta. Se você usa extensões Kotlin, pode usar corrotinas Kotlin para não precisar definir um listener separado.

Mostrar produtos disponíveis

É possível mostrar produtos disponíveis para o usuário da mesma forma que faria com uma integração do sistema de faturamento do Google Play. Quando o usuário encontrar os produtos disponíveis e selecionar um para comprar, inicie o fluxo de pagamentos externos, conforme descrito na seção Como iniciar o fluxo de pagamentos externos.

Preparar um token de transação externa

Para informar uma transação externa ao Google Play, você precisa ter um token de transação externa gerado pela Biblioteca Google Play Faturamento. Um novo token de transação externa precisa ser gerado sempre que o usuário acessar um site ou app externo pela API de pagamentos externos. Para isso, chame a API createBillingProgramReportingDetailsAsync. O token precisa ser gerado imediatamente antes de launchBillingFlow ser chamado.

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.
      }
});

Se você usa as extensões do Kotlin, pode usar as corrotinas do Kotlin para não precisar definir um listener separado.

Iniciar o fluxo de pagamentos externos

Inicie o fluxo de pagamentos externos chamando launchBillingFlow() de maneira semelhante a iniciar um fluxo de compra com uma integração do sistema de faturamento do Google Play, mas com um parâmetro adicional DeveloperBillingOptionParams fornecido, indicando que o app quer ativar o fluxo de pagamentos externos para essa compra.

DeveloperBillingOptionParams precisa conter o seguinte:

Quando o app chama launchBillingFlow() com DeveloperBillingOptionParams fornecido, o sistema de faturamento do Google Play segue esta lógica:

  • O sistema verifica se o país do Google Play do usuário oferece suporte a pagamentos externos (ou seja, um país com suporte). Em caso positivo, o Google Play vai verificar se os pagamentos externos estão ativados com base na configuração do BillingClient e se DeveloperBillingOptionParams foi fornecido.
    • Se os pagamentos externos tiverem sido ativados, o fluxo de compra vai mostrar a UX de escolha do usuário.
    • Se os pagamentos externos não estiverem ativados, o fluxo de compra vai mostrar a UX padrão do sistema de faturamento do Google Play, sem escolha do usuário.
  • Se o país do Google Play do usuário não tiver suporte, o fluxo de compra vai mostrar a UX padrão do sistema de faturamento do Google Play, sem escolha do usuário.

O país do Google Play do usuário tem suporte

O país do Google Play do usuário não tem suporte

Pagamentos externos ativados (configuração do BillingClient e launchBillingFlow)

A UX de escolha do usuário aparece

A UX padrão do sistema de faturamento do Google Play aparece para o usuário

Pagamentos externos não ativados (não ativados durante a configuração do BillingClient ou DeveloperBillingOptionParams não fornecidos para launchBillingFlow)

A UX padrão do sistema de faturamento do Google Play aparece para o usuário

A UX padrão do sistema de faturamento do Google Play aparece para o usuário

O snippet a seguir demonstra como 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();

Processar a seleção do usuário

A forma como você lida com o restante do fluxo de compra varia dependendo do usuário ter selecionado o sistema de faturamento do Google Play ou pagar no seu site.

Quando o usuário seleciona pagar no seu site ou em um app de pagamentos

Se o usuário escolher pagar no seu site, o Google Play vai chamar o DeveloperProvidedBillingListener para notificar o app de que o usuário escolheu pagar no seu site ou em um app de pagamentos. Em particular, o método onUserSelectedDeveloperBilling() é chamado.

Se o app definir launchMode como LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, o Google Play vai abrir o link. Se launchMode foi definido como CALLER_WILL_LAUNCH_LINK, o app é responsável por abrir o link. Ao vincular usuários a um app de pagamento, você é responsável por verificar se o usuário já tem o app instalado no dispositivo.

Use esse token para informar qualquer transação resultante dessa escolha, conforme explicado no guia de integração de back-end.

Quando o usuário seleciona o sistema de faturamento do Google Play

Se o usuário escolher o sistema de faturamento do Google Play, ele vai continuar com o fluxo de compra.

  • Consulte Como processar compras no guia de integração da biblioteca para mais informações sobre como processar novas compras no app usando o sistema de faturamento do Google Play.
  • Consulte Novas assinaturas no guia de gerenciamento de assinatura para outras orientações sobre compras de assinaturas.

Processar mudanças na assinatura

Para desenvolvedores que usam pagamentos externos, as compras precisam ser processadas pelo sistema de faturamento do Google Play ou informadas com um externalTransactionId, dependendo da escolha do usuário. As mudanças em assinaturas existentes que foram processadas pelo site do desenvolvedor podem ser feitas pelo mesmo sistema de faturamento até a expiração.

Esta seção descreve como lidar com alguns cenários comuns de mudança de assinatura.

Fazer upgrade e downgrade de fluxos

As mudanças no plano de assinatura, incluindo fluxos de upgrade e downgrade, precisam ser tratadas de maneira diferente, dependendo de a assinatura ter sido comprada originalmente pelo sistema de faturamento do Google Play ou pelo site do desenvolvedor.

Os complementos que dependem de uma assinatura atual, compartilham a mesma forma de pagamento e alinham as cobranças recorrentes são tratados como upgrades. Para outros complementos, os usuários precisam poder escolher qual sistema de faturamento querem usar. Inicie uma nova experiência de compra usando launchBillingFlow(), conforme descrito em iniciar o fluxo de pagamentos externos.

Assinaturas compradas no site do desenvolvedor ou em um app de pagamento

Para assinaturas que foram compradas originalmente no site do desenvolvedor ou em um app de pagamento após a escolha do usuário, aqueles que solicitarem um upgrade ou downgrade vão passar pelo site do desenvolvedor ou por um app de pagamento sem precisar passar pela experiência de escolha do usuário de novo.

Para fazer isso, chame launchBillingFlow() quando o usuário solicitar um upgrade ou downgrade. Em vez de especificar outros parâmetros no objeto SubscriptionUpdateParams, use setOriginalExternalTransactionId(), fornecendo o ID da transação externa para a compra original.

DeveloperBillingOptionParams também precisa ser fornecido nessa chamada. Isso não mostra a tela de escolha do usuário, já que a escolha original é preservada para upgrades e downgrades. Você precisa gerar um novo token de transação externa para essa transação, conforme descrito aqui.

Quando o upgrade ou downgrade for concluído usando o site do desenvolvedor ou um app de pagamento, você precisará informar uma nova transação usando o token de transação externa recebido na chamada anterior para a nova compra da assinatura.

Assinaturas compradas usando o sistema de faturamento do Google Play

Da mesma forma, os usuários que compraram a assinatura atual pelo sistema de faturamento do Google Play após a escolha do usuário precisam passar pelo fluxo padrão do Google Play Faturamento. DeveloperBillingOptionParams não pode ser definido na chamada para launchBillingFlow.

Cancelamentos e restaurações de assinaturas

Os usuários podem cancelar a assinatura quando quiserem. Quando um usuário cancela uma assinatura, a rescisão do direito pode ser adiada até o término do período pago. Por exemplo, se um usuário cancelar uma assinatura mensal na metade do mês, ele poderá continuar acessando o serviço por aproximadamente duas semanas até perder o acesso. Durante esse período, a assinatura ainda está tecnicamente ativa, ou seja, o usuário pode usar o serviço.

Várias vezes os usuários decidem reverter o cancelamento durante esse período ativo. Neste guia, isso é chamado de restauração. As próximas seções descrevem como lidar com cenários de restauração na integração da API de pagamentos externos.

Assinaturas compradas no site do desenvolvedor

Se você tiver um ID de transação externa para uma assinatura cancelada, não será necessário chamar o launchBillingFlow() para restaurar a assinatura. Ele não pode ser usado para esse tipo de ativação. Se o usuário restaurar a assinatura enquanto ainda estiver no período ativo de uma assinatura cancelada, nenhuma transação vai ocorrer nesse momento. Será possível continuar gerando relatórios sobre renovações quando o ciclo atual expirar e a próxima renovação ocorrer. Isso inclui casos em que o usuário recebe um crédito ou preço especial de renovação como parte da restauração (por exemplo, uma promoção para incentivar o usuário a manter a assinatura).

Assinaturas compradas usando o sistema de faturamento do Google Play

Geralmente, os usuários podem restaurar assinaturas no sistema de faturamento do Google Play. Para assinaturas canceladas que foram originalmente compradas no sistema de faturamento do Google Play, o usuário pode desfazer o cancelamento enquanto a assinatura estiver ativa usando o recurso Renovar assinatura. Nesse caso, você recebe uma notificação do desenvolvedor em tempo real SUBSCRIPTION_RESTARTED no seu back-end, e um novo token de compra não é emitido. O token original é usado para continuar a assinatura. Para saber como gerenciar a restauração no sistema de faturamento do Google Play, consulte Restaurações no guia de gerenciamento de assinaturas.

Também é possível acionar uma restauração no sistema de faturamento do Google Play pelo app chamando launchBillingFlow(). Consulte Antes da expiração da assinatura: no app para conferir uma explicação sobre como fazer isso. No caso de usuários que passaram pelo fluxo de escolha do usuário para a compra original (que foi cancelada, mas ainda está ativa), o sistema detecta automaticamente a escolha e mostra a interface do usuário para restaurar essas compras. É preciso confirmar a recompra da assinatura no Google Play, mas não é necessário passar pelo fluxo de escolha do usuário de novo. Nesse caso, um novo token de compra é emitido para o usuário. Seu back-end recebe uma notificação do desenvolvedor em tempo real SUBSCRIPTION_PURCHASED, e o valor linkedPurchaseToken do novo status de compra é definido como no caso de um upgrade ou downgrade, com o token de compra antigo da assinatura que foi cancelada.

Renovações de assinatura

Se uma assinatura expirar completamente, seja por cancelamento ou pagamento recusado sem recuperação (uma suspensão de conta expirada), o usuário vai precisar renovar a assinatura para recuperar o direito de acesso.

A renovação de uma assinatura também pode ser ativada pelo app, de forma semelhante a uma assinatura padrão. Os usuários precisam ser capazes de escolher qual sistema de faturamento querem usar. O launchBillingFlow() pode ser chamado nesse caso, conforme descrito em iniciar o fluxo de pagamentos externos.

Processamento de respostas

Quando um erro ocorre, os métodos isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() e launchBillingFlow() podem fornecer um BillingResponseCode diferente de BillingResponseCode.OK. Considere processar estes códigos de resposta da seguinte maneira:

  • BillingResponseCode.ERROR: este é um erro interno. Não prossiga com a transação nem abra o site externo. Tente de novo chamando a API outra vez.
  • BillingResponseCode.FEATURE_NOT_SUPPORTED: as APIs de pagamentos externos não são compatíveis com a Play Store no dispositivo atual. Não prossiga com a transação nem abra o site externo.
  • BillingResponseCode.DEVELOPER_ERROR: há um erro na solicitação. Use a mensagem de depuração para identificar e corrigir o erro antes de continuar.
  • BillingResponseCode.USER_CANCELED: não abra o site ou app externo. Chame launchBillingFlow() de novo para mostrar a caixa de diálogo de informações ao usuário na próxima vez que você tentar direcionar o usuário para fora do app.
  • BillingResponseCode.BILLING_UNAVAILABLE: a transação não está qualificada para pagamentos externos e, portanto, o faturamento do desenvolvedor não estará disponível neste programa. Isso ocorre porque o usuário não está em um país qualificado para o programa ou sua conta não foi inscrita nele. No último caso, verifique o status de registro no Google Play Console.
  • BillingResponseCode.NETWORK_ERROR, BillingResponseCode.SERVICE_DISCONNECTED, BillingResponseCode.SERVICE_UNAVAILABLE: são erros temporários que precisam ser tratados com uma política de novas tentativas adequada. No caso de SERVICE_DISCONNECTED, restabeleça uma conexão com o Google Play antes de tentar de novo.

Testar links de pagamentos externos

Os testadores de licença devem ser usados para testar sua integração de pagamentos externos. Você não vai receber faturas por transações iniciadas por contas de teste de licença. Consulte Testar o faturamento em apps com o licenciamento de apps para mais informações sobre como configurar testadores de licença.

Próximas etapas

Depois de concluir a integração no app, estará tudo pronto para integrar seu back-end.