Toda API de pagamentos, de qualquer país e de qualquer meio, segue o mesmo desenho conceitual. Entender esse desenho torna qualquer integração nova mais simples.
1. Intenção de pagamento
A aplicação declara que quer receber um valor. Isso cria um objeto com identificador próprio — cobrança, charge, payment intent. Esse objeto é a unidade de conciliação.
2. Instrumento de pagamento
O pagador escolhe como paga. No Pix, o instrumento é o QR Code ou o Copia e Cola aberto no aplicativo do banco. Em cartão, seriam os dados do cartão tokenizados.
3. Confirmação assíncrona
A confirmação quase nunca é a resposta da mesma requisição. Ela chega depois, por webhook. Modelar a aplicação como assíncrona desde o começo evita reescrever tudo mais tarde.
4. Idempotência
Redes falham; clientes repetem requisições. Idempotência é o mecanismo que garante que repetir não cobra duas vezes. É requisito, não otimização.
5. Conciliação
No fim, é preciso responder com precisão: quanto entrou, de quem, por qual pedido e com qual taxa. Um registro financeiro imutável, atualizado por evento, é a forma mais confiável de sustentar essa resposta.
Perguntas frequentes
- Por que a resposta da API não diz logo se foi pago?
- Porque a liquidação acontece fora da sua requisição. A API confirma que a cobrança foi criada; o pagamento chega depois, por webhook.