Refunds (Reembolsos) - Z2Pay Developers

Um refund (reembolso/estorno) devolve ao cliente o valor de um pagamento já liquidado. No Z2Pay, um refund nasce a partir de um pagamento (pay_...) e passa por um ciclo de estados até ser processado no gateway ou via transferência (no caso de boleto). Esta página cobre os endpoints de consulta e decisão manual de refunds: buscar por ID, listar por transação ou por pagamento, e aprovar ou recusar um refund pendente.

A criação de um refund não é feita aqui. Para abrir um pedido de reembolso, use o endpoint de estorno em Payments (POST /transactions/{transactionId}/payments/{paymentId}/refund). Esta página documenta o que acontece depois que o refund já existe.

Todas as requisições usam o header x-api-key. Veja Autenticação.

Endpoints

Método	Rota	Descrição
`GET`	`/refunds/{id}`	Busca um refund por ID
`GET`	`/refunds/transaction/{transactionId}`	Lista os refunds de uma transação
`GET`	`/refunds/payment/{paymentId}`	Lista os refunds de um pagamento
`POST`	`/refunds/{id}/approve`	Aprova um refund pendente e envia para processamento
`POST`	`/refunds/{id}/refuse`	Recusa um refund pendente

Estados do refund

O campo status indica em que ponto do ciclo o refund está. Os estados terminais (não mudam mais) são refunded, refused e failed.

Status	Significado
`pending`	Aguardando decisão manual (aprovar ou recusar)
`approved`	Aprovado; em transição para processamento
`processing`	Sendo processado no gateway
`refunded`	Reembolso concluído (terminal)
`refused`	Pedido recusado (terminal)
`failed`	Falha no processamento (terminal)
`awaiting_bank_details`	Boleto: aguardando o cliente informar os dados bancários
`bank_details_received`	Boleto: dados bancários recebidos, pronto para a transferência
`invalid_bank_details`	Boleto: dados bancários inválidos; novo pedido de dados enviado
`ted_processing`	Boleto: transferência (PIX/TED) em processamento

Auto-approve da company. Cada empresa tem uma configuração de aprovação automática de reembolsos (habilitada por padrão). Com auto-approve ligado, um refund de cartão é criado, aprovado e processado imediatamente — ou seja, ele pode já nascer em approved/processing e nunca passar por pending. Com auto-approve desligado, o refund nasce em pending e precisa ser aprovado pelos endpoints abaixo.

Fluxo de boleto. Boleto não é estornado no gateway: o valor é devolvido por transferência bancária (PIX/TED), então é preciso coletar os dados bancários do cliente. Por isso um refund de boleto, ao ser aprovado, vai para awaiting_bank_details em vez de processing. Depois que os dados chegam (bank_details_received), a transferência é processada (ted_processing) até concluir (refunded). A coleta de dados bancários acontece por um link/convite enviado ao cliente, fora deste conjunto de endpoints.

Buscar refund por ID

GET /refunds/{id}

Retorna os dados completos de um refund.

string

obrigatório

ID do refund (prefixo ref_).

curl https://api.sandbox.z2pay.com/refunds/ref_3kf9d2a7b1c5e8 \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "ref_3kf9d2a7b1c5e8",
  "companyId": "comp_a1b2c3d4e5",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "refunded",
  "reason": "Cliente solicitou cancelamento",
  "requestedBy": "api",
  "requestedByType": "api",
  "paymentMethod": "credit_card",
  "failureReason": null,
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:45:02.000Z",
  "refundedAt": "2026-06-24T13:45:05.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:45:05.000Z",
  "deletedAt": null
}

string

ID do refund (ref_...).

transactionId

string

ID da transação (txn_...).

paymentId

string

ID do pagamento estornado (pay_...).

amount

integer

Valor reembolsado, em centavos (ex.: 4990 = R$ 49,90).

currency

string

Moeda. Sempre BRL.

status

string

Estado atual do refund (ver tabela de estados acima).

reason

string

Motivo informado na criação do refund.

requestedBy

string

Identificador de quem solicitou o refund.

requestedByType

string

Origem da solicitação: api, admin, customer ou gateway.

paymentMethod

string | null

Método do pagamento estornado (ex.: credit_card, boleto). Pode ser null.

failureReason

string | null

Motivo da falha quando status é failed. Caso contrário, null.

reviewedBy

string | null

Quem aprovou/recusou o refund. null enquanto não revisado.

reviewedAt

string | null

Data/hora da revisão (ISO 8601). null enquanto não revisado.

refundedAt

string | null

Data/hora da conclusão do reembolso (ISO 8601). null enquanto não concluído.

createdAt

string

Data/hora de criação (ISO 8601).

updatedAt

string

Data/hora da última atualização (ISO 8601).

deletedAt

string | null

Data/hora de remoção lógica. Normalmente null.

Erros

Status	Quando ocorre
`404`	Refund não encontrado

Veja Erros para o formato da resposta de erro.

Listar refunds de uma transação

GET /refunds/transaction/{transactionId}

Retorna, de forma paginada, todos os refunds associados a uma transação.

transactionId

string

obrigatório

ID da transação (prefixo txn_).

