> ## 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.
# Estornar pagamento
> Abre um pedido de estorno de um pagamento específico da transação — total ou parcial.
`POST /transactions/:transactionId/payments/:paymentId/refund`
Faz parte do recurso [Pagamentos](/pt-BR/payments) — o ciclo de vida do pagamento está lá, e o do
estorno em [Reembolsos](/pt-BR/refunds).
Abre um pedido de estorno para **um pagamento**. É a rota a usar quando a transação tem mais de um
pagamento e você quer devolver só um deles — para devolver a transação inteira, use
[`POST /transactions/{id}/refund`](/pt-BR/transactions/refund).
**O `200` cria um pedido, não devolve o dinheiro.** O estorno nasce como `rfd_` e segue o próprio
ciclo — pode precisar de aprovação, e o prazo de volta é da adquirente. Acompanhe por
[`GET /refunds/{id}`](/pt-BR/refunds/get); tratar esta resposta como "estornado" antecipa um fato
que ainda não aconteceu.
**Se aprova sozinho ou não, é configuração da sua conta.** Com auto-aprovação, o pedido já sai
encaminhado; sem ela, fica aguardando decisão. A mesma chamada, portanto, tem desfechos
diferentes em contas diferentes — não assuma um deles no código.
**`amount` faz o estorno parcial.** Omitido, devolve o valor total do pagamento. Em centavos, e
nunca maior do que o que resta a estornar.
**Os dois ids do caminho são conferidos juntos.** Um `paymentId` que exista mas pertença a outra
transação não é aceito — o `transactionId` da URL é afirmação sobre o pagamento, não enfeite.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/transactions/txn_ebgsvfsb4151nmbgvj4sek6ol/payments/pay_kd6z67zbp52rgtg2idms96fhm/refund \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-d '{ "amount": 5000, "reason": "Cliente desistiu de um dos itens" }'
```
O `reason` é obrigatório — sem ele a chamada responde `400` de validação.
```json Resposta 200 theme={null}
{
"refund": {
"id": "rfd_z3w8qmc4nx1te7bkhjs0dvpra",
"paymentId": "pay_kd6z67zbp52rgtg2idms96fhm",
"transactionId": "txn_ebgsvfsb4151nmbgvj4sek6ol",
"amount": 5000,
"reason": "Cliente desistiu de um dos itens",
"status": "pending",
"createdAt": "2026-08-11T14:05:00.000Z"
},
"processResult": null
}
```
A resposta é o par `{ refund, processResult }` — o mesmo formato, no singular, que o
[estorno da transação inteira](/pt-BR/transactions/refund) devolve no plural. `processResult`
vem preenchido quando o estorno é processado na hora (aprovação automática), com `success` e o
estorno atualizado.
## OpenAPI
````yaml openapi/psp.json POST /transactions/{transactionId}/payments/{paymentId}/refund
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:
/transactions/{transactionId}/payments/{paymentId}/refund:
post:
tags:
- Transactions
summary: Estornar payment
description: >-
Cria um pedido de refund para um payment específico. Suporta refund
parcial via campo amount. Comportamento de auto-approve é controlado
pela config da company
operationId: PaymentController_refundPayment
parameters:
- name: paymentId
in: path
required: true
description: ID do payment
schema:
type: string
- name: transactionId
in: path
required: true
description: ID da transação
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
minLength: 1
maxLength: 4000
description: Motivo do estorno (obrigatório, 1–4000 chars).
amount:
type: integer
minimum: 0
exclusiveMinimum: true
description: >-
Valor a estornar, em centavos; omitido estorna o valor total
do payment (parciais não podem exceder o saldo disponível).
required:
- reason
responses:
'200':
description: Refund criado e processado
content:
application/json:
schema:
type: object
properties:
refund:
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: Dados do estorno relacionado ao pagamento.
processResult:
type: object
properties:
success:
type: boolean
description: Indica se o processamento foi bem-sucedido.
refund:
type: object
description: Dados do estorno relacionado ao pagamento.
message:
type: string
description: Mensagem descritiva do resultado do processamento.
description: Resultado do processamento da operação.
example:
refund:
id: rfd_dt8xoet16jhqxrgn76f0x25vg
transactionId: txn_raqtaj22an9s5dexc1vthopl8
paymentId: pay_k0fg3q4jjcbi56hdhbi7xlj5e
amount: 9995
currency: BRL
status: refunded
reason: Estorno parcial - produto avariado
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: '2025-06-29T14:10:00.000Z'
createdAt: '2025-06-29T14:09:55.000Z'
updatedAt: '2025-06-29T14:10:00.000Z'
processResult:
success: true
refund:
id: rfd_dt8xoet16jhqxrgn76f0x25vg
transactionId: txn_raqtaj22an9s5dexc1vthopl8
paymentId: pay_k0fg3q4jjcbi56hdhbi7xlj5e
amount: 9995
currency: BRL
status: refunded
reason: Estorno parcial - produto avariado
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: '2025-06-29T14:10:00.000Z'
createdAt: '2025-06-29T14:09:55.000Z'
updatedAt: '2025-06-29T14:10:00.000Z'
message: Refund processado com sucesso
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
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
'404':
description: Payment não encontrado
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: NOT_FOUND
message: Payment not found
'409':
description: Payment não estornável ou valor excede limite
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: CONFLICT
message: No refundable payment found
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````