Uma compra pendente parece uma venda, mas o dinheiro não chegou, e concedê-la cedo demais dá o produto de graça

Alguém toca em comprar no seu app. Seus logs mostram um pedido novo, seu listener de cobrança dispara, e você entrega a mercadoria. Na maioria das compras isso é exatamente o certo. Em uma compra pendente é um erro, porque o pedido existe mas o dinheiro não. O cliente escolheu um método de pagamento que é liquidado depois, a loja ainda espera receber, e você acabou de entregar um recurso pago por uma cobrança que talvez nunca seja compensada. Este é o primo silencioso de um reembolso. Aqui nada é revertido, porque nada chegou a ser cobrado. Você simplesmente deu o produto de graça.

Uma compra pendente é um pedido real em um estado ainda não pago, e tanto a App Store quanto o Google Play têm um. As duas lojas dizem claramente para esperar. A armadilha é que um pedido pendente parece quase idêntico a um concluído no seu código, então uma integração que trata cada compra nova como uma venda entrega mercadoria em pedidos que a loja ainda tenta cobrar. Trate isso corretamente e você não perde nada. Trate errado e cada pagamento lento que não se concretiza é puro custo, entregue às suas custas.

O que é de fato uma compra pendente

Uma compra pendente é um pedido que a loja registrou mas ainda não cobrou. O comprador iniciou o fluxo, a loja aceitou, e a liquidação acontece em algum lugar que seu app não consegue ver. O Google Play chama isso de estado PENDING. A Apple chama de transação pendente, ou diferida. Nomes diferentes, mesmo fato: a loja mantém um pedido aberto enquanto espera receber, e disse a você para não tratar esse pedido como dinheiro.

Google Play: o pagamento acontece em outro lugar

Alguns métodos de pagamento são liquidados fora de banda. Dinheiro em uma loja física, transferências bancárias e parte da cobrança pela operadora exigem passos adicionais entre o toque e a cobrança. Quando um cliente escolhe um deles, o Google retorna a compra no estado PENDING em vez de PURCHASED. Em um pagamento em dinheiro, o cliente recebe um código por notificação e por e-mail, leva-o a uma loja participante e paga ao caixa. Até isso acontecer, o Google não cobrou nada, e você também não. A regra do Google é uma linha: use getPurchaseState() e conceda o direito apenas quando o estado for PURCHASED. Ela também diz para não confirmar uma compra enquanto ela estiver em PENDING, porque a confirmação pertence a um pedido pago, não a um prometido.

Apple: a compra espera o toque de outra pessoa

O estado pendente da Apple significa que a transação precisa de uma ação externa antes de poder ser concluída. A mais comum é Ask to Buy, em que uma criança inicia uma compra e um organizador da família precisa aprová-la. No StoreKit 2, a chamada de compra retorna Product.PurchaseResult.pending. No StoreKit mais antigo, a transação é reportada como diferida. De todo modo, a Apple não cobrou de ninguém, e a transação finalizada, se vier, chega de forma assíncrona por meio de Transaction.updates. Mostre ao cliente um estado de espera e não libere nada até a transação concluída chegar.

Por que conceder uma compra pendente custa dinheiro de verdade

A perda aqui não é do tipo reembolso, em que o dinheiro que você contabilizou é retirado. É pior em um aspecto específico: não há dinheiro a retirar, porque nada chegou a ser cobrado.

Você entrega, e a loja nunca recebe

Quando você libera em um pedido pendente que depois cancela, já gastou para atendê-lo. O processamento que rodou o recurso, as chamadas de API de terceiros que você pagou, o armazenamento que alocou e, para um consumível, o pagamento real da coisa que vendeu. Tudo isso sai pela porta em um pedido que não gerou receita. Um reembolso ao menos parte de uma cobrança que aconteceu. Uma compra pendente concedida por engano nunca teve cobrança alguma, então nem aparece como dinheiro saindo. Aparece como nada, que é exatamente por que é fácil passar despercebido e fácil de repetir.

O sinal de cancelamento, e o que ele significa

A loja de fato avisa você quando um pedido pendente morre. No Google Play, um produto avulso que não se concretiza envia uma notificação ONE_TIME_PRODUCT_CANCELED, tipo 2, e uma assinatura que estava pendente envia SUBSCRIPTION_PENDING_PURCHASE_CANCELED, tipo 20. Quando esses mesmos pedidos, em vez disso, se concretizam, você recebe ONE_TIME_PRODUCT_PURCHASED, tipo 1, ou SUBSCRIPTION_PURCHASED, tipo 4. Na Apple não há evento de cancelamento a capturar, porque uma transação diferida que é recusada simplesmente nunca se torna uma transação concluída. Se você liberou cedo demais, esse silêncio é a conta.

