> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar reembolsos
> Lista paginada dos reembolsos da conta, com filtros por etapa, transação, pagamento, forma de pagamento e período.
`GET /refunds`
Faz parte do recurso [Reembolsos](/pt-BR/refunds) — o objeto, os status e o ciclo estão lá.
Retorna uma lista paginada de todos os reembolsos da conta. Todos os filtros são opcionais e podem
ser combinados. As datas seguem **ISO 8601 com timezone** (veja [Convenções](/pt-BR/convencoes)).
**Filtro com valor inválido é rejeitado, não ignorado.** `?status=xpto` responde **400** com
`error.issues[]` apontando o campo e os valores aceitos.
O formato do erro e a lista de códigos estão em [Erros](/pt-BR/erros).
**Vários valores no mesmo filtro.** `status` e `paymentMethod` aceitam uma lista separada por
vírgula, e o resultado traz qualquer reembolso que case com **um dos** valores. Ex.:
`?status=pending,approved&paymentMethod=boleto,pix`.
**`dateField` decide sobre qual data o período incide.** Com `createdAt` (o padrão) você pergunta
"o que foi pedido neste mês"; com `refundedAt`, "quando o dinheiro efetivamente voltou". A segunda
é a que fecha com o extrato — um reembolso pedido em junho e liquidado em julho aparece em meses
diferentes conforme a escolha.
```bash theme={null}
?dateField=refundedAt&startDate=2026-07-01T00:00:00-03:00&endDate=2026-07-31T23:59:59-03:00
```
**Para ver os reembolsos de uma transação ou de um pagamento, filtre aqui.** `?transactionId=` e
`?paymentId=` fazem correspondência exata, e aceitam etapa, período e ordenação na mesma
consulta — `?transactionId=txn_123&status=refunded&dateField=refundedAt`.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/refunds \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
--data-urlencode "status=refunded" \
--data-urlencode "dateField=refundedAt" \
--data-urlencode "startDate=2026-06-01T00:00:00-03:00" \
--data-urlencode "endDate=2026-06-30T23:59:59-03:00" \
--data-urlencode "sortDir=desc" \
--data-urlencode "limit=10"
```
```json theme={null}
{
"data": [
{
"id": "rfd_j3cpkaysqmix17mxhcmv8qypl",
"transactionId": "txn_aqbcw2lky42xfidw5pcdss8h1",
"paymentId": "pay_jxt9b5qv1x0h0h8ustleqjgr8",
"amount": 14990,
"currency": "BRL",
"status": "refunded",
"reason": "Cliente solicitou cancelamento da compra",
"requestedByType": "api",
"paymentMethod": "credit_card",
"customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
"customerName": "Maria Silva",
"customerEmail": "maria.silva@example.com",
"customerDocument": "12345678909",
"customerDocumentType": "cpf",
"additionalInfo": {
"checkoutLinkId": "chk_byd8p3p79re859jpkmr0j65n3"
},
"failureReason": null,
"reviewedAt": "2026-06-29T14:10:00.000Z",
"refundedAt": "2026-06-29T14:12:45.000Z",
"createdAt": "2026-06-29T13:45:30.000Z",
"updatedAt": "2026-06-29T14:12:45.000Z"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 1,
"totalPages": 1
}
}
```
## OpenAPI
````yaml openapi/psp.json GET /refunds
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/refunds:
get:
tags:
- Refunds
summary: Listar reembolsos
description: Retorna os reembolsos da conta, com filtros e paginação.
operationId: RefundController_list
parameters:
- name: transactionId
in: query
required: false
description: Retorna os reembolsos desta transação. Correspondência exata.
schema:
type: string
nullable: true
description: Retorna os reembolsos desta transação. Correspondência exata.
- name: paymentId
in: query
required: false
description: Retorna os reembolsos deste pagamento. Correspondência exata.
schema:
type: string
nullable: true
description: Retorna os reembolsos deste pagamento. Correspondência exata.
- name: paymentMethod
in: query
required: false
description: >-
Forma de pagamento estornada: `credit_card`, `boleto` ou `pix`.
Aceita vários separados por vírgula.
schema:
type: array
items:
type: string
enum:
- credit_card
- boleto
- pix
nullable: true
description: >-
Forma de pagamento estornada: `credit_card`, `boleto` ou `pix`.
Aceita vários separados por vírgula.
- name: status
in: query
required: false
description: >-
Etapa do reembolso. Aceita vários separados por vírgula. Valores:
pending, approved, processing, refunded, refused, failed,
awaiting_bank_details, bank_details_received, invalid_bank_details,
ted_processing.
schema:
type: array
items:
type: string
enum:
- pending
- approved
- processing
- refunded
- refused
- failed
- awaiting_bank_details
- bank_details_received
- invalid_bank_details
- ted_processing
nullable: true
description: >-
Etapa do reembolso. Aceita vários separados por vírgula. Valores:
pending, approved, processing, refunded, refused, failed,
awaiting_bank_details, bank_details_received,
invalid_bank_details, ted_processing.
- name: startDate
in: query
required: false
description: >-
Início do período (ISO 8601 com timezone), inclusive. Aplica-se ao
`dateField`.
schema:
type: string
format: date-time
nullable: true
description: >-
Início do período (ISO 8601 com timezone), inclusive. Aplica-se ao
`dateField`.
- name: endDate
in: query
required: false
description: >-
Fim do período (ISO 8601 com timezone), inclusive. Aplica-se ao
`dateField`.
schema:
type: string
format: date-time
nullable: true
description: >-
Fim do período (ISO 8601 com timezone), inclusive. Aplica-se ao
`dateField`.
- name: dateField
in: query
required: false
description: >-
Campo a que `startDate` e `endDate` se aplicam: `createdAt` (pedido)
ou `refundedAt` (dinheiro devolvido). Default: `createdAt`.
schema:
type: string
enum:
- createdAt
- refundedAt
nullable: true
description: >-
Campo a que `startDate` e `endDate` se aplicam: `createdAt`
(pedido) ou `refundedAt` (dinheiro devolvido). Default:
`createdAt`.
- name: sortBy
in: query
required: false
description: >-
Campo de ordenação: `createdAt` (pedido) ou `refundedAt` (dinheiro
devolvido). Default: `createdAt`.
schema:
type: string
enum:
- createdAt
- refundedAt
nullable: true
description: >-
Campo de ordenação: `createdAt` (pedido) ou `refundedAt` (dinheiro
devolvido). Default: `createdAt`.
- name: sortDir
in: query
required: false
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
schema:
type: string
enum:
- asc
- desc
nullable: true
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
- name: page
in: query
required: false
description: Número da página a retornar.
schema:
type: integer
minimum: 0
exclusiveMinimum: true
default: 1
description: Número da página a retornar.
- name: limit
in: query
required: false
description: Quantidade de itens por página.
schema:
type: integer
minimum: 0
exclusiveMinimum: true
maximum: 100
default: 10
description: Quantidade de itens por página.
responses:
'200':
description: Lista de reembolsos
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
transactionId:
type: string
description: ID da transação relacionada ao registro.
paymentId:
type: string
description: ID do pagamento relacionado ao registro.
amount:
type: integer
description: Valor em centavos.
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
status:
type: string
description: >-
Situação do reembolso. Valores: `pending`,
`approved`, `processing`, `refunded`, `refused`,
`failed`, `awaiting_bank_details`,
`bank_details_received`, `invalid_bank_details`,
`ted_processing`.
reason:
type: string
description: Motivo informado para a operação.
requestedByType:
type: string
description: >-
Origem da solicitação: `api`, `admin`, `customer` ou
`gateway`.
paymentMethod:
type: string
nullable: true
description: 'Forma de pagamento (ex.: credit_card, pix, boleto).'
customerId:
type: string
nullable: true
description: >-
Comprador da venda estornada (`cust_`), copiado da
transação quando o estorno é criado. Nulo quando a
transação não tem cliente.
customerName:
type: string
nullable: true
description: Nome do comprador quando o estorno foi criado.
customerEmail:
type: string
nullable: true
description: E-mail do comprador quando o estorno foi criado.
customerDocument:
type: string
nullable: true
description: >-
Documento do comprador (CPF ou CNPJ) quando o
estorno foi criado.
customerDocumentType:
type: string
nullable: true
description: 'Tipo do documento do comprador: `cpf` ou `cnpj`.'
additionalInfo:
type: object
nullable: true
properties:
checkoutLinkId:
type: string
description: >-
Id do link de checkout (`chk_`) da venda de
origem — a mesma chave do `additionalInfo` da
transação.
description: >-
Vínculo com a venda de origem, copiado da transação
quando o estorno é criado. Nulo quando a venda foi
criada direto pela API, sem link de checkout.
failureReason:
type: string
nullable: true
description: Motivo da falha do processamento.
reviewedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a solicitação foi revisada (ISO
8601).
refundedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o estorno foi concluído (ISO
8601).
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro (ISO
8601).
description: Lista de registros retornados na página atual.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
description: Dados de paginação do resultado.
example:
data:
- id: rfd_j3cpkaysqmix17mxhcmv8qypl
transactionId: txn_aqbcw2lky42xfidw5pcdss8h1
paymentId: pay_jxt9b5qv1x0h0h8ustleqjgr8
amount: 14990
currency: BRL
status: pending
reason: Cliente solicitou cancelamento da compra
requestedByType: api
paymentMethod: credit_card
customerId: cust_lhsmn6ugmjotm5qvnunrr2hz1
customerName: Maria Silva
customerEmail: maria.silva@example.com
customerDocument: '12345678909'
customerDocumentType: cpf
additionalInfo:
checkoutLinkId: chk_byd8p3p79re859jpkmr0j65n3
failureReason: null
reviewedAt: null
refundedAt: null
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
pagination:
page: 1
limit: 10
total: 1
totalPages: 1
'400':
description: Filtro inválido
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````