Orientações de integração de back-end para monetização fora do Google Play Faturamento

A API Google Play Developer agora inclui recursos adicionais para relatar transações de um faturamento alternativo ou sistema de ofertas externas. Neste guia, descrevemos como informar faturamento ou transações de promoções externas.

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 sejam específicas do faturamento alternativo ou de promoções externas, as instruções da Sujeito à documentação do sistema de faturamento do Google Play.

Informar novas transações externas ao Google Play

Integrar com Externaltransactions APIs para informar transações que acontecem fora do sistema de faturamento do Google Play países com suporte, incluindo transações de US $0 resultantes do teste sem custo financeiro compras. Transações em sistemas de faturamento alternativo ou de promoções externas só deve ser iniciada e informada para os países de usuários qualificados, conforme permitido no faturamento alternativo ou programas de ofertas externas. Caso contrário, a chamada de API será recusados. Isso se aplica a todas as transações, incluindo novas compras, renovações recargas, upgrades, downgrades, entre outros.

Relatórios de transações externas

Chame Externaltransactions API para informar uma transação externa. depois que o pagamento for autorizado por meio do método de faturamento alternativo ou sistema de promoções externas. Isso se aplica a todas as transações, incluindo cobranças, renovações, reembolsos, entre outros. Todas as transações precisam ser informados em até 24 horas após a ocorrência da transação.

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 confidenciais e reservadas ou confidenciais como parte ID da transação.

Informar uma nova compra

Sempre que uma nova compra for concluída no faturamento alternativo ou sistema de promoções externas, será feita uma chamada à API Externaltransactions obrigatórios. Para essas novas compras, você precisa fornecer um único externalTransactionId associado à compra no back-end como uma consulta. . Esse externalTransactionId não pode ser reutilizado no mesmo app ID do pacote.

O externalTransactionToken recebido pelo app usando o UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener ou ExternalOfferReportingDetailsListener também são necessários como parte o corpo da solicitação para compras únicas e transações iniciais em um compra recorrente (como uma assinatura). Em ambos os casos, isso é chamado uma transação inicial. Após a transação inicial, o externalTransactionToken não é mais necessário, e você reporta transações (como renovações de assinatura), fornecendo um novo campo externalTransactionId. Consulte Informar transações seguintes de uma compra. para mais detalhes sobre como informar transações seguintes.

Exemplo:

1. O desenvolvedor configura e ativa o faturamento alternativo no app.
2. O usuário 1 está na Coreia do Sul, um país com suporte, 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 UserChoiceBillingListener 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 product1 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 grátis.

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",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Observação: subscriptionType pode ser RECURRING (para assinaturas com renovação automática) ou PREPAID (para assinaturas pré-pagas).

Observação: OtherRecurringProduct pode ser usado para representar compras únicas. que exigem vários pagamentos ou um pagamento atrasado. Por exemplo, uma encomenda pode ter uma transação inicial de US $0,00 seguida por uma segunda transação em um segundo a data do preço da SKU em que a encomenda é concluída. Consulte Informar as transações seguintes de uma compra para mais detalhes sobre os relatórios transações seguintes.

Observação: informar uma transação de uma compra usando apenas o faturamento alternativo ou as promoções externas são iguais às anteriores, exceto pelo fato de que externalTransactionToken é conseguidos usando as etapas descritas no faturamento alternativo exclusivo ou guia de promoções externas.

Se você fizer transações com um usuário que mora na Índia, onde os tributos variam dependendo da área político-administrativa (como estado ou província), inclua essa área em userTaxAddress. Consulte a lista predefinida de strings no guia de referência da API para conferir as áreas político-administrativas aplicáveis.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

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 as 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 inicial 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",

   "externalSubscription" {
     "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.

Migrar dos relatórios manuais de transações de faturamento alternativo

Observação: relatórios manuais apenas de faturamento alternativo e escolha de faturamento do usuário será desativado. Para mais detalhes sobre os prazos de migração, consulte Noções básicas sobre a escolha de faturamento do usuário no Google Play. Confirme para migrar todas as assinaturas ativas iniciadas enquanto você oferecia faturamento alternativo sem relatórios automatizados pelo Externaltransactions API antes da desativação dos relatórios manuais.

Para migrar assinaturas ativas iniciadas enquanto você oferecia faturamento alternativo sem relatórios automatizados, crie uma nova transação de custo zero usando o campo migratedTransactionProgram em vez de especificar um initialExternalTransactionId ou externalTransactionToken. Defina transactionTime como a hora em que o usuário se inscreveu inicialmente para cada assinatura ativa. Em seguida, informe normalmente cada transação subsequente para essas assinaturas usando as APIs, fornecendo o initialExternalTransactionId usado acima para criar as transações de renovação. Depois que a assinatura for migrada, não será mais necessário informar manualmente as próximas transações, desde que elas sejam informadas pelos métodos automatizados descritos nesta página.

Ao migrar assinaturas, considere os limites de cota para garantir que a migração não cause uma interrupção da cota. Se muitas assinaturas precisarem sejam migrados, distribua-os em vários dias ou solicite um aumento na cota ,

Observação: somente os desenvolvedores que ofereceram um faturamento alternativo sem relatórios automatizados poderão definir o campo migratedTransactionProgram. Se você já ofereciam faturamento alternativo sem automação e estão recebendo erro ao tentar fazer uma solicitação para migrar a assinatura, é possível entrar em contato com nossa equipe de suporte para receber ajuda.

O campo migratedTransactionProgram só pode ser usado ao migrar de relatórios manuais. Ele será descontinuado quando os relatórios manuais não forem mais aceitos.

Exemplo de solicitação:

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

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

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

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

Denunciar programas de parcerias do Google Play

Desenvolvedores que participam de programas de parcerias, como O Programa Play Media Experience precisa oferecer as transaction_program_code ao informar transações externas. Se você for um desenvolvedor qualificado, entre em contato com seu Gerente de desenvolvimento comercial para obter informações sobre como definir este campo.

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 valor pago pelo usuário no transação) e reembolsos parciais (quando o valor é menor do que o que o usuário pagou no link externo original transação). 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.