> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liquerapay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Solicitar Devolução
> Solicita a devolução **integral** de uma cobrança paga. Não há body —
o `id` da cobrança é passado via query string. Não existe devolução parcial.
**Regras:**
- A cobrança precisa estar com status `PAID`
- A cobrança ainda não pode ter sido devolvida integralmente
- O merchant precisa ter saldo disponível para cobrir o valor (a taxa cobrada não é devolvida)
Solicita a devolução **integral** de uma cobrança paga.
O `id` da cobrança é passado como **query string**, sem body:
`POST /transparents/refund?id=chg_018f8e2d9a5f7b10c3d4`. Não existe
devolução parcial — o valor devolvido é sempre o total ainda não
devolvido da cobrança.
* A cobrança precisa estar com `status = PAID`
* A cobrança ainda não pode ter sido devolvida integralmente
* O merchant precisa ter saldo disponível para cobrir o valor
**Exemplo:**
```bash theme={null}
POST /transparents/refund?id=chg_018f8e2d9a5f7b10c3d4
```
**Resposta:**
```json theme={null}
{
"data": {
"id": "refu_018fa1b23c4d5e6f7081",
"chargeId": "chg_018f8e2d9a5f7b10c3d4",
"amount": 5000,
"status": "PENDING",
"createdAt": "2026-04-19T20:10:00.000Z"
},
"error": null,
"success": true
}
```
## Como funciona
O valor da cobrança é debitado do saldo `available` do merchant.
Status inicial: `PENDING`.
Solicitação assíncrona ao banco/PSP usando o `end2endId` da cobrança.
`COMPLETED` quando o PIX de devolução for confirmado, ou `FAILED` se
houver erro — acompanhe pelo webhook `REFUND_COMPLETED`/`REFUND_FAILED`.
## Erros comuns
| Erro | Causa |
| ----------------------------------------------- | ------------------------------------------------------------- |
| `400 BAD_REQUEST` (`Apenas cobranças pagas...`) | Cobrança não está com status `PAID` |
| `400 BAD_REQUEST` (`Cobrança já devolvida...`) | Não há mais valor a devolver (já foi devolvida integralmente) |
| `400 BAD_REQUEST` (`Saldo insuficiente...`) | Saldo `available` menor que o valor a devolver |
| `400 BAD_REQUEST` (`end2endId não disponível`) | Cobrança paga sem E2E registrado — contate o suporte |
| `404 NOT_FOUND` | Cobrança não existe ou pertence a outro merchant |
A **taxa cobrada na cobrança original não é devolvida**. Se você cobrou
R$ 50,00 com taxa de R$ 0,50 e devolver a cobrança, você terá um prejuízo
de R\$ 0,50 — debitado do seu saldo.
## OpenAPI
````yaml POST /transparents/refund
openapi: 3.1.0
info:
title: API Liquerapay
description: |
API pública da Liquerapay para criar cobranças PIX, processar saques,
gerenciar clientes e receber eventos via webhooks.
## Versão Beta
A v1 está em **beta**. Endpoints e payloads podem sofrer pequenas
alterações antes da versão estável (1.0). Recomendamos travar a versão
da sua integração no `package.json` / `requirements.txt` enquanto
estivermos em beta.
Não há ambiente de sandbox — todas as chamadas acontecem contra o
ambiente de produção.
## Como começar
1. Crie sua conta em [app.liquerapay.com](https://app.liquerapay.com)
2. Gere uma chave de API no painel (`liq_...`)
3. Faça sua primeira chamada em `https://api.liquerapay.com`
version: 1.0.0-beta
contact:
name: Suporte Liquerapay
url: https://liquerapay.com
license:
name: Proprietary
servers:
- url: https://api.liquerapay.com
description: Produção
security:
- bearerAuth: []
tags:
- name: Customers
description: Cadastre e gerencie os clientes da sua loja para reutilizar em cobranças.
- name: Checkout Transparente
description: >-
Crie cobranças PIX (QR Code copia-e-cola) direto pela API e gerencie
devoluções.
- name: Withdrawals
description: Solicite saques do saldo disponível para uma chave PIX.
- name: Webhooks
description: Cadastre URLs para receber eventos da Liquerapay em tempo real.
paths:
/transparents/refund:
post:
tags:
- Checkout Transparente
summary: Solicitar devolução
description: >
Solicita a devolução **integral** de uma cobrança paga. Não há body —
o `id` da cobrança é passado via query string. Não existe devolução
parcial.
**Regras:**
- A cobrança precisa estar com status `PAID`
- A cobrança ainda não pode ter sido devolvida integralmente
- O merchant precisa ter saldo disponível para cobrir o valor (a taxa
cobrada não é devolvida)
parameters:
- name: id
in: query
required: true
schema:
type: string
example: chg_018f8e2d9a5f7b10c3d4
responses:
'201':
description: Devolução iniciada.
content:
application/json:
schema:
$ref: '#/components/schemas/RefundResponse'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
RefundResponse:
type: object
required:
- data
- error
- success
properties:
data:
$ref: '#/components/schemas/Refund'
error:
type: 'null'
example: null
success:
type: boolean
enum:
- true
example: true
Refund:
type: object
required:
- id
- chargeId
- amount
- status
- createdAt
properties:
id:
type: string
example: refu_018fa1b23c4d5e6f7081
chargeId:
type: string
example: chg_018f8e2d9a5f7b10c3d4
amount:
type: integer
description: >-
Valor devolvido em centavos — sempre o total ainda não devolvido da
cobrança.
example: 5000
status:
type: string
description: Status da devolução (`PENDING`, `COMPLETED`, `FAILED`).
example: PENDING
createdAt:
type: string
format: date-time
example: '2026-04-19T20:10:00.000Z'
Error:
type: object
required:
- error
- message
- success
properties:
error:
type: string
description: >-
Código do erro (ex.: `VALIDATION_ERROR`, `UNAUTHORIZED`,
`NOT_FOUND`).
example: VALIDATION_ERROR
message:
type: string
description: Mensagem amigável descrevendo o erro.
example: 'amount: deve ser um número inteiro positivo'
success:
type: boolean
enum:
- false
example: false
responses:
BadRequest:
description: Requisição inválida (validação ou regra de negócio).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
validation:
summary: Erro de validação
value:
error: VALIDATION_ERROR
message: 'amount: deve ser um número inteiro positivo'
success: false
business:
summary: Erro de regra de negócio
value:
error: BAD_REQUEST
message: >-
Saldo insuficiente. Disponível 4500 centavos, necessário 5050
centavos
success: false
NotFound:
description: Recurso não encontrado.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: NOT_FOUND
message: Customer não encontrado
success: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key ou JWT
description: |
Autentique suas requisições enviando o token no header
`Authorization: Bearer `.
O token pode ser:
- Uma **API key** com prefixo `liq_`, gerada em
[Dashboard Liquerapay → Configurações → API Keys](https://app.liquerapay.com).
- Um **JWT** retornado pelo login do dashboard (uso interno).
Não há distinção de ambiente — toda chave vale para o único
ambiente disponível (produção).
````