Devoluções

Solicitação, consulta e listagem de devoluções de Pix recebidos em cobranças

Uma devolução estorna ao pagador, total ou parcialmente, o valor de um Pix recebido em uma cobrança. É possível solicitar várias devoluções para a mesma cobrança, desde que a soma não ultrapasse o valor pago.

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

Solicitar devolução

POST /api/v1/pix-refunds

Headers

Header	Obrigatório	Exemplo
`Content-Type`	sim	`application/json`
`x-transaction-id`	não	`328d5e1a-06dd-4263-8081-0a2ec31c1f9a`

Body

{
  "txid": "astra260915120000123cob4A2F9012",
  "amount": 150.00,
  "description": "Devolução solicitada pelo cliente",
  "userReference": "DEV-12345",
  "sendWebhook": true
}

Campo	Tipo	Obrigatório	Descrição
`txid`	string	sim	Identificador da cobrança paga que será devolvida
`amount`	number	sim	Valor a devolver. Mínimo `0.01`. A soma de todas as devoluções não pode ultrapassar o valor do Pix recebido
`description`	string	não	Mensagem ao pagador sobre a devolução
`userReference`	string	não	Referência do integrador, devolvida na consulta
`sendWebhook`	boolean	não	Reservado — hoje só é gravado, não afeta o disparo do webhook. Use `pix_refund.returned` no cadastro do webhook para ser notificado

`201 Created`

{
  "pixRefundId": "astra260915143000456dev01A0012yoP",
  "pixChargeId": 42,
  "tenantId": "01a09ad2-151a-784c-a069-d1c04cec9489",
  "partnerBankId": 1,
  "amount": 150.00,
  "status": { "code": 2, "description": "PROCESSING" },
  "statusReason": null,
  "pixChargeTxid": "astra260915120000123cob4A2F9012",
  "refundEndToEnd": "Eastra260915143000456dev01A0012yoP",
  "sendWebhookInt": 1,
  "pixEndToEnd": "E12345678202609151432abcdef123456",
  "creationDate": "2026-09-15T14:30:00",
  "updatedAt": "2026-09-15T14:30:00",
  "refundTypeCode": 1,
  "numberRetries": 0,
  "settlementDate": null,
  "description": "Devolução solicitada pelo cliente"
}

Guarde pixRefundId para consultar a devolução. Em sandbox a devolução é liquidada de forma síncrona/imediata na maioria dos casos; o resultado final também chega pelo webhook (pix_refund.returned) e pode ser confirmado em Consultar devolução.

Erros:

Status	Significado
`401`	Certificado de cliente ausente ou inválido
`404`	Cobrança não encontrada para o cliente autenticado
`409`	Cobrança já totalmente devolvida, ou ainda não liquidada (paga)
`422`	Valor solicitado excede o valor (restante) da cobrança

Consultar devolução

GET /api/v1/pix-refunds/{pixRefundId}

Parâmetro	Tipo	Exemplo
`pixRefundId`	string	`astra260915143000456dev01A0012yoP`

`200 OK`

{
  "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"
}

Campos da 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`	integer	Código do status — ver Status da devolução
`status.description`	string	Nome do status
`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 de cliente ausente ou inválido · 404 devolução não encontrada para o cliente autenticado.

Listar devoluções

GET /api/v1/pix-refunds

Lista devoluções do cliente autenticado, com filtros opcionais e paginação. Diferente da listagem de cobranças, aqui nenhum filtro é obrigatório.

Query params

Parâmetro	Obrigatório	Exemplo	Descrição
`initialDate`	não	`2026-09-01T00:00:00`	Início do período (data de criação)
`endDate`	não	`2026-09-30T23:59:59`	Fim do período (data de criação)
`pixChargeTxid`	não	`astra260915120000123cob4A2F9012`	Filtra pelas devoluções de uma cobrança
`status`	não	`3`	Código do status — ver Status da devolução
`page`	não	`0`	Página (começa em `0`)
`size`	não	`20`	Itens por página
`sort`	não	`creationDate,desc`	Ordenação no formato `campo,asc` ou `campo,desc`

`200 OK`

{
  "content": [
    {
      "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"
    }
  ],
  "number": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "numberOfElements": 1,
  "first": true,
  "last": true,
  "empty": false
}

Cada item de content é uma devolução com os campos descritos em Campos da devolução, acima.

Erros: 401 certificado de cliente ausente ou inválido.

Devoluções

On this page