Lembrete
1. A partir de 2 de agosto de 2023, todos os novos apps precisarão usar a versão 5 ou mais recente da Biblioteca Faturamento. A partir de 1º de novembro de 2023, isso também será válido para todas as atualizações dos apps atuais. Saiba mais.
2. Caso o app seja direcionado ao Android 14 ou mais recente, atualize para a Biblioteca Play Faturamento 5.2.1, 6.0.1 ou mais recente.

Orientações sobre a integração de back-end para faturamento alternativo (somente na República da Coreia)

A API Google Play Developer agora inclui mais funcionalidades para relatar transações de um sistema de faturamento alternativo. Neste guia, descrevemos como usar a nova funcionalidade para informar transações de faturamento alternativo.

Há alguns componentes que podem ser necessários para processar no seu back-end as compras no app. Para criá-los, você precisa configurar sua integração de back-end conforme indicado em Configurar a API Google Play Developer. Para todas as funcionalidades de back-end do desenvolvedor que não são específicas de APIs de faturamento alternativo, são aplicadas as instruções da documentação do sistema de faturamento do Google Play.

Informar novas transações externas ao Google Play

Integre com Externaltransactions APIs para informar transações que acontecem fora do sistema do Google Play na República da Coreia, incluindo transações de US$ 0 resultantes de compras de teste sem custo financeiro. As transações em sistemas alternativos de faturamento só podem ser informadas para países de usuários qualificados, e a chamada de API falha em outros casos. Essa limitação se aplica a todas as transações, incluindo novas compras, renovações, recargas, upgrades, downgrades, entre outras.

Relatórios de transações externas

Chame Externaltransactions API para relatar uma transação externa depois que o pagamento for autorizado pelo sistema alternativo de faturamento. Isso se aplica a todas as transações, incluindo cobranças iniciais, renovações, reembolsos e outros. Todas as transações precisam ser informadas em até 24 horas após a ocorrência.

Cada transação externa é informada com um ID de transação externo. Para compras recorrentes (como assinaturas renováveis automaticamente), é necessário enviar o ID da transação externa associado à primeira transação na compra recorrente como um parâmetro para qualquer transação seguinte, incluindo reembolsos. Isso registra a série de transações para a compra. Envie um novo ID de transação externa para compras quando o produto mudar (como um upgrade ou downgrade) ou se a transação recorrente for cancelada ou expirar e o mesmo produto for comprado de novo mais tarde. Não inclua informações de identificação pessoal como parte desse ID de transação externa.

Informar uma nova compra

Sempre que uma nova compra é concluída no sistema alternativo de faturamento, é preciso fazer uma chamada para a API Externaltransactions. Para essas novas compras, é necessário fornecer um externalTransactionId exclusivo associado à compra no back-end como um parâmetro de consulta. Esse externalTransactionId não pode ser reutilizado no mesmo ID de pacote do app.

O externalTransactionToken recebido pelo app pelo callback AlternativeBillingListener também é necessário como parte do corpo da solicitação para compras únicas e primeira transação em uma compra recorrente, como uma assinatura. Em ambos os casos, isso é chamado de transação inicial. Após a transação inicial, o externalTransactionToken não é mais necessário e você informa transações seguintes, como renovações de assinatura, fornecendo um novo externalTransactionId exclusivo. Consulte Informar transações seguintes de uma compra para mais detalhes sobre isso.

Exemplo:

  1. O desenvolvedor configura e ativa o faturamento alternativo no app.
  2. O usuário 1 está na Coreia do Sul e está tentando comprar product1 por 12.634,10 KRW/mês, com uma oferta de teste gratuito de um mês.
  3. O app inicia o fluxo de compra com o ProductDetails para product1 e a oferta que o usuário selecionou.
  4. O usuário 1 seleciona o sistema alternativo de faturamento do desenvolvedor.
  5. O AlternativeBillingListener recebe o valor my_token como o externalTransactionToken.
  6. Em seguida, o desenvolvedor envia as informações pertinentes para o back-end (valor de externalTransactionToken e produtos sendo comprados). Em seguida, ele inicia o fluxo de compra para product no sistema alternativo de faturamento. Essa transação recebe um ID exclusivo no lado do desenvolvedor, que é usado para informar o Google Play: 123-456-789. O ID da transação é obrigatório, mesmo que o usuário esteja recebendo um teste gratuito.
  7. Depois que a transação é realizada no sistema alternativo de faturamento, o desenvolvedor informa a transação ao Google Play com a solicitação abaixo. Ela é registrada inicialmente como uma transação de zero dólar, porque o usuário recebe um mês sem custos.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "external_subscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Informar transações seguintes de uma compra

Em alguns casos, há mais de um pagamento do usuário associado à mesma compra externa. Por exemplo, renovações de assinatura ou recargas de planos pré-pagos. É possível informar essas transações seguintes usando a mesma API em Externaltransactions. Conforme descrito em Informar uma nova compra, o externalTransactionToken não é necessário para transações seguintes. Em vez disso, um novo externalTransactionId exclusivo é enviado como parâmetro de consulta para cada transação de renovação ou recarga, com o ID da transação inicial incluído no campo initialExternalTransactionId.

Seguindo o exemplo anterior:

  1. A primeira renovação do usuário 1 ocorre no sistema alternativo de faturamento. O ID da transação original era 123-456-789.

  2. O desenvolvedor informa a recorrência da transação no parâmetro de consulta do URL como o ID externo dessa nova transação, fazendo referência ao ID externo da transação inicial no campo initialExternalTransactionId.

Exemplo de solicitação:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "external_subscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Informar upgrade ou downgrade

Para informar um upgrade ou downgrade quando o usuário for proprietário de uma assinatura no sistema alternativo de faturamento, use o mesmo endpoint e função na API Externaltransactions enviando o externalTransactionToken que foi fornecido ao app para a transação de upgrade ou downgrade. Isso é parecido com o processo de informar uma nova compra.

Informar reembolsos de compras ao Google Play

Integre com a API Externaltransactions para informar transações reembolsadas a usuários fora do sistema de faturamento do Google Play. Para que o Google Play identifique corretamente qual transação foi reembolsada, inclua o externalTransactionId correspondente para a transação informada anteriormente como parte dos parâmetros de URL.

Ao informar reembolsos de compras de assinatura, consulte o externalTransactionId da recorrência específica da assinatura que está sendo reembolsada.

Exemplo: suponha que uma assinatura tenha estas transações:

  • Uma transação inicial com o ID da transação externa ABC.1234-5678-9012-34567

  • A primeira transação recorrente com o ID da transação externa ABC.1234-5678-9012-34567..0

  • A segunda transação recorrente com o ID da transação externa ABC.1234-5678-9012-34567..1

Para informar um reembolso de todas as transações de assinatura, faça três solicitações de reembolso separadas: uma para a transação inicial e duas para as seguintes.

Esse método aceita reembolsos totais, em que o valor é o mesmo que o usuário pagou na transação externa original, e reembolsos parciais, em que o valor é menor do que o usuário pagou na transação externa original. Para reembolsos parciais, é necessário especificar o valor sem tributos que foi reembolsado.

Cotas da API

A API Externaltransactions está sujeita a cotas diárias de API para todas as chamadas, assim como qualquer outro endpoint da API Google Play Developer.

Além disso, a API Externaltransactions tem um limite de 1.200 consultas por minuto (QPM) para chamadas de Externaltransactions.createexternaltransaction ou Externaltransactions.refundexternaltransaction. As chamadas de Externaltransactions.getexternaltransaction não são contabilizadas no limite de 1.200 QPM.