> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4seletpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Estornar cobrança
> Estorna uma cobrança paga, total ou parcialmente. Sem `amount`, estorna todo o saldo restante. Um estorno parcial precisa ser de pelo menos 100 centavos e só um estorno por vez pode estar em processamento.
**O estorno é assíncrono.** A resposta traz a cobrança em `refund_processing`. A conclusão chega pelos webhooks `charge.refunded` ou `charge.partial_refunded`. O suporte a estorno, inclusive parcial, depende da adquirente da cobrança: quando ela não suporta, a resposta é 422 (`refund_not_supported`).
Sem o campo `amount`, o estorno devolve **todo o saldo restante** da cobrança. Para um estorno parcial, envie `amount` em centavos (mínimo de `100`).
O estorno é **assíncrono**. A resposta `200` traz `status: "refund_processing"`. O resultado final chega pelos webhooks `charge.refunded` ou `charge.partial_refunded`.
Só uma cobrança paga pode ser estornada, e apenas um estorno por vez. A disponibilidade do estorno depende da **adquirente que processou a cobrança**, não da configuração da conta: quando ela não suporta a operação, a resposta é `422` (`refund_not_supported`).
Depois de um estorno parcial confirmado, a cobrança fica `partially_refunded`, e `amount_refunded` e `amount_refundable` mostram o valor estornado e o saldo restante.
Envie o header `Idempotency-Key` para reenviar com segurança. Veja [Idempotência e limites](/pages/v2/start/idempotencia-e-limites).
## OpenAPI
````yaml POST /v2/charges/{id}/refund
openapi: 3.1.0
info:
title: 4Selet Pay API
description: >
API de processamento de pagamentos da plataforma 4Selet Pay. Suporta
cobranças únicas, assinaturas recorrentes, PIX, Cartão de Crédito. Todas as
rotas autenticadas requerem um Bearer Token obtido via `/v1/login`.
version: 1.0.0
contact:
name: 4Selet Pay
email: suporte@4selet.com.br
servers:
- url: https://sandbox.4seletpay.com.br/api
description: Servidor de Sandbox
security:
- bearerAuth: []
tags:
- name: Autenticação
description: Rotas de autenticação e criação de usuários
- name: Cobranças
description: Criação, consulta, cancelamento e reembolso de cobranças
- name: Pedidos
description: Consulta de pedidos e gerenciamento de confirmações desafiadas
- name: Cartões
description: Cadastro e gerenciamento dos cartões salvos de um cliente
- name: Assinaturas
description: Criação e gerenciamento de assinaturas recorrentes
- name: Faturas
description: Gerenciamento de faturas e pagamento de faturas em atraso
- name: Clientes Bloqueados
description: Gerenciamento de lista negra de clientes
- name: Contas
description: Criação e gerenciamento de contas na plataforma
- name: Aplicativo
description: Endpoints para dashboard e uso via aplicativo mobile
- name: Notificações Push
description: Envio e gerenciamento de notificações push
- name: Utilitários
description: Endpoints utilitários como listagem de fusos horários
- name: Gestão
description: Relatórios gerenciais (acesso restrito a Super Admins)
- name: Webhooks
description: Endpoints para receber notificações de gateways de pagamento
- name: Endpoints de Webhook
description: >-
Gerenciamento de endpoints de webhook para receber notificações de eventos
da plataforma
- name: Links de Pagamento
description: Criação e gerenciamento de links de pagamento com checkout pré-configurado
- name: Análise de Fraude
description: >-
API de Risco — consulta o risco de fraude de uma transação (autenticada
por chave de API)
- name: Pedidos (v2)
description: >-
API v2 — pedidos com um ou mais meios de pagamento, captura, cancelamento
e verificação por código
- name: Cobranças (v2)
description: API v2 — consulta e estorno de cobranças
- name: Cartões (v2)
description: API v2 — cadastro e consulta de cartões salvos
- name: Assinaturas (v2)
description: API v2 — criação e gerenciamento de assinaturas recorrentes
- name: Faturas (v2)
description: >-
API v2 — consulta, pagamento e verificação por código das faturas de
assinaturas
paths:
/v2/charges/{id}/refund:
post:
tags:
- Cobranças (v2)
summary: Estornar cobrança
description: >
Estorna uma cobrança paga, total ou parcialmente. Sem `amount`, estorna
todo o saldo restante. Um estorno parcial precisa ser de pelo menos 100
centavos e só um estorno por vez pode estar em processamento.
**O estorno é assíncrono.** A resposta traz a cobrança em
`refund_processing`. A conclusão chega pelos webhooks `charge.refunded`
ou `charge.partial_refunded`. O suporte a estorno, inclusive parcial,
depende da adquirente da cobrança: quando ela não suporta, a resposta é
422 (`refund_not_supported`).
operationId: v2RefundCharge
parameters:
- $ref: '#/components/parameters/V2Id'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/V2RefundChargeRequest'
examples:
total:
summary: Estorno total
value: {}
parcial:
summary: Estorno parcial de R$ 30,00
value:
amount: 3000
responses:
'200':
description: >-
Estorno solicitado. A cobrança fica em `refund_processing` até a
confirmação
content:
application/json:
schema:
$ref: '#/components/schemas/V2Charge'
example:
id: cha_8Kq2Lm9XvB3nT7pZ
object: charge
amount: 10000
currency: brl
status: refund_processing
paid: true
captured: true
amount_refunded: 0
amount_refundable: 0
payment_method_details:
type: card
payment_intent: cha_8Kq2Lm9XvB3nT7pZ
'400':
$ref: '#/components/responses/V2IdempotencyInvalid'
'401':
$ref: '#/components/responses/V2Unauthorized'
'403':
$ref: '#/components/responses/V2AccountBlocked'
'404':
$ref: '#/components/responses/V2ChargeNotFound'
'409':
$ref: '#/components/responses/V2IdempotencyInUse'
'422':
description: Estorno não permitido ou valor inválido
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
examples:
charge_not_refundable:
summary: Cobrança não está paga
value:
error:
type: invalid_request_error
code: charge_not_refundable
message: Somente uma cobrança paga pode ser estornada.
charge_already_refunded:
summary: Cobrança já estornada por completo
value:
error:
type: invalid_request_error
code: charge_already_refunded
message: Esta cobrança já foi estornada por completo.
charge_refund_in_progress:
summary: Estorno anterior ainda em processamento
value:
error:
type: invalid_request_error
code: charge_refund_in_progress
message: >-
Um estorno desta cobrança ainda está em processamento.
Tente novamente quando ele for concluído.
amount_too_large:
summary: Valor maior que o saldo estornável
value:
error:
type: invalid_request_error
code: amount_too_large
message: >-
O valor excede os 6000 centavos que ainda podem ser
estornados nesta cobrança.
param: amount
amount_too_small:
summary: Estorno parcial abaixo do mínimo
value:
error:
type: invalid_request_error
code: amount_too_small
message: O estorno parcial deve ser de pelo menos 100 centavos.
param: amount
refund_not_supported:
summary: Adquirente não suporta o estorno
value:
error:
type: invalid_request_error
code: refund_not_supported
message: A adquirente desta cobrança não suporta este estorno.
validation_error:
summary: Valor inválido
value:
error:
type: invalid_request_error
code: validation_error
message: The amount field must be at least 1.
param: amount
idempotency_key_conflict:
summary: Idempotency-Key usada com outro corpo
value:
error:
type: idempotency_error
code: idempotency_key_conflict
message: >-
The Idempotency-Key has already been used with a
different request body.
'429':
$ref: '#/components/responses/V2ThrottleExceeded'
'500':
$ref: '#/components/responses/V2ServerError'
'502':
description: >-
A adquirente não aceitou o estorno. A cobrança continua paga; tente
novamente mais tarde
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: api_error
code: refund_failed
message: >-
A adquirente não aceitou o estorno. Tente novamente mais
tarde.
security:
- secretKeyAuth: []
components:
parameters:
V2Id:
name: id
in: path
required: true
description: Identificador do recurso (o campo `id` devolvido pela API)
schema:
type: string
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: >
Chave de idempotência opcional e recomendada. Tem até 128 caracteres e
vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a
resposta original (mesmo status e mesmo corpo), sem processar de novo.
Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode
ser reutilizada. A mesma chave com um corpo diferente retorna 422
(`idempotency_key_conflict`), uma requisição original ainda em andamento
retorna 409 (`idempotency_key_in_use`) e uma chave com mais de 128
caracteres retorna 400 (`idempotency_key_invalid`).
schema:
type: string
maxLength: 128
example: pedido-1024-tentativa-1
schemas:
V2RefundChargeRequest:
type: object
properties:
amount:
type: integer
minimum: 1
description: >
Valor a estornar, em centavos. Sem `amount`, estorna todo o saldo
restante. Um estorno parcial precisa ser de pelo menos 100 centavos.
example: 3000
V2Charge:
type: object
description: Visão financeira de um pagamento
properties:
id:
type: string
example: cha_8Kq2Lm9XvB3nT7pZ
object:
type: string
enum:
- charge
amount:
type: integer
description: Valor em centavos
example: 10000
currency:
type: string
example: brl
status:
type: string
enum:
- pending
- paid
- refund_processing
- partially_refunded
- refunded
- chargeback
- failed
description: >
`failed` também cobre cobranças canceladas e expiradas.
`refund_processing`: um estorno foi pedido e aguarda confirmação.
paid:
type: boolean
description: A cobrança foi paga (inclusive se depois foi estornada)
captured:
type: boolean
description: A cobrança foi capturada (mesmo valor de `paid`)
amount_refunded:
type: integer
description: Valor já estornado, em centavos
example: 0
amount_refundable:
type: integer
description: Valor que ainda pode ser estornado, em centavos
example: 10000
payment_method_details:
type: object
properties:
type:
type: string
enum:
- card
- pix
- boleto
payment_intent:
type: string
description: O `id` do pagamento correspondente no pedido ou na fatura
example: cha_8Kq2Lm9XvB3nT7pZ
V2Error:
type: object
description: Envelope de erro da API v2
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request_error
- idempotency_error
- authentication_error
- api_error
description: Categoria do erro
code:
type: string
description: Código estável do erro. Use este campo na sua lógica
example: validation_error
message:
type: string
description: Texto técnico, para log e depuração. Não exiba ao pagador
example: The payments field is required.
param:
type: string
description: >-
Campo que causou o erro, em notação de ponto. Presente só quando
se aplica
example: payments
customer_message:
type: string
description: Texto para exibir ao pagador. Presente só quando se aplica
V2ThrottleError:
type: object
description: >
Corpo padrão, fora do envelope `error`, do limite geral de requisições e
do limite de reenvio do código de verificação
properties:
message:
type: string
example: Too Many Attempts.
responses:
V2IdempotencyInvalid:
description: O header `Idempotency-Key` tem mais de 128 caracteres
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: invalid_request_error
code: idempotency_key_invalid
message: Idempotency-Key must be 128 characters or fewer.
V2Unauthorized:
description: Chave de API ausente, inválida, revogada ou de outro ambiente
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: authentication_error
code: invalid_api_secret
message: Invalid API secret.
V2AccountBlocked:
description: >-
As requisições da conta estão bloqueadas. A resposta traz
`customer_message`
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: invalid_request_error
code: account_requests_blocked
message: As requisições desta conta estão bloqueadas.
customer_message: >-
Não foi possível concluir sua transação. Tente novamente mais
tarde.
V2ChargeNotFound:
description: Cobrança não encontrada nesta conta
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: invalid_request_error
code: resource_missing
message: Recurso "charge" não encontrado.
V2IdempotencyInUse:
description: >-
Uma requisição com a mesma `Idempotency-Key` ainda está em andamento.
Tente novamente em instantes
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: idempotency_error
code: idempotency_key_in_use
message: >-
A request with this Idempotency-Key is still being processed.
Retry shortly.
V2ThrottleExceeded:
description: >
Limite geral de requisições excedido (120 por minuto por chave de API e
por conta). Esta resposta não usa o envelope `error` da API v2.
headers:
X-RateLimit-Limit:
description: Limite de requisições da janela
schema:
type: integer
X-RateLimit-Remaining:
description: Requisições restantes na janela
schema:
type: integer
Retry-After:
description: Segundos até a próxima tentativa
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/V2ThrottleError'
example:
message: Too Many Attempts.
V2ServerError:
description: Erro inesperado ao processar a requisição
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: api_error
code: internal_error
message: Ocorreu um erro inesperado ao processar a requisição.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Token JWT obtido via `POST /v1/login`. Envie no header `Authorization:
Bearer `.
secretKeyAuth:
type: http
scheme: bearer
description: >
Chave de API (secret key) da conta, no formato `sk_live_...` (produção)
ou `sk_test_...` (Dev mode). Envie no header `Authorization: Bearer
`. Autentica todas as rotas da API v2 e as rotas de Análise de
Fraude. A chave identifica a conta, então a API v2 não usa o header
`account`. Uma chave só é aceita no ambiente em que foi criada. Gere a
sua no dashboard em Configurações → Chaves de API.
````