> ## Documentation Index > Fetch the complete documentation index at: https://docs.pay.v4companyamaral.com/llms.txt > Use this file to discover all available pages before exploring further. # Emitir cobrança Pix > Cria a cobrança na conta de recebimento do lojista (com split da taxa do V4 Pay), salva no banco e devolve o código "copia e cola" e a imagem do QR Code (base64). O status inicial é `pending` e muda para `paid` automaticamente quando o pagamento é confirmado. ## OpenAPI ````yaml /openapi.yaml post /pix openapi: 3.1.0 info: title: V4Pay API version: 2.0.0 description: > API do gateway de pagamentos V4Pay: autenticação, clientes, cobranças, cupons e emissão de Pix — cada lojista tem uma conta de recebimento no CNPJ dele, e a cobrança leva um split com a taxa do V4 Pay. Todas as rotas protegidas usam token JWT — o usuário é identificado pelo token, nunca por `user_id` no corpo da requisição. servers: - url: https://v4pay-api.vercel.app description: Produção. - url: http://localhost:3000 description: Ambiente local de desenvolvimento. security: [] tags: - name: Pix description: Emitir e consultar cobranças Pix — o coração da API. - name: Cobranças description: Registro direto de cobranças e a listagem do histórico da loja. - name: Clientes description: Cadastro de pagadores para reutilizar nas cobranças. - name: Links de pagamento description: URLs públicas reutilizáveis que abrem o checkout com o valor definido. - name: Checkout (público) description: >- As rotas que a página de pagamento usa — sem autenticação, o pagador não tem conta. - name: Produtos description: Catálogo da loja; um produto pode virar cobrança ou link. - name: Cupons description: Descontos aplicados no checkout e na emissão por produto. - name: Assinaturas description: Cobrança recorrente, gerada por um cron diário. - name: Webhooks (endpoints) description: >- As URLs do seu servidor que recebem os eventos da loja, com assinatura HMAC. - name: Chaves de API description: Credenciais de integração (v4pay_test_ / v4pay_live_), revogáveis. - name: Conta de recebimento description: Cadastro da empresa e a conta que recebe — vale no modo subconta. - name: Aprovação de produção description: >- O fluxo para liberar a operação em produção — dados da empresa, documentos e análise da equipe. - name: Saques description: >- Pedidos de saque do saldo — suspensos no modo conta única (REPASSE_MANUAL). - name: Membros da loja description: Convites e papéis de quem opera a loja junto com o dono. - name: Conta (auth) description: Cadastro, login, perfil e a troca de ambiente da sessão. - name: Auditoria description: Trilha das ações feitas na loja, com quem fez e de onde. - name: Sistema description: Saúde da API. - name: Interno description: >- USO INTERNO DO PAINEL — documentado por transparência, não para integração: pode mudar sem aviso (Roadmap, aprovações da equipe, cron, login com Google, onboarding). paths: /pix: post: tags: - Pix summary: Emitir cobrança Pix description: > Cria a cobrança na conta de recebimento do lojista (com split da taxa do V4 Pay), salva no banco e devolve o código "copia e cola" e a imagem do QR Code (base64). O status inicial é `pending` e muda para `paid` automaticamente quando o pagamento é confirmado. operationId: createPix requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PixRequest' responses: '201': description: Cobrança Pix emitida com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Charge' aviso: type: string description: >- Só vem quando, no modo produto, o vínculo com o produto e as URLs de retorno não puderam ser gravados (os campos ainda não existem no banco deste ambiente). A cobrança vale normalmente. '400': description: > Dados inválidos, ou valor abaixo do mínimo de R$ 5,00 (`codigo: VALOR_MINIMO`, com o mínimo em `valor_minimo`). content: application/json: schema: type: object properties: error: type: object properties: message: type: string codigo: type: string enum: - VALOR_MINIMO valor_minimo: type: number example: 5 '401': $ref: '#/components/responses/Unauthorized' '409': description: > A conta de recebimento do lojista ainda não pode cobrar: não existe neste ambiente (`SUBCONTA_INEXISTENTE`) ou ainda não foi aprovada (`SUBCONTA_NAO_APROVADA`). Veja a situação e o link para enviar documentos em `GET /receiving-account`. content: application/json: schema: type: object properties: error: type: object properties: message: type: string codigo: type: string enum: - SUBCONTA_INEXISTENTE - SUBCONTA_NAO_APROVADA aprovacao: $ref: '#/components/schemas/AprovacaoSubconta' '500': description: Erro ao emitir o Pix. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: PixRequest: type: object description: >- Dados para emissão de uma cobrança Pix, em dois modos. MODO MANUAL (sem `product_id`): `amount`, `description` e os dados do pagador são obrigatórios como listado em `required`. MODO PRODUTO (com `product_id`): o valor é calculado NO SERVIDOR — `amount` enviado é IGNORADO (vale o preço do produto, menos o cupom); `description` enviada vale, senão o nome do produto; `expires_at` tem padrão de 24 horas; o pagador vem de `customer_id` OU dos campos inline (`novo_cliente: true` também o cadastra em clientes). Um produto por cobrança, quantidade 1, só Pix. required: - amount - description - customer_name - customer_email - customer_cpf - expires_at properties: product_id: type: string format: uuid description: >- Liga o MODO PRODUTO — produto ATIVO do lojista (`404` se não existir ou estiver inativo). O preço da cobrança passa a ser o dele. novo_cliente: type: boolean description: >- Só no modo produto, sem `customer_id` — `true` cadastra o pagador em clientes e liga o `customer_id` na cobrança; ausente/`false`, a cobrança é avulsa. coupon_code: type: string description: >- Só no modo produto — cupom do lojista aplicado sobre o preço, com as mesmas regras e erros da validação do checkout (`400`; abaixo de R$ 5,00, `codigo: VALOR_MINIMO`). example: BEMVINDO10 success_url: type: - string - 'null' description: >- Só no modo produto — para onde o checkout manda o pagador após pagar. URL http(s) validada (`400` fora disso); vazio limpa. cancel_url: type: - string - 'null' description: >- Só no modo produto — o "voltar" do checkout. Mesma validação da success_url. customer_id: type: string format: uuid description: >- ID de um cliente já cadastrado (opcional; no modo produto, tem precedência sobre os campos inline e carrega nome/e-mail/documento/telefone do cadastro). amount: type: number format: double minimum: 5 description: >- Valor da cobrança em reais. Mínimo R$ 5,00: abaixo disso a API devolve `400` com `codigo: VALOR_MINIMO`, antes de chamar o motor de pagamentos. example: 100.5 description: type: string maxLength: 140 description: Mensagem exibida ao pagador. example: 'Pagamento do pedido #123' customer_name: type: string example: Maria da Silva customer_email: type: string format: email example: maria@cliente.com customer_cpf: type: string description: >- Documento do pagador, obrigatório no Pix — CPF (11 dígitos) ou CNPJ (14), com dígitos verificadores validados; aceita formatado ou só números — a API guarda só os dígitos. example: '12345678901' customer_phone: type: string example: (11) 91234-5678 expires_at: type: string format: date-time example: '2026-09-30T23:59:59Z' Charge: type: object description: Objeto representando uma cobrança (com ou sem Pix emitido). properties: id: type: string format: uuid user_id: type: string format: uuid customer_id: type: - string - 'null' format: uuid txid: type: string description: Identificador da transação Pix. example: 9f3a1c2b4d5e6f708192a3b4c5d6e7f8 description: type: string example: 'Pagamento do pedido #123' amount: type: number format: double description: Valor em reais. example: 150.75 customer_name: type: string customer_email: type: string format: email customer_cpf: type: string customer_phone: type: string product_id: type: - string - 'null' description: >- Produto que originou a cobrança (modo produto); nulo em cobrança manual. success_url: type: - string - 'null' cancel_url: type: - string - 'null' expires_at: type: string format: date-time due_date: type: string format: date-time pix_code: type: string description: Código "copia e cola" do Pix. example: 00020126...5913NOME_RECEBEDOR6009SAO PAULO62070503***6304ABCD qr_code_url: type: - string - 'null' description: >- Imagem do QR Code em data URL (base64), gerada na hora a partir de `pix_code`. Só vem preenchida em cobrança `pending`; nas demais é `null`. example: data:image/png;base64,iVBORw0KGgoAAA... status: type: string enum: - pending - paid - canceled - refunded example: pending end_to_end_id: type: - string - 'null' description: Identificador da liquidação Pix (preenchido no pagamento). paid_at: type: - string - 'null' format: date-time description: Horário da confirmação do pagamento. created_at: type: string format: date-time AprovacaoSubconta: type: object description: > Aprovação (KYC) da conta de recebimento. Cada frente vale `PENDING` (falta enviar algo), `AWAITING_APPROVAL` (enviado, em análise), `APPROVED` ou `REJECTED`. Só com `geral = APPROVED` a cobrança é liberada. Enquanto isso, o `link_documentos` leva o lojista à página segura do parceiro para enviar documentos e fazer a selfie; ele some quando não falta mais nada. properties: aprovada: type: boolean description: true quando `geral` é APPROVED. conferida: type: boolean description: false se nunca conseguimos ler a aprovação. geral: type: - string - 'null' enum: - PENDING - AWAITING_APPROVAL - APPROVED - REJECTED - null dados_comerciais: type: - string - 'null' enum: - PENDING - AWAITING_APPROVAL - APPROVED - REJECTED - null conta_bancaria: type: - string - 'null' enum: - PENDING - AWAITING_APPROVAL - APPROVED - REJECTED - null documentos: type: - string - 'null' enum: - PENDING - AWAITING_APPROVAL - APPROVED - REJECTED - null conferida_em: type: - string - 'null' format: date-time link_documentos: type: - string - 'null' format: uri link_documentos_qr: type: - string - 'null' description: >- O mesmo link como QR code (imagem PNG em base64, data URL), para abrir no celular. Só em GET /receiving-account e na conferência. motivos_recusa: type: - string - 'null' description: Texto do motor de pagamentos quando algo foi recusado. Error: type: object properties: error: type: object properties: message: type: string description: Descrição da mensagem de erro. ErrorAuth: type: object description: > Segundo formato de erro, usado só pelo middleware de autenticação (token ausente, inválido ou chave revogada). Repare que aqui `error` é uma string, não um objeto. properties: error: type: string example: Token JWT ou chave de API ausente responses: Unauthorized: description: Não autenticado. Repare no formato — `error` é string neste caso. content: application/json: schema: $ref: '#/components/schemas/ErrorAuth' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Token JWT obtido em `/auth/login`, enviado no cabeçalho `Authorization` no formato `Bearer `. ````