Acompanhar as cobranças do mês
Nesta página
Liste as cobranças em abertoPercorra as páginas do mêsConfira os pagamentos de uma cobrançaSituação da cobrançaErrosSaiba quais cobranças das linhas dos seus clientes estão em aberto, quais já foram pagas e como cada uma foi paga.
Liste as cobranças em aberto
Filtre por status=PENDING. Para ver só uma linha ou um titular, acrescente lineId ou customerId.
curl "https://api.payzucell.com.br/v1/charges?status=PENDING&limit=100" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"{
"data": [
{
"id": "cm4a6r2e80007q8f2v3b5n9kd",
"environment": "LIVE",
"customerId": "cm3x1z4d20002q8f2t6y9w3qe",
"customerName": "Ana Lima",
"lineId": "cm3x2b7k90004q8f2m1n6p8rs",
"lineMsisdn": "5511987654321",
"kind": "RENEWAL",
"status": "PENDING",
"amount": 29.9,
"dueOn": "2026-11-25",
"expiresAt": "2026-12-02T00:00:00.000Z",
"paidAt": null,
"createdAt": "2026-11-18T09:00:41.000Z"
}
],
"nextCursor": null
}amount: o valor da cobrança, em reais.dueOn: o dia de vencimento.expiresAt: o prazo para pagar.
Referência: Listar as cobranças
Percorra as páginas do mês
A lista não tem filtro de data. Para ler as cobranças criadas em um mês:
- Ordem: a lista vem da cobrança mais nova para a mais antiga, pela data de criação,
createdAt. - Situações: liste sem
status, para vir todas. - Páginas: siga o
nextCursorde cada página, sempre com os mesmos filtros da primeira chamada. - Fim do mês: ignore as cobranças criadas depois dele.
- Começo do mês: pare na primeira cobrança com
createdAtanterior a ele, ou quandonextCursorviernull. - Fuso: o
createdAtvem em UTC. O mês no horário de Brasília começa às03:00Zdo dia 1.
curl "https://api.payzucell.com.br/v1/charges?limit=100&cursor=WyIyMDI2LTExLTAzVDA5OjAwOjQxLjAwMFoiLCJjbTQ5dDJ3NmswMDAzcThmMmI4aDFyNXhlIl0" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"A cobrança que vence num mês pode ter sido criada no mês anterior.
A cobrança de renovação é criada antes do vencimento. Para separar pelo vencimento, dueOn, não pare pelo createdAt: siga as páginas até o nextCursor vir null.
O cursor e o limite por página estão em Paginação.
Confira os pagamentos de uma cobrança
curl https://api.payzucell.com.br/v1/charges/cm4a6r2e80007q8f2v3b5n9kd \
-H "Authorization: Bearer SUA_CHAVE_DE_API"{
"id": "cm4a6r2e80007q8f2v3b5n9kd",
"environment": "LIVE",
"customerId": "cm3x1z4d20002q8f2t6y9w3qe",
"customerName": "Ana Lima",
"lineId": "cm3x2b7k90004q8f2m1n6p8rs",
"lineMsisdn": "5511987654321",
"kind": "RENEWAL",
"status": "PAID",
"amount": 29.9,
"dueOn": "2026-11-25",
"expiresAt": "2026-12-02T00:00:00.000Z",
"paidAt": "2026-11-18T18:12:30.000Z",
"createdAt": "2026-11-18T09:00:41.000Z",
"payments": [
{
"id": "cm4a6s1f30008q8f2p7c2m4hu",
"orderId": "cm4a6r9g50009q8f2k8d1z6wy",
"chargeIds": ["cm4a6r2e80007q8f2v3b5n9kd"],
"method": "PIX",
"status": "PAID",
"amount": 29.9,
"pixCopyPaste": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426655440000520400005303986540529.905802BR5905PAYZU6009SAO PAULO62070503***63040E51",
"pixQrCode": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAAA...",
"expiresAt": "2026-11-19T09:00:42.000Z",
"paidAt": "2026-11-18T18:12:30.000Z",
"createdAt": "2026-11-18T09:00:42.000Z"
}
]
}payments: os pagamentos da cobrança, do mais novo para o mais antigo.methodestatus: o meio e a situação de cada pagamento.chargeIds: os IDs das cobranças que o pagamento cobre. Um pagamento pode quitar mais de uma cobrança do mesmo titular.
Referência: Consultar uma cobrança
Situação da cobrança
Para saber se uma cobrança em aberto mudou, consulte-a pelo id.
| Situação | Significado |
|---|---|
PENDING | Aguardando pagamento. |
PAID | Paga. |
EXPIRED | Não foi paga a tempo. A troca de PENDING para EXPIRED acontece depois de expiresAt, não no mesmo instante. |
CANCELLED | Cancelada. |
A cobrança PENDING, antes de expiresAt, também pode ser paga na hora com o saldo da carteira. Veja Pagar com o saldo da carteira.
Erros
- Parâmetro fora do formato:
statusfora da lista,limitfora de 1 a 100,cursorinválido, oulineIdoucustomerIdvazio.detailsdiz qual parâmetro corrigir. - Recurso não encontrado: a cobrança não existe, é de outro integrador ou é do outro ambiente.
- Filtro sem resultado:
lineIdoucustomerIdque não é seu traz a lista vazia, sem erro.
O limite de chamadas está em Limites de requisição e os erros da chave, em Autenticação.