Pagamento por pedido explicado: o push STK bem feito

O pagamento por pedido é o fluxo que todo o cliente de mobile money conhece de cor sem nunca pensar nele. Um comerciante pede dinheiro, aparece um pedido no telefone do cliente, ele introduz o PIN e está feito. É o padrão de pagamento mais usado nos mercados que adotaram cedo o mobile money, e parece não exigir esforço nenhum. Essa facilidade é fruto de uma quantidade surpreendente de engenharia que trabalha arduamente para ficar invisível. Basta errar uma parte e a magia transforma-se numa cobrança em dobro, num pagamento bloqueado ou num comerciante que entregou mercadoria por dinheiro que nunca chegou.

Eis o que acontece de facto por trás do pedido, e o que é preciso para o tornar instantâneo, seguro e imune a cobranças em dobro.

Duas formas de o pedido chegar

Há dois mecanismos por trás de "aparece um pedido", e importam porque têm alcance e modos de falha diferentes.

O mecanismo clássico é o SIM Application Toolkit (STK): código que corre no próprio cartão SIM, razão pela qual consegue mostrar um pedido seguro de PIN num telefone básico sem nenhuma aplicação instalada. Foi com o STK que os primeiros sistemas de mobile money chegaram a toda a gente: o menu e a introdução do PIN são comandados a partir do SIM, pela rede, num aparelho que não tem mais nada. O mecanismo moderno é a notificação de aplicação: uma notificação para uma aplicação de smartphone que abre um ecrã de confirmação. Ambos terminam no mesmo ponto: o cliente autoriza e uma cobrança percorre o seu ciclo de vida. Uma plataforma que valha a pena suporta ambos, porque a base de clientes usa ambos.

A cobrança é uma máquina de estados

A ideia mais importante do pagamento por pedido é que uma cobrança não é um evento: é uma máquina de estados com um conjunto explícito e bem definido de estados e transições. Tratá-la como uma chamada "envia e esquece" é a raiz da maioria dos incidentes em produção. Os estados são, aproximadamente:

• Pendente: o comerciante pediu uma cobrança; o pedido foi enviado; o sistema aguarda o cliente.
• Autorizada: o cliente introduziu o PIN e confirmou; o sistema verificou o saldo e os limites e está a registar o movimento.
• Concluída: o razão lançou entradas equilibradas; o dinheiro moveu-se; o comerciante pode entregar.
• Recusada / Expirada / Falhada: o cliente recusou, o pedido expirou ou uma verificação falhou; nenhum dinheiro se moveu e a cobrança é fechada de forma limpa.

Cada cobrança está exatamente num destes estados a cada momento, e só pode mover-se por transições definidas. Isto não é burocracia: é o que torna o fluxo compreensível e recuperável. Quando algo corre mal, a pergunta é sempre "em que estado está esta cobrança e que transição ficou parada?", uma pergunta com resposta, em vez de um encolher de ombros.

Como o comerciante fica a saber o resultado

O sistema do comerciante precisa de saber se a cobrança foi concluída: para imprimir um recibo, entregar a mercadoria, atualizar uma encomenda. Há duas formas de o saber, e a diferença entre elas é a diferença entre uma integração lenta e uma integração nítida.

1. Consulta periódica (polling). O comerciante pergunta repetidamente ao endpoint de estado: "já está?". Funciona, mas é desperdício e tem atraso: consulte demasiadas vezes e sobrecarrega a API; consulte poucas e o cliente fica à espera na caixa.
2. Webhooks. A plataforma envia ao comerciante um callback assinado no instante em que a cobrança muda de estado. O comerciante fica a saber em momentos, sem chamadas desperdiçadas, e recebe um evento limpo para agir. Esta é a primitiva certa, e uma plataforma bem construída torna-a o comportamento padrão, com a consulta como alternativa.

O que o torna fiável

Três propriedades transformam uma demonstração que funciona num sistema sobre o qual um comerciante pode construir um negócio.

Idempotência: o fim da cobrança em dobro

As redes repetem pedidos. Se o pedido "criar cobrança" de um comerciante expira e ele o reenvia, não pode criar uma segunda cobrança. Cada pedido de criação leva uma chave de idempotência; a plataforma regista-a, e uma repetição com a mesma chave devolve a cobrança original em vez de iniciar uma nova. A mesma disciplina protege o passo de confirmação. A garantia que o cliente sente, "só fui cobrado uma vez", é esta propriedade, aplicada no ponto em que o dinheiro se move, e não uma verificação esperançosa na aplicação.

Webhooks assinados

