Skip to main content
POST
Criar cobrança PIX
Cria uma cobrança PIX e retorna um QR Code pronto para apresentar ao cliente.

Obrigatório

method (fixo em "PIX") e amount (em centavos, mínimo 100). Os demais campos são opcionais.
Exemplo:

Callback específico da cobrança

Use clientCallbackUrl quando uma cobrança precisar notificar um endpoint específico. A URL não precisa estar previamente cadastrada: a API valida a URL e cria ou atualiza internamente um webhook do merchant autenticado com CHARGE_CREATED e CHARGE_PAID.
  • CHARGE_CREATED é enfileirado logo depois que a cobrança é persistida, com status PENDING e os dados do PIX (sem imageBase64).
  • CHARGE_PAID é enviado quando o pagamento for confirmado.
  • O callback usa o header Liquera-Signature, além dos mesmos retries e histórico de entregas dos webhooks gerais.
  • Quando o campo é informado, esses eventos vão somente para o endpoint escolhido. Se omitido, seguem para todos os webhooks gerais inscritos.
O callback pertence ao merchant que criou a cobrança; webhooks cadastrados em outro merchant não recebem seus eventos. Para obter o secret e validar Liquera-Signature, cadastre previamente a mesma URL em POST /webhooks e guarde o valor retornado.

Split de pagamento

O campo opcional split[] divide a cobrança com outras contas Liquera. Os repasses são liquidados pelo PSP no momento em que a cobrança é paga — a sua conta recebe apenas o líquido, e cada recebedor recebe a parte dele direto no saldo (mais o webhook SPLIT_RECEIVED).
A resposta passa a trazer:
  • netAmount — centavos que ficam com a sua conta = amount − taxa da Liquera − soma dos repasses
  • split[] — cada repasse resolvido: { merchantId, mode, value, amount }, onde amount é o valor efetivo em centavos (no PERCENT, arredondado para baixo)
Cada merchantId do split precisa existir (senão 404 NOT_FOUND) e estar com KYC aprovado, subconta ativa e chave PIX ativa — caso contrário 400 BAD_REQUEST. Não é possível fazer split para uma chave PIX externa nem para a sua própria conta.
split[] aceita de 1 a 5 entradas, sem merchantId repetido.
taxa da Liquera + soma dos repasses tem que deixar pelo menos 1 centavo para você. Se estourar, a criação retorna 400 BAD_REQUEST com o detalhamento (bruto / taxa / splits / restante).
O recebedor de um split não paga taxa — ela sai inteira da sua conta, sobre o valor bruto, como em qualquer cobrança.
Devolver uma cobrança que teve split debita cada recebedor da parte dele, além da sua conta. Veja Solicitar Devolução.

Como apresentar o QR Code

A resposta traz dois formatos — escolha o melhor para seu canal:

brCode (texto)

String copia-e-cola. Ideal para web/mobile com botão “Copiar código”.

imageBase64 (imagem)

PNG em base64 (data:image/png;base64,...). Renderize com <img src={...}>.

Validações importantes

O merchant precisa ter cobranças habilitadas e uma chave PIX ativa cadastrada. Sem isso, a criação retorna 400 BAD_REQUEST.
Sua conta tem minTicket e maxTicket definidos, além do limite fixo de 100 a 100.000.000 centavos. Valores fora do intervalo retornam 400 BAD_REQUEST.
Se o customer não existir (ou pertencer a outro merchant), você recebe 404 NOT_FOUND.
Mínimo 1 minuto, máximo 30 dias. Padrão: 86400 segundos (24h). Atenção: o campo é em segundos, não minutos.
Texto exibido para o cliente no app de pagamento. Não envie dados sensíveis (PII, senhas, tokens).
A URL é opcional, tem no máximo 2.048 caracteres e precisa ser um endpoint HTTPS público. A API cria ou atualiza o webhook no merchant autenticado com CHARGE_CREATED e CHARGE_PAID.

Authorizations

Authorization
string
header
required

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

O token pode ser:

Não há distinção de ambiente — toda chave vale para o único ambiente disponível (produção).

Body

application/json
method
enum<string>
required

Método de pagamento — hoje só "PIX" é suportado.

Available options:
PIX
Example:

"PIX"

amount
integer
required

Valor da cobrança em centavos, sujeito ao limite do merchant.

Required range: 100 <= x <= 100000000
Example:

5000

description
string

Texto que aparece para o cliente no momento do pagamento.

Maximum string length: 140
Example:

"Pedido"

customerId
string

Opcional. ID de um cliente já cadastrado para anexar à cobrança.

Maximum string length: 50
Example:

"cust_018f3a2b7c4d7c40a1b2"

expiresIn
integer
default:86400

Tempo de validade do QR Code em segundos (60 a 2.592.000 = 30 dias). Padrão 86400 = 24h.

Required range: 60 <= x <= 2592000
Example:

1800

clientCallbackUrl
string<uri>

URL HTTPS pública opcional para receber CHARGE_CREATED e CHARGE_PAID somente desta cobrança. A API cria ou atualiza internamente o endpoint no merchant autenticado e substitui os webhooks gerais nesses eventos. Para obter o secret usado na assinatura, cadastre previamente a mesma URL em POST /webhooks.

Maximum string length: 2048
Example:

"https://meusite.com/webhooks/liquerapay"

split
object[]

Opcional. Divide a cobrança com outras contas Liquera (até 5 repasses). Cada recebedor precisa estar com KYC aprovado e ter subconta + chave PIX ativas. A soma dos repasses mais a taxa da Liquera precisa deixar pelo menos 1 centavo para a sua conta.

Maximum array length: 5
Example:

Response

Cobrança criada — apresente brCode ou imageBase64 ao cliente.

data
object
required
error
null
required
Example:

null

success
enum<boolean>
required
Available options:
true
Example:

true