page

integer

padrão:"1"

Página (começa em 1).

limit

integer

padrão:"20"

Itens por página. Mínimo 1, máximo 100.

curl "https://api.sandbox.z2pay.com/refunds/transaction/txn_9z8y7x6w5v4u?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "ref_3kf9d2a7b1c5e8",
      "transactionId": "txn_9z8y7x6w5v4u",
      "paymentId": "pay_1a2b3c4d5e6f",
      "amount": 4990,
      "currency": "BRL",
      "status": "refunded",
      "reason": "Cliente solicitou cancelamento",
      "paymentMethod": "credit_card",
      "refundedAt": "2026-06-24T13:45:05.000Z",
      "createdAt": "2026-06-24T13:44:58.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

data

array

Lista de refunds (mesma estrutura de Buscar refund por ID).

pagination

object

Mostrar campos

page

integer

Página atual.

limit

integer

Itens por página.

total

integer

Total de refunds encontrados.

totalPages

integer

Total de páginas.

Listar refunds de um pagamento

GET /refunds/payment/{paymentId}

Igual ao endpoint anterior, mas filtra pelos refunds de um pagamento específico.

paymentId

string

obrigatório

ID do pagamento (prefixo pay_).

page

integer

padrão:"1"

Página (começa em 1).

limit

integer

padrão:"20"

Itens por página. Mínimo 1, máximo 100.

curl "https://api.sandbox.z2pay.com/refunds/payment/pay_1a2b3c4d5e6f?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

A resposta tem o mesmo formato (data + pagination) do endpoint por transação.

Aprovar refund

POST /refunds/{id}/approve

Aprova um refund que está pendente e o envia para processamento. Para cartão, o refund segue para o gateway. Para boleto, o refund passa a aguardar os dados bancários do cliente (awaiting_bank_details).

string

obrigatório

ID do refund (prefixo ref_).

Este endpoint é idempotente: reenviar a mesma requisição com o header Idempotency-Key não cria um efeito duplicado. Veja Convenções.

Idempotency-Key

string

Chave única para garantir que a aprovação não seja aplicada mais de uma vez.

curl -X POST https://api.sandbox.z2pay.com/refunds/ref_3kf9d2a7b1c5e8/approve \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 7c1f0e2a-9b3d-4a6e-8f12-5d0c9b8a7e6f"

{
  "id": "ref_3kf9d2a7b1c5e8",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "processing",
  "reason": "Cliente solicitou cancelamento",
  "paymentMethod": "credit_card",
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:50:11.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:50:11.000Z"
}

O status retornado depende do método: cartão tende a ir para processing (e depois refunded), enquanto boleto vai para awaiting_bank_details.

Erros

Status	Quando ocorre
`404`	Refund não encontrado
`409`	O refund não pode ser aprovado no status atual (ex.: já terminal)

Veja Erros para o formato da resposta.

Recusar refund

POST /refunds/{id}/refuse

Recusa um refund pendente, levando-o ao estado terminal refused.

string

obrigatório

ID do refund (prefixo ref_).

O corpo é opcional e aceita um único campo:

reason

string

Motivo da recusa. Quando enviado, deve ter entre 1 e 4000 caracteres. O campo é validado, mas não substitui o reason original do refund na resposta (que mantém o motivo informado na criação).

Este endpoint é idempotente — informe o header Idempotency-Key para reenvios seguros.

Idempotency-Key

string

Chave única para garantir que a recusa não seja aplicada mais de uma vez.

curl -X POST https://api.sandbox.z2pay.com/refunds/ref_3kf9d2a7b1c5e8/refuse \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 1b2c3d4e-5f60-7a8b-9c0d-1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Reembolso fora do prazo de política" }'

{
  "id": "ref_3kf9d2a7b1c5e8",
  "transactionId": "txn_9z8y7x6w5v4u",
  "paymentId": "pay_1a2b3c4d5e6f",
  "amount": 4990,
  "currency": "BRL",
  "status": "refused",
  "reason": "Cliente solicitou cancelamento",
  "paymentMethod": "credit_card",
  "reviewedBy": "api",
  "reviewedAt": "2026-06-24T13:52:40.000Z",
  "createdAt": "2026-06-24T13:44:58.000Z",
  "updatedAt": "2026-06-24T13:52:40.000Z"
}

Erros

Status	Quando ocorre
`404`	Refund não encontrado
`409`	O refund não pode ser recusado no status atual (ex.: já terminal)

Veja Erros para o formato da resposta.

Veja também

Payments

Crie um refund estornando um pagamento.

Transactions

Entenda a transação que originou o pagamento.

Chargebacks

Estornos iniciados pelo emissor do cartão.

Erros

Formato dos erros e como tratá-los.

​Endpoints

​Estados do refund

​Buscar refund por ID

​Listar refunds de uma transação

​Listar refunds de um pagamento

​Aprovar refund

​Recusar refund

​Veja também

Payments

Transactions

Chargebacks

Erros

Endpoints

Estados do refund

Buscar refund por ID

Listar refunds de uma transação

Listar refunds de um pagamento

Aprovar refund

Recusar refund

Veja também