Um webhook é uma chamada HTTP não solicitada que chega ao servidor do comerciante a afirmar que um pagamento foi concluído. Porque haveria ele de acreditar? Porque cada callback é assinado: uma assinatura HMAC-SHA256 calculada sobre o conteúdo com um segredo partilhado que só a plataforma e o comerciante conhecem. O comerciante recalcula a assinatura e rejeita tudo o que não corresponda, o que torna inúteis para um atacante os falsos callbacks "foi pago". E como as redes falham, os webhooks são repetidos com intervalos crescentes até serem confirmados, para que uma falha momentânea do comerciante não faça perder o evento: é reenviado até o servidor dele responder com sucesso.

Expiração

Uma cobrança não confirmada não pode ficar pendurada para sempre. Se o cliente se for embora sem introduzir o PIN, a cobrança deve expirar de forma limpa em vez de ficar como uma responsabilidade em aberto que pode misteriosamente concluir-se uma hora depois. Uma janela de expiração limitada e previsível é o que mantém a visão do comerciante coerente com a do cliente.

Os casos-limite que separam sistemas reais de demonstrações

O caminho feliz (enviar, confirmar, concluir) é o quarto fácil do trabalho. As falhas interessantes vivem nas lacunas:

• O cliente confirma, mas a rede perde a confirmação de receção. A cobrança está completed na plataforma; o comerciante nunca soube. A repetição do webhook existe exatamente para isto. O handler do comerciante também deve ser idempotente, para que um evento "concluída" reenviado não faça entregar a mercadoria duas vezes.
• Duas confirmações chegam em concorrência. Uma confirmação repetida não pode lançar duas vezes. A chave de idempotência e a máquina de estados garantem juntas que a segunda confirmação vê "já concluída" em vez de mover dinheiro outra vez.
• A cobrança expira no mesmo instante em que o cliente confirma. A máquina de estados deve definir um único vencedor: a transição é atómica, por isso a cobrança fica autorizada ou expirada, nunca as duas, e o cliente é informado claramente.
• Reconciliação. No fim do dia, cada cobrança completed deve corresponder a um conjunto equilibrado de lançamentos no razão e a um registo de liquidação. Como o ciclo de vida da cobrança e o razão estão ligados, a conclusão é o lançamento, a reconciliação faz-se por construção e não por investigação.

Uma cronologia prática

Eis o que acontece, segundo a segundo, quando um comerciante cobra 1.250 a um cliente por compras de mercearia. Os tempos são típicos e não garantidos.

A leitura e a digitação do cliente dominam o tempo. Tudo o que a plataforma faz demora bem menos de um segundo, e é por isso que a experiência parece instantânea quando funciona, e o raro passo lento se nota de imediato.

Construir corretamente o lado do comerciante

Metade de uma integração fiável de pagamento por pedido vive no sistema do comerciante. Um bom handler de webhooks:

• Verifica a assinatura antes de confiar em qualquer coisa do conteúdo.
• É idempotente: uma segunda entrega do mesmo evento não muda nada.
• Responde depressa e faz o trabalho pesado depois, para que a plataforma não esgote o tempo e repita sem necessidade.
• Faz a correspondência pela referência da cobrança, nunca apenas pelo montante e número de telefone.
• Recorre ao endpoint de estado se nenhum evento chegar dentro da janela esperada, em vez de assumir falha.
• Regista cada evento que recebe, para que as disputas possam ser respondidas a partir dos registos.

Escolher a janela de expiração

A expiração é um compromisso. Demasiado curta, e os clientes que procuram o telefone veem a cobrança morrer antes de confirmar. Demasiado longa, e os comerciantes esperam com a mercadoria no balcão, enquanto chegam pedidos obsoletos depois de o cliente ter saído. A maioria dos operadores fica-se por um a dois minutos para pagamentos presenciais, mais para pedidos à distância, como uma fatura enviada a um cliente em casa. Seja qual for a janela, mostre-a: um operador de caixa que sabe que o pedido dura um minuto sabe quando tentar de novo.

Pormenores que os clientes notam

Pequenas escolhas no ecrã do pedido decidem se os clientes confiam nele:

• Mostrar o nome registado do comerciante, não um código interno, para que os clientes saibam quem está a pedir.
• Mostrar o montante e a referência com clareza antes do campo do PIN.
• Oferecer uma opção clara de recusa, para que um cliente que não esperava o pedido o possa recusar em vez de o ignorar.
• Confirmar por palavras e por mensagem: um recibo com o comerciante, o montante e a referência, no ecrã e por SMS.
• Alertar para pedidos inesperados. Os burlões enviam pedidos na esperança de que o cliente aprove por reflexo; uma linha curta como "Aprove apenas se estiver a pagar a este comerciante" reduz esse risco.

Um ciclo de vida, todos os canais

