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)

POST /transparents/refund

Solicitar devolução

cURL

curl --request POST \
  --url https://api.liquerapay.com/transparents/refund \
  --header 'Authorization: Bearer <token>'

201

Example

{
  "data": {
    "id": "refu_018fa1b23c4d5e6f7081",
    "chargeId": "chg_018f8e2d9a5f7b10c3d4",
    "amount": 5000,
    "status": "PENDING",
    "createdAt": "2026-04-19T20:10:00.000Z"
  },
  "error": null,
  "success": true
}

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.

Pré-requisitos

• 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:

POST /transparents/refund?id=chg_018f8e2d9a5f7b10c3d4

Resposta:

{
  "data": {
    "id": "refu_018fa1b23c4d5e6f7081",
    "chargeId": "chg_018f8e2d9a5f7b10c3d4",
    "amount": 5000,
    "status": "PENDING",
    "createdAt": "2026-04-19T20:10:00.000Z"
  },
  "error": null,
  "success": true
}

Como funciona

1. Validamos o saldo

   O valor da cobrança é debitado do saldo available do merchant.

2. Criamos o registro de refund

   Status inicial: PENDING.

3. Disparamos para o PSP

   Solicitação assíncrona ao banco/PSP usando o end2endId da cobrança.

4. Atualizamos o status

   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.

Authorizations

Authorization · string · header · required

Autentique suas requisições enviando o token no header Authorization: Bearer <token>.

O token pode ser:

• Uma API key com prefixo liq_, gerada em Dashboard Liquerapay → Configurações → API Keys.
• 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).

Query Parameters

id · string · required

Example:

"chg_018f8e2d9a5f7b10c3d4"

Response

201

application/json

Devolução iniciada.

data · object · required

Show child attributes

error · null · required

Example:

null

success · enum<boolean> · required

Available options: true

Example:

true