Cobranças

O que são cobranças?

Cobranças são solicitações de pagamento criadas para um cliente, que podem ser pagas usando diversos métodos, como Pix, boleto, cartão de crédito, etc. Com pagamentos.dev, você pode criar, consultar, atualizar e cancelar cobranças de forma simples e eficiente, utilizando uma interface unificada para diversos provedores de pagamento.

A disponibilidade das operações pode variar de acordo com o provedor conectado.Consulte a documentação do provedor para detalhes específicos sobre as funcionalidades suportadas.

Cobranças vs Pagamentos

É importante entender a diferença entre cobranças e pagamentos:

Cobranças: São as solicitações de pagamento criadas para um cliente. Elas representam o valor que deve ser pago, o método de pagamento, o cliente associado, etc. As cobranças podem ter diferentes status, como pendente, pago, cancelado, etc.
Pagamentos: São as transações financeiras realizadas para quitar as cobranças. Um pagamento pode ser bem-sucedido, falhar, ser estornado, etc. Os pagamentos estão diretamente relacionados às cobranças, mas representam a ação de pagar, enquanto as cobranças representam a solicitação de pagamento.

Status das cobranças

Para facilitar o gerenciamento, os status das cobranças são padronizados em:

pendente: A cobrança foi criada, mas ainda não foi paga.
pago: A cobrança foi paga com sucesso.
cancelado: A cobrança foi cancelada e não pode mais ser paga.
vencido: A cobrança não foi paga dentro do prazo e está vencida.
falha: Ocorreu um erro durante o processamento do pagamento.

Criando uma cobrança

Pix

import { pg } from './pagamentos'

await pg.cobrancas.create({
  idempotencyKey: crypto.randomUUID(),
  valor: 1000, // valor em centavos
  metodoPagamento: 'pix', // ou 'boleto', 'cartaoCredito', etc.
  cliente: {
    nome: 'João Silva',
    documento: '123.456.789-00'
  }
})

Cartão de crédito

import { pg } from './pagamentos'

await pg.cobrancas.create({
  idempotencyKey: crypto.randomUUID(),
  valor: 5000, // valor em centavos
  metodoPagamento: 'cartaoCredito',
  cliente: {
    nome: 'Maria Souza',
    documento: '987.654.321-00'
  },
  cartaoCredito: {
    token: 'token-do-cartao' // token gerado pelo provedor
  }
})

Consultando uma cobrança

import { pg } from './pagamentos'

const pagamento = await pg.cobrancas.get('id-da-cobranca')

console.log(pagamento.status) // 'pendente', 'pago', 'cancelado', etc.

Listando cobranças

import { pg } from './pagamentos'

const pagamentos = await pg.cobrancas.list({
  clienteDocumento: '123.456.789-00', // filtra por cliente
  status: 'pendente' // filtra por status
})

console.log(pagamentos)

Filtros disponíveis podem variar dependendo do provedor conectado. Consulte a documentação do provedor para detalhes específicos.

Cancelando uma cobrança

import { pg } from './pagamentos'

await pg.cobrancas.cancel('id-da-cobranca', { idempotencyKey: crypto.randomUUID() })

Atualizando uma cobrança

import { pg } from './pagamentos'

await pg.cobrancas.update('id-da-cobranca', {
  idempotencyKey: crypto.randomUUID(),
  valor: 1500, // novo valor em centavos
  cliente: {
    nome: 'João Silva',
    documento: '123.456.789-00'
  }
})

Fundamentos

Métodos de Pagamento

Funcionalidades

O que são cobranças?

Cobranças vs Pagamentos

Status das cobranças

Criando uma cobrança

Pix

Cartão de crédito

Consultando uma cobrança

Listando cobranças

Cancelando uma cobrança

Atualizando uma cobrança

​O que são cobranças?

​Cobranças vs Pagamentos

​Status das cobranças

​Criando uma cobrança

​Pix

​Cartão de crédito

​Consultando uma cobrança

​Listando cobranças

​Cancelando uma cobrança

​Atualizando uma cobrança

O que são cobranças?

Cobranças vs Pagamentos

Status das cobranças

Criando uma cobrança

Pix

Cartão de crédito

Consultando uma cobrança

Listando cobranças

Cancelando uma cobrança

Atualizando uma cobrança