A janela, e quem espera por quem

Uma compra pendente não é um relógio contra o qual você corre. É um relógio que, do seu lado, não começou.

O Google Play dá ao cliente dias, não minutos

Um pagamento em dinheiro ou por transferência bancária é liquidado no ritmo do cliente, não no seu. O pedido fica em PENDING até o cliente pagar ou a janela se esgotar e o Google cancelá-lo. Sua própria janela de confirmação de três dias, aquela que reembolsa automaticamente uma compra que você deixa de confirmar, nem começa até a compra passar de PENDING para PURCHASED. Então não há pressa para atender um pedido pendente. Há apenas a disciplina de esperar o estado mudar.

A aprovação da Apple está no telefone do organizador da família

Um pedido de Ask to Buy chega ao dispositivo do organizador como um aviso que ele aprova ou recusa quando puder. Isso pode ser minutos, horas ou um dia depois, e seu app não pode apressá-lo. O único comportamento correto é refletir o estado de espera e deixar o StoreKit lhe entregar a transação concluída se e quando a aprovação vier.

Como lidar com compras pendentes sem vazamento

Todo o trabalho se resume a quatro hábitos. Nenhum deles é difícil, e pular qualquer um é por onde o dinheiro vai embora.

Conceda no estado pago, nunca no pendente

No Google Play, verifique getPurchaseState() e conceda apenas em PURCHASED, e não confirme uma compra enquanto ela estiver em PENDING. Na Apple, libere apenas em uma transação concluída e nunca no resultado pendente. Essa única regra fecha todo o vazamento. Todo o resto é garantir que você de fato perceba quando o estado pago chega.

Verifique de novo quando o app voltar

A transição de pendente para pago costuma acontecer enquanto seu app não está em execução. No Google Play, chame queryPurchasesAsync() no seu handler onResume() para captar pedidos que viraram PURCHASED em segundo plano, e mantenha seu listener de Real-time Developer Notifications como a fonte da verdade do lado do servidor. Na Apple, escute Transaction.updates por toda a vida do app, porque uma transação aprovada pode chegar muito depois de a chamada de compra original ter retornado.

Ative o suporte a pendentes e teste os dois desfechos

O Google exige que você chame enablePendingPurchases() ao construir o BillingClient, e dar suporte a transações pendentes para produtos avulsos é obrigatório, não opcional. Teste antes de publicar. Testadores licenciados recebem dois instrumentos de teste extras para formas de pagamento diferidas, em que o pagamento se conclui automaticamente ou se cancela automaticamente depois de alguns minutos, para que você possa observar de ponta a ponta tanto o caminho do pagamento quanto o caminho da desistência.

Diga ao cliente que o pedido não está concluído

Um comprador pendente é um cliente real no meio de uma compra, não uma falha. Mostre a ele que o pedido espera o pagamento ou uma aprovação, e dê um caminho claro de volta para concluí-lo. Um estado pendente silencioso perde vendas que um bem sinalizado recupera, porque a maioria desses compradores ainda quer a coisa e só tem um passo restante.

Os mesmos feeds de Real-time Developer Notifications e App Store Server Notifications que o RefundHalt já lê para reembolsos e estornos também carregam esses sinais. A notificação de compra que diz que um pedido pendente enfim foi compensado, e a de cancelamento que diz que não foi, chegam ao seu painel ao lado do resto dos seus eventos de receita, então um pedido pendente que não se concretizou é algo que você pode ver em vez de algo que pagou por acidente.

A versão curta

Uma compra pendente é um pedido sem pagamento, e as duas lojas são explícitas em que você deve esperar. O Google Play retorna pedidos em dinheiro, por transferência bancária e parte da cobrança pela operadora em um estado PENDING e diz para conceder acesso apenas em PURCHASED. A Apple retorna uma transação pendente ou diferida para Ask to Buy e outras ações necessárias e entrega a transação concluída depois por meio de Transaction.updates. Libere no estado pago, verifique de novo quando seu app for retomado, ative e teste o suporte a pendentes, e sinalize o pedido em espera para o cliente. Faça isso e uma compra pendente não custa nada. Pule e você entrega um produto pago por uma cobrança que nunca veio, que é a única perda sem recibo para apontar.