Listar cobranças

As cobranças da conta, da mais nova para a mais antiga, com filtros e paginação por cursor.

GET /v1/payments

cURL

curl "https://bukio-backend-production.up.railway.app/v1/payments?limit=20&status=paid&method=pix" \
  -H "Authorization: Bearer bk_live_..."

200

{
  "items": [
    {
      "id": "BKY-7KQ2M9XP4RZT",
      "status": "paid",
      "statusTitle": "Pix recebido",
      "amount": 15000,
      "fee": 50,
      "refundedAmount": 0,
      "description": "Pedido 1842",
      "txid": "7kq2m9xp4rzt1a2b3c4d5e6f",
      "copyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
      "expiresAt": "2026-10-08T15:30:00.000Z",
      "paidAt": "2026-10-08T15:04:11.000Z",
      "customer": null,
      "payer": { "name": "Ana Souza", "document": "***.456.789-**", "institution": "Banco Exemplo" },
      "createdAt": "2026-10-08T15:00:00.000Z"
    }
  ],
  "nextCursor": "WyIyMDI2LTEwLTA4VDE1OjAwOjAwLjAwMFoiLCIuLi4iXQ"
}

Escopo payments:list. Os filtros são aplicados no servidor e valem para a lista inteira, com o cursor (não só para a página). Para saber de um pagamento, prefira o webhook payment.paid a listar em laço.

limit · integer · default: "50"

De 1 a 100.

cursor · string

O nextCursor da página anterior. Inválido: 400 INVALID_CURSOR.

status · string

Só as cobranças nesta situação: pending (aguardando pagamento), paid (paga), expired (vencida sem pagamento) ou refunded (estornada por inteiro). A pendente que já passou do prazo entra em expired.

method · string

Só as desta forma de pagamento: pix, card ou crypto.

customerId · string

Só as deste cliente (o id de Listar clientes).

subaccountId · string

Só as desta subconta (o sacc_... ou o seu externalId), inclusive as divididas com ela.

q · string

Busca, sem diferença de maiúscula ou acento, no código BKY-, na descrição, no nome ou CPF/CNPJ mascarado de quem pagou e no nome do cliente. Até 80 caracteres.

​

Resposta

items · object[]

Cada item tem o mesmo formato de Criar cobrança: id, status, statusTitle, amount, fee, refundedAmount, description, txid, copyPaste, expiresAt, paidAt, customer, payer, createdAt.

nextCursor · string | null

Mande em ?cursor= para a próxima página. null quando acabou.

cURL

curl "https://bukio-backend-production.up.railway.app/v1/payments?limit=20&status=paid&method=pix" \
  -H "Authorization: Bearer bk_live_..."

200

{
  "items": [
    {
      "id": "BKY-7KQ2M9XP4RZT",
      "status": "paid",
      "statusTitle": "Pix recebido",
      "amount": 15000,
      "fee": 50,
      "refundedAmount": 0,
      "description": "Pedido 1842",
      "txid": "7kq2m9xp4rzt1a2b3c4d5e6f",
      "copyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
      "expiresAt": "2026-10-08T15:30:00.000Z",
      "paidAt": "2026-10-08T15:04:11.000Z",
      "customer": null,
      "payer": { "name": "Ana Souza", "document": "***.456.789-**", "institution": "Banco Exemplo" },
      "createdAt": "2026-10-08T15:00:00.000Z"
    }
  ],
  "nextCursor": "WyIyMDI2LTEwLTA4VDE1OjAwOjAwLjAwMFoiLCIuLi4iXQ"
}