> ## Documentation Index > Fetch the complete documentation index at: https://docs.liquerapay.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar Cobrança PIX > Cria uma cobrança PIX e retorna o **QR Code** (em texto copia-e-cola e em imagem base64) para o seu cliente pagar. - O valor é em **centavos** (`amount`) - `method` hoje só aceita `"PIX"` - O `expiresIn` controla por quanto tempo o QR Code é válido, **em segundos** (60 a 2.592.000) - Você pode anexar um cliente cadastrado via `customerId` - O merchant precisa ter cobranças habilitadas e uma chave PIX ativa Cria uma cobrança PIX e retorna um QR Code pronto para apresentar ao cliente. `method` (fixo em `"PIX"`) e `amount` (em centavos, mínimo 100). Os demais campos são opcionais. **Exemplo:** ```json theme={null} { "method": "PIX", "amount": 5000, "description": "Pedido #1234", "customerId": "cust_018f3a2b7c4d7c40a1b2", "expiresIn": 1800 } ``` ## Como apresentar o QR Code A resposta traz dois formatos — escolha o melhor para seu canal: String **copia-e-cola**. Ideal para web/mobile com botão "Copiar código". PNG em base64 (`data:image/png;base64,...`). Renderize com ``. ```html theme={null} QR Code PIX ``` ## 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). ## OpenAPI ````yaml POST /transparents/create openapi: 3.1.0 info: title: API Liquerapay description: | API pública da Liquerapay para criar cobranças PIX, processar saques, gerenciar clientes e receber eventos via webhooks. ## Versão Beta A v1 está em **beta**. Endpoints e payloads podem sofrer pequenas alterações antes da versão estável (1.0). Recomendamos travar a versão da sua integração no `package.json` / `requirements.txt` enquanto estivermos em beta. Não há ambiente de sandbox — todas as chamadas acontecem contra o ambiente de produção. ## Como começar 1. Crie sua conta em [app.liquerapay.com](https://app.liquerapay.com) 2. Gere uma chave de API no painel (`liq_...`) 3. Faça sua primeira chamada em `https://api.liquerapay.com` version: 1.0.0-beta contact: name: Suporte Liquerapay url: https://liquerapay.com license: name: Proprietary servers: - url: https://api.liquerapay.com description: Produção security: - bearerAuth: [] tags: - name: Customers description: Cadastre e gerencie os clientes da sua loja para reutilizar em cobranças. - name: Checkout Transparente description: >- Crie cobranças PIX (QR Code copia-e-cola) direto pela API e gerencie devoluções. - name: Withdrawals description: Solicite saques do saldo disponível para uma chave PIX. - name: Webhooks description: Cadastre URLs para receber eventos da Liquerapay em tempo real. paths: /transparents/create: post: tags: - Checkout Transparente summary: Criar cobrança PIX description: > Cria uma cobrança PIX e retorna o **QR Code** (em texto copia-e-cola e em imagem base64) para o seu cliente pagar. - O valor é em **centavos** (`amount`) - `method` hoje só aceita `"PIX"` - O `expiresIn` controla por quanto tempo o QR Code é válido, **em segundos** (60 a 2.592.000) - Você pode anexar um cliente cadastrado via `customerId` - O merchant precisa ter cobranças habilitadas e uma chave PIX ativa requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateChargeRequest' responses: '201': description: Cobrança criada — apresente `brCode` ou `imageBase64` ao cliente. content: application/json: schema: $ref: '#/components/schemas/CreateChargeResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: CreateChargeRequest: type: object required: - method - amount additionalProperties: false properties: method: type: string enum: - PIX description: Método de pagamento — hoje só `"PIX"` é suportado. example: PIX amount: type: integer minimum: 100 maximum: 100000000 description: Valor da cobrança em centavos, sujeito ao limite do merchant. example: 5000 description: type: string maxLength: 140 description: Texto que aparece para o cliente no momento do pagamento. example: Pedido customerId: type: string maxLength: 50 description: Opcional. ID de um cliente já cadastrado para anexar à cobrança. example: cust_018f3a2b7c4d7c40a1b2 expiresIn: type: integer minimum: 60 maximum: 2592000 default: 86400 description: >- Tempo de validade do QR Code **em segundos** (60 a 2.592.000 = 30 dias). Padrão 86400 = 24h. example: 1800 CreateChargeResponse: type: object required: - data - error - success properties: data: $ref: '#/components/schemas/Charge' error: type: 'null' example: null success: type: boolean enum: - true example: true Charge: type: object required: - id - amount - status - txid - brCode - imageBase64 - createdAt properties: id: type: string example: chg_018f8e2d9a5f7b10c3d4 amount: type: integer example: 5000 status: $ref: '#/components/schemas/ChargeStatus' txid: type: string description: Identificador da transação enviado ao PSP. example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f brCode: type: string description: Código copia-e-cola do PIX. example: 00020126580014BR.GOV.BCB.PIX0136abc...6304ABCD imageBase64: type: string description: PNG do QR Code em base64 (`data:image/png;base64,...`). example: data:image/png;base64,iVBORw0KGgoAAAA... expiresAt: type: string format: date-time example: '2026-04-19T19:02:11.420Z' customer: allOf: - $ref: '#/components/schemas/CustomerSummary' nullable: true createdAt: type: string format: date-time example: '2026-04-19T18:32:11.420Z' Error: type: object required: - error - message - success properties: error: type: string description: >- Código do erro (ex.: `VALIDATION_ERROR`, `UNAUTHORIZED`, `NOT_FOUND`). example: VALIDATION_ERROR message: type: string description: Mensagem amigável descrevendo o erro. example: 'amount: deve ser um número inteiro positivo' success: type: boolean enum: - false example: false ChargeStatus: type: string enum: - PENDING - PAID - EXPIRED - REFUNDED - DISPUTED description: | - `PENDING`: QR Code emitido, aguardando pagamento - `PAID`: pagamento confirmado - `EXPIRED`: passou do tempo limite sem pagamento - `REFUNDED`: cobrança paga foi devolvida integralmente - `DISPUTED`: há uma infração/MED aberta contra o pagamento example: PAID CustomerSummary: type: object required: - id - name - taxId - email description: Customer resumido, anexado a uma cobrança. properties: id: type: string example: cust_018f3a2b7c4d7c40a1b2 name: type: string example: João Silva taxId: type: string description: CPF ou CNPJ (apenas números). example: '12345678900' email: type: string example: joao@exemplo.com phone: type: string nullable: true example: '+5511999999999' responses: BadRequest: description: Requisição inválida (validação ou regra de negócio). content: application/json: schema: $ref: '#/components/schemas/Error' examples: validation: summary: Erro de validação value: error: VALIDATION_ERROR message: 'amount: deve ser um número inteiro positivo' success: false business: summary: Erro de regra de negócio value: error: BAD_REQUEST message: >- Saldo insuficiente. Disponível 4500 centavos, necessário 5050 centavos success: false Unauthorized: description: Falha de autenticação (token inválido, ausente ou revogado). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: UNAUTHORIZED message: Token inválido ou ausente success: false Forbidden: description: Acesso negado para esta operação. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: FORBIDDEN message: Saques estão temporariamente bloqueados para este merchant success: false NotFound: description: Recurso não encontrado. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: NOT_FOUND message: Customer não encontrado success: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key ou JWT description: | Autentique suas requisições enviando o token no header `Authorization: Bearer `. O token pode ser: - Uma **API key** com prefixo `liq_`, gerada em [Dashboard Liquerapay → Configurações → API Keys](https://app.liquerapay.com). - 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). ````