Cobranças

Criar uma cobrança

POST /v1/cobrancas

Escopo cobrancas:criar. Cria no produto da chave (PIX Cobrança ou boleto).

Campo	Tipo
valor	inteiro	Obrigatório. Em centavos (8990 = R$ 89,90)
vencimento	data	AAAA-MM-DD. PIX com vencimento; boleto exige
descricao	texto	Até 140 caracteres. Aparece para o pagador
idExterno	texto	O seu identificador (até 64). Único por organização; dá para consultar por ele
pagador	objeto	nome, documento (CPF ou CNPJ), email, endereco. Boleto e PIX com vencimento exigem; boleto exige o endereço
pagador.endereco	objeto	cep, logradouro, numero, complemento, bairro, cidade, uf
condicoes	objeto	multaPercentual, jurosMensalPercentual, descontoPercentual ou descontoValor, descontoDiasAntes, mensagens
expiracaoSegundos	inteiro	PIX imediato: validade do QR Code (padrão: 24 horas)

Exemplo de PIX com vencimento e condições:

{
  "valor": 15000,
  "vencimento": "2026-10-20",
  "descricao": "Mensalidade de outubro",
  "idExterno": "mensalidade-2026-10-cliente-88",
  "pagador": { "nome": "Maria Souza", "documento": "529.982.247-25" },
  "condicoes": { "multaPercentual": "2", "jurosMensalPercentual": "1" }
}

Respostas

• 201 (PIX): o banco já emitiu; a resposta traz pix.copiaECola e pix.txid.
• 202: a cobrança está emitindo. Acontece sempre no boleto e no PIX quando o banco demora mais de alguns segundos. Consulte depois ou espere o aviso.
• 422: algum campo precisa de correção; veja errors (por campo).

Consultar

GET /v1/cobrancas/{id}

Escopo cobrancas:ler. {id} é o id da SinapsePay ou o seu idExterno.

Se a cobrança está em aberto, vencida ou expirou há menos de um dia, a consulta pergunta ao banco na hora (no máximo uma vez a cada 5 segundos por cobrança) e responde já atualizada. Assim, mesmo que um aviso do banco se perca, o pagamento aparece quando você consulta.

O objeto Cobrança

{
  "id": "4ec2604f-97c2-4715-9642-c6e59cb7bef8",
  "produto": "pix",
  "status": "paga",
  "valor": 8990,
  "descricao": "Pedido 1042",
  "idExterno": "pedido-1042",
  "pix": { "txid": "4ec2604f97c247159642c6e59cb7bef8", "tipo": "imediata", "copiaECola": "000201...", "expiracaoSegundos": 86400 },
  "pagamentos": [
    {
      "id": "c1a8...",
      "origem": "webhook",
      "valorOriginal": 8990,
      "valorPago": 8990,
      "pagoEm": "2026-10-06T13:53:41Z",
      "creditoEm": "2026-10-06",
      "pagoPorNome": "Maria Souza",
      "pagoPorDocumento": "52998224725",
      "endToEndId": "E75691000202610061353..."
    }
  ],
  "criadaEm": "2026-10-06T13:52:08Z",
  "statusAlteradoEm": "2026-10-06T13:53:41Z"
}

Boleto traz boleto (nossoNumero, seuNumero, linhaDigitavel, codigoBarras) no lugar de pix. Devoluções aparecem em devolucoes (veja devoluções).

Situações

status	Quer dizer
emitindo	Pedido enviado ao banco
em_aberto	Pronta para pagar
vencida	Passou do vencimento e ainda aceita pagamento (com multa e juros, se houver)
expirada	PIX imediato além da validade: o banco não aceita mais
paga	Pagamento recebido
devolvida	Todo o valor pago foi devolvido
cancelando → cancelada	Cancelada no banco a seu pedido
baixada	Paga por fora e baixada por você
falhou	O banco recusou a emissão; veja motivoFalha

Um pagamento que chega com valor diferente do esperado entra com divergencia (pago_a_mais, pago_a_menos, pago_em_dobro, pago_apos_baixa, pago_apos_cancelamento).

Cancelar e baixar

POST /v1/cobrancas/{id}/cancelar        { "motivo": "Cliente desistiu" }
POST /v1/cobrancas/{id}/baixar          { "valorPago": 15000, "pagoEm": "2026-10-06", "forma": "dinheiro" }

• Cancelar (cobrancas:cancelar): o banco deixa de aceitar o pagamento. Resposta 202; a cobrança vai de cancelando para cancelada. Se o pagamento chegar antes, ele vale e o cancelamento é recusado (cancelamentoRecusado).
• Baixar (cobrancas:baixar): para o que foi recebido fora do banco. forma: dinheiro, transferencia, cheque ou outro. A cobrança fica baixada e o banco deixa de aceitá-la.