Documentação

Base de produção: https://api.livrepix.com. Envie sua chave no cabeçalho Authorization: Bearer lp_live_.... Nunca coloque a chave no navegador ou em repositórios.

Credenciais no painel

Entre no painel pelo link enviado ao seu e-mail para criar e revogar chaves, definir a URL padrão do webhook, copiar o segredo de assinatura ou rotacioná-lo. Uma chave nova é exibida por completo somente uma vez; depois, o painel mostra apenas o prefixo.

A URL padrão passa a valer para as novas cobranças que não enviarem webhook_url no corpo. Ao rotacionar o segredo, atualize seu sistema imediatamente: as próximas assinaturas usam o novo valor.

Criar cobrança

POST /api/v1/charges
Authorization: Bearer $LIVREPIX_KEY
Idempotency-Key: pedido_4821
Content-Type: application/json

{
  "amount_cents": 2500,
  "payer_cpf": "CPF_OU_CNPJ_VALIDO",
  "payer_name": "Cliente",
  "description": "Créditos",
  "external_id": "pedido_4821",
  "webhook_url": "https://seuapp.com/webhooks/livrepix"
}

amount_cents fica entre 1000 e 600000. Também é aceito amount como decimal. O CPF/CNPJ é obrigatório e fica armazenado somente como hash irreversível mais os quatro últimos dígitos.

Link e checkout incorporado

A resposta da criação inclui checkout_url. Envie essa URL ao cliente como link de pagamento ou incorpore o checkout no seu site. A área de pagamento é pública; sua chave de API nunca vai para o navegador.

<iframe
  src="https://livrepix.com/c/?id=lp_ch_..."
  title="Pagamento Pix"
  width="480"
  height="720"
  style="width:100%;max-width:480px;border:0;border-radius:16px"
  allow="clipboard-write">
</iframe>

O checkout pode ser incorporado por páginas HTTPS. Para testar em desenvolvimento, localhost e 127.0.0.1 também são aceitos.

Consultar

Taxas, liquidação e saque

No Pix In pela Eulen, o custo é R$ 1,00 por cobrança mais 1% para a LivrePix. Sem Wallet vinculada, o ledger credita o líquido no saldo do painel. Com uma LivrePix Wallet mainnet vinculada, as novas cobranças são liquidadas diretamente nela e não geram crédito duplicado no ledger. O acesso à plataforma é uma assinatura separada: os primeiros 30 dias não têm custo de assinatura; depois, o ciclo mensal custa R$ 29,90, com descontos nos ciclos de 3, 6 e 12 meses.

D+0 significa liquidação no mesmo dia. O valor é convertido em DEPIX, pareado 1:1 com o real. Com uma Wallet Liquid mainnet vinculada, as novas cobranças seguem diretamente para ela. O envio de DEPIX que já esteja no saldo LivrePix também é iniciado automaticamente em D+0 e entrega o valor integral, sem taxa de saque da LivrePix. A taxa de 1% pertence somente ao Pix In (Pix para DEPIX). A referência final fica registrada no histórico.

No Pix Out pela Eulen, o valor reservado é enviado integralmente à operadora. A Eulen calcula o Pix líquido e sua tarifa, estimada em 1%; a LivrePix não acrescenta margem nessa saída.

Para saque Pix, envie pix_key_type como cpf, cnpj, email, phone ou random. O campo payee_document deve conter o CPF ou CNPJ do titular. O documento e a chave ficam criptografados no destino protegido. Quando a conta usa a rota Conversões SistemasB, o histórico exibe awaiting_approval até a liberação operacional e muda para pago automaticamente após a confirmação do gateway. Essa rota desconta 1% do valor reservado; o painel mostra o valor líquido antes da confirmação.

Webhooks livrepix

Eventos enviados: charge.completed, charge.expired, charge.refunded e withdrawal.paid. O endpoint recebe X-Webhook-Timestamp e X-Webhook-Signature. A assinatura hexadecimal é HMAC-SHA256 de timestamp + "." + corpo_bruto.

// Node.js
const expected = crypto
  .createHmac('sha256', process.env.LIVREPIX_WEBHOOK_SECRET)
  .update(timestamp + '.' + rawBody)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'))) {
  throw new Error('assinatura inválida');
}

Responda HTTP 2xx em até 8 segundos. Entregas malsucedidas são repetidas com backoff exponencial. Trate também o seu processamento como idempotente usando o ID da cobrança.

Estados

creating → pending → completed. Uma cobrança pendente também pode virar expired; uma concluída pode virar refunded. O saldo só muda com eventos autenticados.