Pagar.me: pagamentos e split

Pagar.me é um gateway de pagamento brasileiro (do grupo Stone). A plataforma usa o gateway para cobrar cartão de crédito, boleto e PIX no checkout. Em lojas com vários sellers (marketplace) ele também faz o split: a cobrança é dividida na origem entre os recebedores (recipients) dos sellers e o da loja (a comissão), e cada um recebe o seu valor direto do gateway.

Estas são as rotas do administrador da loja para configurar o gateway e acompanhar o dinheiro. O checkout em si é feito pelas rotas da vitrine; aqui você enxerga e age depois que a cobrança existe.

Como funciona

O ciclo de uma cobrança

O gateway avisa a plataforma de cada mudança por webhook. A plataforma traduz o status da cobrança em um status do pedido pela tabela De-para de status. Cada webhook recebido fica guardado e pode ser conferido e reprocessado em Webhooks.

Fluxo típico de implantação

1. Informe as chaves
   PUT /config com as chaves da conta Pagar.me. Use as de teste (sk_test_) com sandbox: true até validar.
2. Teste a conexão
   POST /test-connection confirma que a chave autentica.
3. Ajuste o de-para de status
   GET /status-map e, se preciso, PUT /status-map para que "pago" caia no status certo do seu fluxo de pedidos.
4. Cadastre os recebedores
   Em marketplace, POST /recipients/vendor liga cada seller a um recebedor com conta bancária.
5. Acompanhe
   GET /transactions, GET /charges e GET /webhooks mostram o que entrou e o que falhou.

Conceitos importantes

Transação e cobrança

A transação (transactions) é o registro do checkout atual: um pedido no gateway, com o método, o valor e a resposta completa do gateway. A cobrança (charges) é o registro do caminho antigo, uma cobrança avulsa por pedido. Uma loja pode ter registros nos dois. O estorno aceita ambos; a captura (para cartão autorizado e ainda não capturado) só existe para cobranças.

Recebedor e split

O recebedor é a conta de quem recebe: nome, documento (CPF ou CNPJ) e conta bancária. Cada seller que vende com split precisa de um. O recebedor da loja (marketplace_recipient_id na configuração) fica com a comissão. Na cobrança, o valor é repartido em linhas (splits) do tipo flat (valor fixo em centavos) ou percentage (pontos-base: 1000 = 10%).

Chaves e ambiente

Há uma chave secreta (api_key, começa com sk_), uma chave pública (public_key, pk_) usada no navegador para tokenizar cartões, e uma chave secreta de webhook (secret_key) usada para conferir a assinatura dos avisos. sandbox: true aponta para o ambiente de testes do gateway.

Endpoints

Erros comuns

1. Esperar 404 em "não encontrado". Transação ou cobrança inexistente volta como 500. Confira o id antes de investigar o gateway.
2. Usar o id errado. A captura e a lista de splits recebem o id interno (UUID) da cobrança. O estorno aceita o id interno ou o id do gateway (ch_...).
3. Estornar mais que o saldo. O valor do estorno não pode passar do que ainda resta para estornar. Estorno parcial deixa a cobrança como paga.
4. Mapear "pago" para um status que não existe na loja. O de-para é gravado mesmo assim, mas na hora de pagar o pedido cai num status padrão antigo (processing). Confira exists_in_registry no GET /status-map.
5. Reprocessar um webhook sem pensar no efeito. O reprocessamento roda de novo a regra que muda o status do pedido.
6. Guardar a resposta do PUT /config. Ela traz as chaves secretas em claro. Não registre nem repasse esse corpo.
7. Esquecer o vendor_id na conciliação. A rota exige o seller; sem ele responde 400.

Próximos passos