A API Google Play Developer inclui mais funcionalidades para relatar transações de programas de faturamento e links. Neste guia, descrevemos como informar transações desses programas de faturamento.
Há alguns componentes que podem ser necessários para processar transações externas no seu back-end. Para criá-los, você precisa configurar sua integração de back-end conforme indicado em Configurar a API Google Play Developer. Para criar funcionalidades de back-end do desenvolvedor que não sejam específicas de programas de faturamento e link, consulte o sistema de faturamento do Google Play.
Glossário de termos
Convenções de termos seguidas por este guia:
- Programas de faturamento e links: programas que facilitam compras de conteúdo digital ou downloads de apps fora do Google Play. Isso inclui os programas de faturamento alternativo e conteúdo externo.
- APIs de transações externas: APIs usadas para informar transações de programas de faturamento e vinculação qualificados.
- Transação externa: uma transação qualificada que ocorre fora do app, conforme definido pelos programas de faturamento alternativo e conteúdo externo.
- Token de transação externa: um token fornecido pela Biblioteca Play Faturamento para você usar quando o usuário iniciar uma transação externa. Esse token é usado para notificar o Google Play sobre uma transação externa autorizada.
- ID da transação externo: um identificador exclusivo gerado por você para identificar uma transação externa.
Configurar as permissões do Play Console
Para chamar a API externaltransactions para informar ou reembolsar transações externas, conceda à sua conta de serviço a permissão Gerenciar pedidos e assinaturas no Google Play Console. É possível conceder
essa permissão no nível da conta ou para apps específicos.
Para instruções sobre como criar uma conta de serviço e conceder permissões no Play Console, consulte Usar uma conta de serviço. Para mais informações sobre as permissões do Play Console, consulte Adicionar usuários da conta de desenvolvedor e gerenciar permissões.
Informar novas transações externas ao Google Play
Integre com a API externaltransactions para informar transações que acontecem fora do sistema de faturamento do Google Play em países com suporte, incluindo transações de US $0 resultantes de compras de teste sem custo financeiro e instalações de apps. Você só deve iniciar e informar transações em programas de faturamento e links
para países de usuários qualificados, conforme permitido pelos programas de
faturamento alternativo e de conteúdo externo. Caso contrário, a chamada de API
será recusada. Isso se aplica a todas as transações, incluindo novas compras,
renovações, recargas, upgrades, downgrades e downloads de apps.
Relatórios de transações externas
Chame a API externaltransactions para informar uma transação externa
depois que um pagamento for autorizado por um programa de faturamento e link.
Isso se aplica a todas as transações, incluindo cobranças iniciais, renovações, reembolsos
e outros. Consulte as diretrizes do respectivo programa de faturamento e vinculação para
conhecer os requisitos de relatórios.
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, reservadas ou confidenciais como parte do ID da transação externa.
Informar uma transação inicial
Sempre que uma nova compra ou download de app for autorizado nos programas de faturamento e link, você precisará chamar a API externaltransactions.
O externalTransactionToken recebido pelo app pela Biblioteca Google Play Faturamento é necessário como parte do corpo da solicitação para downloads de apps, compras únicas e primeira transação em uma compra recorrente, como uma assinatura. Isso é chamado de transação inicial. Após a transação inicial, informe as transações seguintes, como renovações de assinatura, fornecendo um novo externalTransactionId exclusivo. Para mais informações, consulte
Informar transações seguintes de uma compra.
Exemplo:
- O desenvolvedor configura e ativa o faturamento alternativo no app.
- O usuário 1 está na Coreia do Sul, um país com suporte, e está tentando comprar
product1por 12.634,10 KRW/mês, com uma oferta de teste sem custo financeiro de um mês. - O app inicia o fluxo de compra com o
ProductDetailsparaproduct1e a oferta que o usuário selecionou. - O usuário 1 seleciona o sistema alternativo de faturamento do desenvolvedor.
- O
UserChoiceBillingListenerrecebe o valormy_tokencomo oexternalTransactionToken. - Em seguida, o desenvolvedor envia as informações pertinentes para o back-end
(valor de
externalTransactionTokene produtos sendo comprados). Em seguida, ele inicia o fluxo de compra paraproduct1no 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 sem custo financeiro. - 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",
"externalSubscription" : {
"subscriptionType" : "RECURRING"
}
},
"userTaxAddress" : {
"regionCode" : "KR"
}
}
Ao informar uma transação inicial, considere o seguinte:
subscriptionTypepode serRECURRING(para assinaturas de renovação automática) ouPREPAID(para assinaturas pré-pagas).OtherRecurringProductprecisa ser usado para representar compras únicas que exigem vários pagamentos ou um pagamento atrasado. Por exemplo, uma compra na pré-venda pode ter uma transação inicial de US $0 seguida por uma segunda transação em uma data posterior pelo preço do SKU quando a compra na pré-venda for concluída. Consulte Informar transações seguintes de uma compra para mais detalhes sobre isso.- É preciso informar
ExternalOfferDetailsao relatar as transações iniciais de promoções externas. Isso não é necessário para transações subsequentes.
Se você fizer transações com um usuário 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"
}
}
Promoções externas
Se a transação que está sendo informada estiver no programa de promoções externas, você
precisará definir o campo externalOfferDetails se a transação for única
ou a primeira de uma série recorrente:
- Ao informar transações de download de apps, defina
linkTypecomoLINK_TO_APP_DOWNLOADe forneça os valores apropriados parainstalledAppPackageeinstalledAppCategory. Consulte Informar o download de um app para mais detalhes. - Ao informar transações de ofertas de conteúdo digital, defina
linkTypecomoLINK_TO_DIGITAL_CONTENT_OFFER. - Depois que um app externo é instalado pelo programa de promoções externas, você
precisa informar as transações feitas nele. Ao informar essas
transações, vincule-as ao evento de download do app original:
- Informe o
externalTransactionTokendo evento de download do app. - No campo
externalOfferDetails, definaappDownloadEventExternalTransactionIdcomo oexternalTransactionIddo evento de download do app. Os outros campos emexternalOfferDetailsnão são obrigatórios.
- Informe o
Exemplo de solicitação de transação em um app externo baixado por promoções externas:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "990000", # 0.99 EUR
"currency" : "EUR"
},
"originalTaxAmount" : {
"priceMicros" : "90000", # 0.09 EUR
"currency" : "EUR"
},
"transactionTime" : "2025-11-22T12:45:00Z",
"oneTimeTransaction" : {
"externalTransactionToken" : "my_external_transaction_token_for_link_to_download_event"
},
"userTaxAddress" : {
"regionCode" : "DE"
},
"externalOfferDetails" : {
"appDownloadEventExternalTransactionId" : "my_external_transaction_id_for_link_to_download_event"
}
}
Os detalhes atualizados da taxa de serviço do Google Play para diferentes tipos de transação podem ser encontrados em Mudanças no Programa de Promoções Externas para usuários no Espaço Econômico Europeu (EEE).
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:
- A primeira renovação do usuário 1 ocorre no sistema alternativo de faturamento. O ID da transação inicial era 123-456-789.
- O desenvolvedor informa a recorrência da transação no parâmetro de consulta do URL como o ID da transação externa para essa nova transação, fazendo referência ao ID da transação externa 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", # 12634 KRW
"currency" : "KRW"
},
"originalTaxAmount" : {
"priceMicros" : "1263000000", # 1263 KRW
"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.
Informar o download de um app
Para informar uma instalação de app no sistema de faturamento de promoções externas, chame Externaltransactions.createexternaltransaction, enviando o externalTransactionToken que foi fornecido ao app. Informe isso como uma transação única e sem custo financeiro. Esse processo é semelhante a informar uma transação inicial. Inclua ExternalOfferDetails no
corpo da solicitação.
Exemplo de solicitação:
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789
Body
{
"originalPreTaxAmount" : {
"priceMicros" : "0",
"currency" : "USD"
},
"originalTaxAmount" : {
"priceMicros" : "0",
"currency" : "USD"
},
"transactionTime" : "2025-12-22T12:45:00Z",
"oneTimeTransaction" : {
"externalTransactionToken" : "my_token",
},
"userTaxAddress" : {
"regionCode" : "US"
},
"externalOfferDetails" : {
"linkType" : "LINK_TO_APP_DOWNLOAD",
"installedAppPackage" : "my.external.app",
"installedAppCategory" : "APP"
}
}
Migrar dos relatórios manuais de transações de faturamento alternativo
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 anteriormente 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 ser migradas, distribua-as em vários dias ou solicite um aumento da cota.
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"
}
}
Requisitos para programas de parcerias do Google Play
Os desenvolvedores que participam de programas de parceria, como o Programa Play Media Experience, precisam fornecer o transaction_program_code ao informar transações externas. Se você é um desenvolvedor qualificado, entre em contato com seu gerente de desenvolvimento de negócios para mais informações sobre como definir esse 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 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 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.