Consultar, Listar e Cancelar

Consultar cobrança

GET /api/v1/pix-charges/{txid}

Retorna a cobrança com seu status atual, os dados do Pix recebido (quando paga) e as devoluções associadas. É o mesmo formato devolvido na criação.

Requer autenticação mTLS. Veja Autenticação.

Parâmetro	Tipo	Exemplo
`txid`	string	`astra260915120000123cob4A2F9012`

`200 OK`

{
  "txid": "astra260915120000123cob4A2F9012",
  "calendar": {
    "creationDate": "2026-09-15T14:30:00",
    "expiration": 3600,
    "expirationDate": "2026-09-15T15:30:00"
  },
  "debtor": {
    "naturalPersonIdentification": "77685349051",
    "name": "Fulano Gomes da Silva"
  },
  "amount": 400.00,
  "status": "PARTIALLY REFUNDED",
  "pixCopyAndPaste": "astra260915120000123cob4A2F9012|400.00|Pedido 12345",
  "qrCodeBase64": null,
  "description": "Pedido 12345",
  "userReference": "PED-12345",
  "pix": {
    "endToEndId": "E12345678202609151432abcdef123456",
    "amount": "400.00",
    "creationDate": "2026-09-15T14:32:10",
    "payerName": "Fulano Gomes da Silva",
    "payerDocumentNumber": "77685349051"
  },
  "devolutionAllowed": true,
  "devolutions": [
    {
      "pixRefundId": "astra260915143000456dev01A0012yoP",
      "pixChargeId": 42,
      "tenantId": "01a09ad2-151a-784c-a069-d1c04cec9489",
      "partnerBankId": 1,
      "amount": 150.00,
      "status": { "code": 3, "description": "RETURNED" },
      "statusReason": null,
      "pixChargeTxid": "astra260915120000123cob4A2F9012",
      "refundEndToEnd": "Eastra260915143000456dev01A0012yoP",
      "sendWebhookInt": 1,
      "pixEndToEnd": "E12345678202609151432abcdef123456",
      "creationDate": "2026-09-15T14:30:00",
      "updatedAt": "2026-09-15T14:30:34",
      "refundTypeCode": 1,
      "numberRetries": 2,
      "settlementDate": "2026-09-15T14:30:34",
      "description": "Devolução solicitada pelo cliente"
    }
  ]
}

qrCodeBase64 só é preenchido enquanto a cobrança está ACTIVE — em qualquer outro status vem null, já que o código deixou de ser válido para pagamento.

Campos da resposta

Campo	Tipo	Descrição
`txid`	string	Identificador da cobrança
`calendar.creationDate`	string (date-time)	Momento de criação da cobrança
`calendar.expiration`	integer	Tempo de vida da cobrança em segundos
`calendar.expirationDate`	string (date-time)	Momento em que a cobrança expira
`debtor`	object \| null	Devedor informado na criação — ver abaixo
`amount`	number	Valor da cobrança
`status`	string	Ver Status da cobrança
`pixCopyAndPaste`	string	Código Pix Copia e Cola
`qrCodeBase64`	string \| null	Imagem PNG do QR Code em Base64. Só presente com `status: ACTIVE`
`description`	string	Descrição informada na criação
`userReference`	string	Referência informada na criação
`pix`	object \| null	Pix recebido. `null` até a cobrança ser paga — ver abaixo
`devolutionAllowed`	boolean	`true` quando `status` é `PAID` ou `PARTIALLY REFUNDED` e a cobrança tem menos de 90 dias
`devolutions`	array \| null	Devoluções da cobrança. `null` até haver alguma — ver abaixo

Campos de `debtor`

Campo	Tipo	Descrição
`naturalPersonIdentification`	string	CPF do devedor
`legalPersonIdentification`	string	CNPJ do devedor
`name`	string	Nome do devedor

Campos de `pix`

Campo	Tipo	Descrição
`endToEndId`	string	Identificador fim a fim (E2E) do Pix recebido
`amount`	string	Valor pago
`creationDate`	string (date-time)	Momento em que o Pix foi processado
`payerName`	string	Nome de quem pagou
`payerDocumentNumber`	string	CPF/CNPJ de quem pagou

Campos de `devolutions[]`

Cada item é o objeto completo da devolução — os mesmos campos devolvidos em Solicitar devolução e Consultar devolução.

