Referência

Checkout Transparente é a forma de criar cobranças PIX chamando a API diretamente e renderizando o QR Code na sua própria interface — sem redirecionar o cliente para uma página hospedada pela Liquerapay. Use quando você quer controle total sobre a experiência de pagamento no seu app/site.

Também existe o Checkout Hospedado (carrinho com produtos + página de pagamento hospedada pela Liquerapay, incluindo links de pagamento reutilizáveis). Essa documentação chega em breve — por enquanto, esta seção cobre apenas o fluxo transparente (/transparents/*).

Fluxo padrão

Criar a cobrança

POST /transparents/create com amount e method: "PIX". Recebe o brCode e, se inscrito, o webhook recebe CHARGE_CREATED.

Apresentar ao cliente

Renderize a imageBase64 ou ofereça o brCode (copia-e-cola).

Cliente paga

O PSP confirma o pagamento. A cobrança vira PAID e creditamos seu saldo.

Você é notificado

Disparamos o webhook CHARGE_PAID para os endpoints inscritos nesse evento.

Ciclo de vida

Status	Significado
`PENDING`	QR Code emitido, aguardando pagamento
`PAID`	Pago — saldo creditado
`EXPIRED`	Tempo limite atingido sem pagamento
`REFUNDED`	Cobrança paga foi devolvida integralmente
`DISPUTED`	Há uma infração/MED aberta contra o pagamento

Campos da cobrança

Campo	Obrigatório?	Descrição
`method`	Sim	Fixo em `"PIX"` — hoje é o único método suportado
`amount`	Sim	Valor em centavos (mínimo 100, máximo 100.000.000), sujeito ao `minTicket`/`maxTicket` do merchant
`description`	Não	Texto exibido no app de pagamento (até 140 caracteres)
`customerId`	Não	ID de um customer já cadastrado
`expiresIn`	Não	Validade do QR Code em segundos (60 a 2.592.000, padrão 86400 = 24h)
`clientCallbackUrl`	Não	URL HTTPS pública do callback específico desta cobrança; a API cria ou atualiza o webhook no merchant autenticado para `CHARGE_CREATED` e `CHARGE_PAID` e substitui os destinos gerais nesses eventos
`split`	Não	Lista de repasses para outras contas Liquera (até 5). Ver Split de pagamento

Exemplo

POST /transparents/create
{
  "method": "PIX",
  "amount": 5000,
  "description": "Pedido #1234",
  "customerId": "cust_018f3a2b7c4d7c40a1b2",
  "expiresIn": 1800,
  "clientCallbackUrl": "https://meusite.com/webhooks/liquerapay"
}

Resposta:

{
  "data": {
    "id": "chg_018f8e2d9a5f7b10c3d4",
    "amount": 5000,
    "status": "PENDING",
    "txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f",
    "brCode": "00020126580014BR.GOV.BCB.PIX0136abc...6304ABCD",
    "imageBase64": "data:image/png;base64,iVBORw0KGgoAAAA...",
    "expiresAt": "2026-04-19T19:02:11.420Z",
    "netAmount": 4920,
    "split": [],
    "customer": {
      "id": "cust_018f3a2b7c4d7c40a1b2",
      "name": "João Silva",
      "taxId": "12345678900",
      "email": "joao@exemplo.com"
    },
    "createdAt": "2026-04-19T18:32:11.420Z"
  },
  "error": null,
  "success": true
}

Split de pagamento

POST /transparents/create aceita split[] para dividir a cobrança com outras contas Liquera. Cada repasse (FIXED em centavos ou PERCENT do bruto) é liquidado pelo PSP no pagamento: a sua conta recebe o líquido (netAmount), cada recebedor recebe a parte dele no saldo e um webhook SPLIT_RECEIVED. O recebedor precisa ser uma conta Liquera com KYC aprovado e subconta + chave PIX ativas. Detalhes e validações em Criar Cobrança → Split de pagamento.

Devoluções (refunds)

Cobranças PAID podem ser devolvidas integralmente via POST /transparents/refund. Regras:

A devolução é sempre do valor total — não há devolução parcial
A taxa cobrada na cobrança original não é devolvida
O merchant precisa ter saldo disponível para cobrir o valor da devolução
Cobrança com split: o débito é rateado — a sua conta perde o total menos os repasses, e cada recebedor de split é debitado da parte dele (todos precisam ter saldo, senão a devolução falha inteira)

Operações disponíveis

Operação	Endpoint
Criar cobrança	`POST /transparents/create`
Listar cobranças	`GET /transparents/list`
Consultar cobrança	`GET /transparents/check`
Solicitar devolução	`POST /transparents/refund`

Clientes

Checkout Transparente

Saques

Webhooks

Loja

Fluxo padrão

Ciclo de vida

Campos da cobrança

Exemplo

Split de pagamento

Devoluções (refunds)

Operações disponíveis

​Fluxo padrão

​Ciclo de vida

​Campos da cobrança

​Exemplo

​Split de pagamento

​Devoluções (refunds)

​Operações disponíveis

Fluxo padrão

Ciclo de vida

Campos da cobrança

Exemplo

Split de pagamento

Devoluções (refunds)

Operações disponíveis