Autenticação
As chaves de API viajam no cabeçalho Authorization, no formato Bearer. Existem chaves de sandbox e de produção; a chave é mostrada uma única vez, no momento em que a cria, e fica guardada em hash do lado do servidor. Nunca coloque a chave em código de navegador nem em repositórios públicos.
Criar uma cobrança
Envie o método, o valor em MZN, o nome e o contacto do cliente. A resposta inclui a referência, o valor bruto, a comissão e o valor líquido, além do estado inicial. Para pagamentos móveis o estado começa pendente até o cliente confirmar no telemóvel.
Idempotência: a parte que quase todos esquecem
Redes falham e utilizadores carregam duas vezes. Envie sempre uma chave de idempotência única por encomenda; se o mesmo pedido chegar outra vez, a plataforma devolve a transacção original em vez de cobrar de novo. Sem isto, mais cedo ou mais tarde vai cobrar duas vezes ao mesmo cliente.
Estados e transições
Trate os estados de forma explícita no seu código.
- pendente — pedido enviado, à espera do cliente.
- em revisão — retido por regra de risco, decide-se depois.
- aprovada — dinheiro no saldo; é aqui que liberta o produto.
- falhada ou bloqueada — não entregue nada.
- reembolsada — devolução total ou parcial de uma aprovada.
Testar antes de ir para produção
Use a chave de sandbox para percorrer os casos felizes e os infelizes: pagamento aprovado, recusado, cliente que não confirma, valor acima do limite, pedido repetido com a mesma chave de idempotência. Só depois troque para a chave de produção — e confirme que a chave de sandbox deixou de estar no seu código.
Limites e boa cidadania
Respeite os limites de velocidade da API, faça repetições com espera crescente e não consulte a lista de transacções em ciclo apertado para saber se um pagamento entrou: é para isso que existem os webhooks.