Campo	Tipo	Descrição
`pixRefundId`	string	Identificador da devolução
`pixChargeId`	integer	Identificador interno da cobrança devolvida
`tenantId`	string (uuid)	Cliente dono da cobrança/devolução
`partnerBankId`	integer	Identificador do banco parceiro
`amount`	number	Valor devolvido
`status.code` / `status.description`	integer / string	Ver Status da devolução
`statusReason`	string \| null	Motivo quando a devolução não é concluída com sucesso
`pixChargeTxid`	string	`txid` da cobrança devolvida
`refundEndToEnd`	string	Identificador fim a fim (E2E) da devolução
`sendWebhookInt`	integer	`1` ou `0` — eco do `sendWebhook` enviado na solicitação
`pixEndToEnd`	string	Identificador fim a fim (E2E) do Pix original devolvido
`creationDate`	string (date-time)	Momento da solicitação
`updatedAt`	string (date-time)	Última atualização do registro
`refundTypeCode`	integer	Tipo de devolução (uso interno)
`numberRetries`	integer	Tentativas de envio ao parceiro (uso interno)
`settlementDate`	string (date-time) \| null	Momento da liquidação. `null` enquanto não liquidada
`description`	string	Mensagem enviada ao pagador

Erros: 401 certificado ausente ou inválido · 404 cobrança não encontrada para o cliente autenticado.

Cancelar cobrança

PUT /api/v1/pix-charges/{txid}/cancel

Cancela uma cobrança do cliente autenticado. Só é permitido enquanto a cobrança está CREATED ou ACTIVE — uma cobrança já paga não pode mais ser cancelada (use devolução nesse caso).

Parâmetro	Tipo	Exemplo
`txid`	string	`astra260915120000123cob4A2F9012`

`200 OK`

Devolve a cobrança no mesmo formato de Consultar cobrança, com status: "Cancelada" e qrCodeBase64: null.

Erros:

Status	Significado
`401`	Certificado de cliente ausente ou inválido
`404`	Cobrança não encontrada para o cliente autenticado
`409`	Cobrança não pode ser cancelada no estado atual (já paga, expirada ou já cancelada)

Listar cobranças

GET /api/v1/pix-charges

Lista as cobranças criadas em um período, com filtros opcionais e paginação.

Query params

Parâmetro	Obrigatório	Exemplo	Descrição
`initialDate`	sim	`2026-09-01T00:00:00`	Início do período (data de criação)
`endDate`	sim	`2026-09-30T23:59:59`	Fim do período (data de criação)
`status`	não	`PAID`	Ver Status da cobrança
`naturalPersonIdentification`	não	`77685349051`	CPF do devedor
`legalPersonIdentification`	não	`00000000000191`	CNPJ do devedor
`userReference`	não	`PED-12345`	Referência do integrador
`page`	não	`0`	Página (começa em `0`)
`size`	não	`20`	Itens por página
`sort`	não	`createdAt,desc`	Ordenação no formato `campo,asc` ou `campo,desc`

Exemplo

curl "https://api.sandbox.eagleix.com.br/api/v1/pix-charges?initialDate=2026-09-01T00:00:00&endDate=2026-09-30T23:59:59&status=PAID&page=0&size=20" \
  --cert cliente.crt \
  --key cliente.key \
  -H "x-transaction-id: 328d5e1a-06dd-4263-8081-0a2ec31c1f9a"

`200 OK`

{
  "content": [
    {
      "txid": "astra260915120000123cob4A2F9012",
      "calendar": {
        "creationDate": "2026-09-15T14:30:00",
        "expiration": 3600,
        "expirationDate": "2026-09-15T15:30:00"
      },
      "debtor": {
        "naturalPersonIdentification": "77685349051",
        "name": "Fulano Gomes da Silva"
      },
      "amount": 400.00,
      "status": "PAID",
      "description": "Pedido 12345",
      "userReference": "PED-12345"
    }
  ],
  "number": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "numberOfElements": 1,
  "first": true,
  "last": true,
  "empty": false
}

Campos de `content[]`

Campo	Tipo	Descrição
`txid`	string	Identificador da cobrança
`calendar.creationDate`	string (date-time)	Momento de criação da cobrança
`calendar.expiration`	integer	Tempo de vida da cobrança em segundos
`calendar.expirationDate`	string (date-time)	Momento em que a cobrança expira
`debtor`	object \| null	Devedor informado na criação. `null` quando nenhum foi informado
`amount`	number	Valor da cobrança
`status`	string	Ver Status da cobrança
`description`	string	Descrição informada na criação
`userReference`	string	Referência informada na criação

Os itens da listagem não trazem pixCopyAndPaste, qrCodeBase64, devolutionAllowed, o Pix recebido nem as devoluções. Para esses dados, use Consultar cobrança.

Erros: 400 parâmetros inválidos (ex.: initialDate/endDate ausentes) · 401 certificado de cliente ausente ou inválido.

Consultar, Listar e Cancelar

On this page