A peça final para fazer isto bem é que o pagamento por pedido não deve ser um caso especial ligado separadamente na aplicação, na caixa e na API. Deve ser um único ciclo de vida de cobrança que todos os canais comandam: um cliente que lê o QR de um comerciante, um comerciante que envia uma cobrança a partir de um terminal de ponto de venda e um parceiro que chama a API de programador criam todos o mesmo tipo de cobrança, que passa pelos mesmos estados, lança no mesmo razão e emite os mesmos webhooks assinados. Construa-o uma vez, corretamente, e cada canal herda as garantias.

Pagamento por pedido, QR ou número de caixa?

O pagamento por pedido é uma de três formas comuns de cobrar a um cliente. Cada uma serve uma situação diferente:

Os comerciantes saem-se melhor quando podem aceitar os três, e a plataforma trata-os como o mesmo tipo de pagamento a chegar por caminhos diferentes.

Fraude em torno dos pedidos

Como um pedido pede ao cliente que aprove um pagamento, atrai engenharia social. O padrão comum é um burlão que dispara pedidos e depois liga ao cliente, fazendo-se passar pelo fornecedor, e convence-o a aprovar. As defesas atuam a vários níveis: mostrar em destaque o nome verificado do comerciante que pede; limitar quantos pedidos um comerciante pode enviar ao mesmo número em pouco tempo; vigiar comerciantes cujos pedidos são maioritariamente recusados ou denunciados; e dizer aos clientes, repetidamente, que o fornecedor nunca lhes pedirá para aprovar um pagamento por telefone. A integração de comerciantes também importa, porque um comerciante verificado com identidade rastreável é uma má ferramenta para fraude.

Medir o pagamento por pedido

Para lá do balcão: pedidos à distância

O mesmo mecanismo funciona quando o cliente não está na caixa. Uma escola pode enviar pedidos de propinas aos pais, uma empresa de serviços pode pedir o pagamento de uma fatura, um estafeta pode pedir o pagamento à chegada. Os pedidos à distância precisam de alguns ajustes: uma expiração mais longa, uma descrição clara do que está a ser pago, o nome verificado de quem pede e uma referência que o cliente reconheça numa fatura ou mensagem. A máquina de estados, a assinatura e a idempotência mantêm-se exatamente iguais, e é por isso que um único ciclo de vida de cobrança serve a caixa, a fatura e a API.

Testar uma integração de pagamento por pedido

Antes de um comerciante entrar em produção, execute estes casos no ambiente de testes:

• aprovar, recusar e deixar expirar um pedido, e verificar que o sistema do comerciante mostra o resultado certo em cada caso;
• enviar duas vezes o mesmo pedido de criação com a mesma chave de idempotência e confirmar que só existe uma cobrança;
• fazer falhar o endpoint de webhooks do comerciante durante alguns minutos e confirmar que os eventos chegam quando ele recupera;
• enviar um webhook com uma assinatura errada e confirmar que o comerciante o rejeita;
• tentar uma cobrança acima do limite do cliente e confirmar que é recusada de forma limpa;
• verificar que os reembolsos remetem para a cobrança original.

Uma integração que passe estes testes comportar-se-á bem no seu dia mais movimentado.

Perguntas frequentes

E se o cliente não tiver ligação de dados?

Os pedidos no SIM funcionam pela rede móvel sem dados. Para os pedidos de aplicação, os clientes sem dados podem pagar na mesma introduzindo o número de caixa do comerciante por USSD.

Um comerciante pode cobrar a um cliente sem a sua aprovação?

Não. A cobrança só é concluída quando o cliente a autoriza com o PIN. O comerciante pode pedir; só o cliente pode aprovar.

Como são tratados os reembolsos?

Um reembolso é uma nova transação do comerciante para o cliente, ligada à cobrança original. A original fica no histórico, para que ambas as partes vejam o que foi pago e o que foi devolvido.

O que deve fazer um operador de caixa se o cliente disser que aprovou mas a caixa não mostrar nada?

Esperar pelo resultado em vez de cobrar duas vezes. A caixa deve consultar o estado da cobrança através da referência. Se a cobrança foi concluída, o resultado aparece em momentos; se expirou, o operador pode enviar um novo pedido em segurança. Nunca aceite uma captura de ecrã de uma confirmação como prova de pagamento.

O pagamento por pedido é seguro para montantes elevados?

Os limites do escalão do cliente aplicam-se exatamente como em qualquer outro pagamento, e o passo do PIN é o mesmo. Para pagamentos empresariais elevados, os comerciantes combinam muitas vezes um pedido com uma referência de fatura, para que ambas as partes possam associar o pagamento a um documento.

Feito assim, o pagamento por pedido parece instantâneo e torna impossível cobrar em dobro, não porque nada falhe nunca, mas porque cada falha tem um estado definido, uma repetição e um caminho de regresso à coerência. É isso que a PesaBridge entrega, nas aplicações e na API de programador, sobre um único ciclo de vida de cobrança.