Blog · Integração
Integração com o Asaas: pagamentos, split e webhooks
Cobrar por Pix e cartão é a parte fácil. O que separa uma integração de pagamento amadora de uma profissional é o que acontece depois: o split que divide o dinheiro certo, o webhook que não processa a mesma cobrança duas vezes e a conciliação que fecha no fim do mês. Aqui vai o que aprendemos operando isso em produção.
Por que um gateway como o Asaas
Integrar direto com bancos e bandeiras é caro, lento e cheio de regra. Um gateway como o Asaas resolve a ponte: você chama uma API e ele cuida de Pix, cartão e boleto, do repasse e das notificações. Para a maioria dos sistemas — de um sistema de gestão a um marketplace — é o caminho mais rápido para começar a receber com segurança.
Cobrança: Pix, cartão e boleto
Na prática, o fluxo é: seu sistema cria uma cobrança via API (valor, cliente, vencimento, forma de pagamento) e recebe de volta o Pix copia-e-cola, o link de cartão ou o boleto. O pulo do gato é não ficar perguntando o tempo todo "já pagou?" — quem avisa é o webhook, que vem a seguir. Enquanto isso, sua cobrança guarda um status (pendente, confirmado, estornado) que espelha o que o gateway diz.
Split de pagamento: dividir o dinheiro automaticamente
É aqui que mora o valor de um marketplace ou de qualquer plataforma com mais de um beneficiário. O split divide cada cobrança entre destinatários — por exemplo, a comissão da plataforma e o valor do prestador — no momento em que o pagamento confirma. Você configura as regras (percentual ou valor fixo, por carteira) e o Asaas faz o repasse para cada um.
O cuidado de engenharia está em tratar o split como parte da transação, não como um cálculo à parte depois: se as regras mudam, se um beneficiário está inativo, se o valor não fecha por centavos de arredondamento — tudo isso precisa ser previsto. É o tipo de detalhe que só aparece quando você opera de verdade. Foi assim que construímos os pagamentos do CoraLink.
Webhooks confiáveis: o que ninguém te conta
O webhook é a notificação que o gateway envia quando algo acontece (pagamento confirmado, estornado, vencido). Parece simples receber, mas há três armadilhas clássicas:
- Duplicidade — o mesmo evento pode chegar mais de uma vez. Sem idempotência (registrar o id do evento e ignorar o repetido), você processa o pagamento duas vezes. É o bug mais caro dessa área.
- Fora de ordem — às vezes a confirmação chega antes do "criado". Seu código não pode assumir sequência; tem que reagir ao estado atual.
- Falha temporária — se o seu endpoint cai, o gateway reenvia. O certo é responder rápido, registrar o evento numa fila e processar de forma assíncrona, com retentativa — em vez de fazer tudo na hora e arriscar perder o evento.
Esses são os mesmos princípios de qualquer integração séria — idempotência, fila e reprocesso — que valem muito além do Asaas. Falamos deles em como integrar sistemas e é o coração da nossa página de integração.
Conciliação: fechar o mês sem susto
No fim, alguém precisa conferir se o que entrou no sistema bate com o que o gateway registra e com o que caiu na conta. Guardar cada evento, cada split e cada estorno com rastreabilidade transforma a conciliação de uma dor de cabeça manual em um relatório. Quem não pensa nisso no começo paga caro depois.
Em resumo
Integrar o Asaas para receber é rápido. Integrar para operar — com split correto, webhooks idempotentes e conciliação — é engenharia, e é onde a maioria erra. Fazemos os dois: da primeira cobrança ao repasse que fecha certo. Se você precisa de pagamentos ou split no seu sistema, é o tipo de integração que fazemos em produção.
Precisa de pagamentos ou split no seu sistema?
Conte o que o seu produto precisa cobrar e repassar. Devolvemos o caminho mais seguro para fazer certo.