Criar cobrança

`POST /v1/charges`

Cria uma cobrança PIX imediata com QR Code. A resposta inclui o payload EMV (copia e cola) e a imagem do QR Code em Base64. A taxa da plataforma é automaticamente descontada via split de pagamento — você não precisa calcular nada.

Pré-requisitos

Para criar cobranças, seu merchant precisa:

KYC aprovado

Seus documentos foram analisados e aprovados pelo compliance.

Conta do adquirente configurada

A conta de recebimento foi configurada pelo time Liquera após a aprovação do KYC.

Chave PIX ativa

Você cadastrou uma chave PIX e ela está com status ativo.

Se alguma condição não for atendida, a API retornará 403 com uma mensagem explicando o que está faltando.

Request

POST https://api.liquera.com.br/v1/charges
Authorization: Bearer <jwt_ou_api_key>
Content-Type: application/json

Headers opcionais

string

Chave de idempotência com até 64 caracteres. Se uma cobrança com a mesma chave já existir para o seu merchant, a API retorna a cobrança original em vez de criar uma nova. Ideal para evitar duplicatas em retries. Use o ID do pedido ou transação no seu sistema.

Body

integer

required

Valor da cobrança em centavos. Mínimo: 1. Exemplo: 9990 = R$ 99,90.

string

required

Descrição da cobrança. Máximo de 255 caracteres. Aparece no comprovante do pagador.

integer

Tempo de expiração da cobrança em segundos. Mínimo: 60 (1 minuto). Máximo: 604800 (7 dias). Padrão: 86400 (24 horas).

object

Dados do pagador. Opcional — se não informado, o QR Code pode ser pago por qualquer pessoa.

Show campos do customer

string

required

Nome completo do pagador. Mínimo de 2 caracteres.

string

required

Email do pagador.

string

required

Telefone do pagador. Entre 10 e 15 dígitos (somente números, com DDD).

string

required

CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador. Apenas números, sem formatação.

object

Dados de rastreamento para atribuição de conversão. Todos os campos são opcionais.

Show campos de tracking

string

Fonte da campanha (ex: google, instagram).

string

Meio da campanha (ex: cpc, email).

string

Nome da campanha.

string

Variação do conteúdo do anúncio.

string

Palavra-chave da campanha.

string

Facebook Click ID (parâmetro fbclid da URL).

string

Facebook Browser ID (cookie _fbc).

string

Facebook Pixel ID (cookie _fbp).

string

URL de origem do pagador. Máximo de 2048 caracteres.

string

IP do pagador (IPv4 ou IPv6).

string

User-Agent do browser do pagador.

Exemplos

Cobrança simples
Com pagador identificado
Com idempotência e tracking

curl -X POST https://api.liquera.com.br/v1/charges \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9990,
    "description": "Pedido #1234 - Camiseta P"
  }'

curl -X POST https://api.liquera.com.br/v1/charges \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9990,
    "description": "Pedido #1234",
    "expiresIn": 3600,
    "customer": {
      "name": "João Silva",
      "email": "joao@gmail.com",
      "phone": "11999998888",
      "document": "12345678901"
    }
  }'

curl -X POST https://api.liquera.com.br/v1/charges \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: pedido-1234-tentativa-1" \
  -d '{
    "amount": 9990,
    "description": "Pedido #1234",
    "tracking": {
      "utmSource": "instagram",
      "utmMedium": "cpc",
      "utmCampaign": "lancamento-verao",
      "fbclid": "IwAR1abc...",
      "sourceUrl": "https://loja.exemplo.com.br/produto/camiseta"
    }
  }'

Response

object

Dados da cobrança criada.

Show campos

string

ID único da cobrança na Liquera.

string

ID da transação no sistema do adquirente.

string

Payload EMV do QR Code (formato “Pix Copia e Cola”).

string

Imagem do QR Code em Base64 com prefixo data:image/png;base64,. Use diretamente em <img src="..."> .

integer

Valor da cobrança em centavos.

string

Status inicial: PENDING.

integer

Tempo de expiração em segundos.

object | null

Dados do pagador se informado, ou null.

201 — Criada
200 — Idempotente (cobrança existente)
403 — KYC pendente
403 — Chave PIX inativa
422 — Documento inválido

{
  "charge": {
    "id": "clx3ghi789",
    "txid": "a1b2c3d4e5f67890abcdef1234567890",
    "qrCode": "00020126580014br.gov.bcb.pix0136...",
    "imageBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "amount": 9990,
    "status": "PENDING",
    "expiresIn": 86400,
    "customer": {
      "id": "clx0cus111",
      "name": "João Silva",
      "document": "12345678901"
    }
  }
}

Quando uma cobrança com o mesmo x-idempotency-key já existe, a API retorna a cobrança original com idempotent: true.

{
  "charge": {
    "id": "clx3ghi789",
    "txid": "a1b2c3d4e5f67890abcdef1234567890",
    "qrCode": "00020126580014br.gov.bcb.pix0136...",
    "amount": 9990,
    "status": "PENDING",
    "expiresIn": 86400,
    "customer": null,
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "idempotent": true
}

{
  "message": "Sua conta ainda não foi aprovada pelo compliance. Envie seus documentos."
}

{
  "message": "Sua chave PIX ainda não está ativa. Aguarde a ativação para criar cobranças."
}

{
  "message": "Documento do pagador não é um CPF nem CNPJ válido"
}

Status da cobrança

Status	Descrição
`PENDING`	Aguardando pagamento
`PAID`	Pagamento confirmado
`FAILED`	Falha no processamento
`CANCELED`	Cobrança cancelada
`REFUNDED`	Pagamento estornado

Cobranças

Saques

Criar cobrança

`POST /v1/charges`

Pré-requisitos

Request

Headers opcionais

Body

Exemplos

Response

Status da cobrança

​POST /v1/charges

​Pré-requisitos

​Request

​Headers opcionais

​Body

​Exemplos

​Response

​Status da cobrança

`POST /v1/charges`

Pré-requisitos

Request

Headers opcionais

Body

Exemplos

Response

Status da cobrança