# V4 Pay > Documentação do V4 Pay — cobranças Pix pelo painel ou pela API. - [Introdução](https://docs.pay.v4companyamaral.com/introduction.md): O V4 Pay é um gateway de cobrança Pix: você cria a cobrança, o cliente paga, você recebe. - [Quickstart](https://docs.pay.v4companyamaral.com/quickstart.md): Sua primeira cobrança Pix em menos de 5 minutos. - [Autenticação](https://docs.pay.v4companyamaral.com/authentication.md): Como gerar a chave de API e como enviá-la em cada requisição. - [Aprovação de produção](https://docs.pay.v4companyamaral.com/aprovacao-de-producao.md): Todo lojista começa em modo teste. Para receber dinheiro de verdade, o cadastro precisa ser aprovado pela equipe do V4 Pay. - [Ambiente de testes](https://docs.pay.v4companyamaral.com/ambiente-de-testes.md): Teste a integração inteira sem mover dinheiro: um interruptor no painel, ou uma chave de API de teste. - [Cobranças](https://docs.pay.v4companyamaral.com/cobrancas.md): Como emitir uma cobrança Pix, o que cada campo exige, os status possíveis e o que o pagador recebe. - [Links de pagamento e checkout](https://docs.pay.v4companyamaral.com/links-e-checkout.md): Uma URL pública que cobra por você: como criar links, como o checkout funciona e onde entram cupom e produto. - [Assinaturas](https://docs.pay.v4companyamaral.com/assinaturas.md): Cobrança recorrente: um cron diário gera a cobrança Pix de cada assinatura vencida. - [Modo de recebimento](https://docs.pay.v4companyamaral.com/modo-de-recebimento.md): Para onde vai o dinheiro das suas cobranças: os dois modos que o V4 Pay opera, e o que muda para você em cada um. - [Webhooks](https://docs.pay.v4companyamaral.com/webhooks.md): O V4 Pay chama o seu servidor quando algo acontece. Aqui estão os eventos, os payloads e como conferir a assinatura. - [Erros e códigos](https://docs.pay.v4companyamaral.com/erros-e-codigos.md): Todos os códigos de erro da API, com o status HTTP e o que fazer em cada um. - [Limites](https://docs.pay.v4companyamaral.com/limites.md): Os tetos da API em um lugar só: valores, tamanhos, expiração e limites de requisição. - [SDKs](https://docs.pay.v4companyamaral.com/sdks.md): Ainda não há SDK oficial. A API é HTTP puro e funciona com qualquer linguagem. - [Perguntas frequentes](https://docs.pay.v4companyamaral.com/faq.md): Respostas curtas para o que mais aparece. - [Changelog](https://docs.pay.v4companyamaral.com/changelog.md): O que mudou na API, em ordem do mais recente para o mais antigo. - [Visão geral da API](https://docs.pay.v4companyamaral.com/api-reference/introduction.md): Base URL, autenticação, formato das respostas e o mapa dos endpoints. - [Cadastrar usuário](https://docs.pay.v4companyamaral.com/api-reference/conta-auth/cadastrar-usuário.md): Cria um usuário do gateway. A senha é armazenada com hash bcrypt. - [Fazer login](https://docs.pay.v4companyamaral.com/api-reference/conta-auth/fazer-login.md): Autentica com e-mail e senha e devolve o token JWT (validade de 1h). - [Consultar a própria conta](https://docs.pay.v4companyamaral.com/api-reference/conta-auth/consultar-a-própria-conta.md): Retorna os dados atualizados da conta do token (tela de Perfil). Sempre a conta do próprio usuário — o header `x-store` não se aplica. A resposta inclui `environment` (`test` ou `live`), o ambiente da sessão. - [Atualizar a própria conta](https://docs.pay.v4companyamaral.com/api-reference/conta-auth/atualizar-a-própria-conta.md): Atualiza os dados da conta do token: nome pessoal, nome da loja (`company`), CNPJ, CPF, telefone e preferências de e-mail. Envie só os campos que quer alterar; `null` ou string vazia remove os opcionais. - [Trocar o ambiente da sessão (teste ou produção)](https://docs.pay.v4companyamaral.com/api-reference/conta-auth/trocar-o-ambiente-da-sessão-teste-ou-produção.md): Devolve um token NOVO com o `env` pedido; nada muda no banco. É assim que o painel entra em modo teste. Só vale para JWT — chave de API tem ambiente fixo. Login, cadastro e Google sempre começam em produção. - [Renovar o token JWT](https://docs.pay.v4companyamaral.com/api-reference/conta-auth/renovar-o-token-jwt.md): Renova um token ainda válido (sessão deslizante). O painel chama automaticamente quando o token está perto de expirar. A resposta inclui `environment` (`test` ou `live`), o ambiente da sessão. - [Respostas do assistente de primeiro acesso](https://docs.pay.v4companyamaral.com/api-reference/interno/respostas-do-assistente-de-primeiro-acesso.md): Grava de uma vez o que o lojista responde no assistente do painel (origem, responsável, nome da loja, se tem CNPJ, dados e endereço da empresa, segmento, faixa de faturamento) e marca `onboarding_completed_at`. **Não abre a subconta**: para isso o painel chama `POST /receiving-account` em seguida, q… - [Motor de recorrência (cron)](https://docs.pay.v4companyamaral.com/api-reference/interno/motor-de-recorrência-cron.md): Cobra todas as assinaturas ativas vencidas (next_billing_at <= agora). Autenticado por CRON_SECRET no header Authorization (Bearer) — na Vercel, o agendamento em vercel.json chama esta rota diariamente. - [Motor de recorrência (cron)](https://docs.pay.v4companyamaral.com/api-reference/interno/motor-de-recorrência-cron-1.md): Cobra todas as assinaturas ativas vencidas (next_billing_at <= agora). Autenticado por CRON_SECRET no header Authorization (Bearer) — na Vercel, o agendamento em vercel.json chama esta rota diariamente. - [Motor de liquidação dos saques (cron)](https://docs.pay.v4companyamaral.com/api-reference/interno/motor-de-liquidação-dos-saques-cron.md): Percorre os saques pendentes. No desenho de conta de recebimento, o dinheiro já cai na conta do lojista, então o saque pelo V4 Pay não existe: o motor devolve configured=false e não executa nada. Autenticado por CRON_SECRET no header Authorization (Bearer). - [Motor de liquidação dos saques (cron)](https://docs.pay.v4companyamaral.com/api-reference/interno/motor-de-liquidação-dos-saques-cron-1.md): Percorre os saques pendentes. No desenho de conta de recebimento, o dinheiro já cai na conta do lojista, então o saque pelo V4 Pay não existe: o motor devolve configured=false e não executa nada. Autenticado por CRON_SECRET no header Authorization (Bearer). - [Entrar com a conta Google](https://docs.pay.v4companyamaral.com/api-reference/interno/entrar-com-a-conta-google.md): Recebe o JWT de sessão do Appwrite (gerado no navegador depois do login com o Google), confirma no Appwrite que a identidade é do provedor `google` e devolve o token do V4 Pay. Se o e-mail ainda não tiver conta, ela é criada na hora. - [O quadro completo](https://docs.pay.v4companyamaral.com/api-reference/interno/o-quadro-completo.md): As 4 colunas sempre presentes (vazia = lista vazia), com os cartões ordenados por `position` (e criação mais recente primeiro no empate). - [Criar cartão (equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/criar-cartão-equipe-v4-pay.md) - [Editar cartão (equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/editar-cartão-equipe-v4-pay.md): Atualiza os campos enviados. Mover de coluna é enviar `status` novo (com `position`, se quiser reordenar). - [Apagar cartão (equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/apagar-cartão-equipe-v4-pay.md): Apaga o cartão e os votos e comentários dele (contagem em `removidos`). - [Curtir/descurtir um cartão](https://docs.pay.v4companyamaral.com/api-reference/interno/curtirdescurtir-um-cartão.md): Alterna a curtida do usuário (1 por pessoa). Limite de 60 por 10 minutos por usuário (`429`). - [Comentários do cartão](https://docs.pay.v4companyamaral.com/api-reference/interno/comentários-do-cartão.md): Do mais antigo ao mais novo. - [Comentar num cartão](https://docs.pay.v4companyamaral.com/api-reference/interno/comentar-num-cartão.md): Autor = usuário do token; o nome exibido é a loja (ou o nome) no momento do comentário. Texto puro até 1024 caracteres. Limite de 30 por 10 minutos por usuário (`429`). - [Apagar comentário (autor ou equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/apagar-comentário-autor-ou-equipe-v4-pay.md) - [Lista de lojistas por situação (equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/lista-de-lojistas-por-situação-equipe-v4-pay.md): Fila de análise. `status=pending` (padrão) sai em ordem de chegada. CPF e CNPJ saem MASCARADOS na lista — a íntegra só no detalhe. - [Dossiê de um lojista (equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/dossiê-de-um-lojista-equipe-v4-pay.md): Dados completos da empresa (documento SEM máscara — é a revisão) e a lista de documentos enviados. - [Baixar um documento do lojista (equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/baixar-um-documento-do-lojista-equipe-v4-pay.md): Responde o ARQUIVO (stream, `Content-Disposition: inline`), buscado do bucket privado pela chave da API. Não existe URL pública de documento. - [Aprovar um cadastro em análise (equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/aprovar-um-cadastro-em-análise-equipe-v4-pay.md): Só de quem está `pending`. O lojista recebe e-mail avisando (quando o e-mail está configurado). - [Recusar um cadastro em análise (equipe V4 Pay)](https://docs.pay.v4companyamaral.com/api-reference/interno/recusar-um-cadastro-em-análise-equipe-v4-pay.md): `motivo` obrigatório (10 a 1000 caracteres) — é o que o lojista lê para corrigir e reenviar. Só de quem está `pending`. - [Criar um novo cliente](https://docs.pay.v4companyamaral.com/api-reference/clientes/criar-um-novo-cliente.md): Cria um cliente vinculado ao usuário autenticado. - [Listar clientes](https://docs.pay.v4companyamaral.com/api-reference/clientes/listar-clientes.md): Retorna os clientes do usuário autenticado. - [Criar uma nova cobrança](https://docs.pay.v4companyamaral.com/api-reference/cobranças/criar-uma-nova-cobrança.md): Registra uma cobrança (sem emissão de Pix — para Pix use `POST /pix`). - [Listar cobranças](https://docs.pay.v4companyamaral.com/api-reference/cobranças/listar-cobranças.md): Lista as cobranças do usuário autenticado. - [Listar cupons](https://docs.pay.v4companyamaral.com/api-reference/cupons/listar-cupons.md): Lista os cupons do usuário autenticado. - [Criar um novo cupom](https://docs.pay.v4companyamaral.com/api-reference/cupons/criar-um-novo-cupom.md) - [Validar cupom](https://docs.pay.v4companyamaral.com/api-reference/cupons/validar-cupom.md): Verifica se um cupom do usuário autenticado é válido (não expirado e com usos disponíveis). - [Atualizar cupom](https://docs.pay.v4companyamaral.com/api-reference/cupons/atualizar-cupom.md): Atualiza apenas os campos enviados no corpo da requisição. - [Excluir cupom](https://docs.pay.v4companyamaral.com/api-reference/cupons/excluir-cupom.md) - [Listar produtos](https://docs.pay.v4companyamaral.com/api-reference/produtos/listar-produtos.md): Lista os produtos do usuário autenticado (mais recentes primeiro). - [Criar um novo produto](https://docs.pay.v4companyamaral.com/api-reference/produtos/criar-um-novo-produto.md) - [Buscar produto por id](https://docs.pay.v4companyamaral.com/api-reference/produtos/buscar-produto-por-id.md) - [Atualizar produto](https://docs.pay.v4companyamaral.com/api-reference/produtos/atualizar-produto.md): Atualiza apenas os campos enviados no corpo da requisição. - [Excluir produto](https://docs.pay.v4companyamaral.com/api-reference/produtos/excluir-produto.md) - [Listar assinaturas](https://docs.pay.v4companyamaral.com/api-reference/assinaturas/listar-assinaturas.md): Lista as assinaturas do usuário autenticado (mais recentes primeiro). - [Criar uma nova assinatura](https://docs.pay.v4companyamaral.com/api-reference/assinaturas/criar-uma-nova-assinatura.md) - [Cobrar agora](https://docs.pay.v4companyamaral.com/api-reference/assinaturas/cobrar-agora.md): Gera imediatamente a cobrança Pix desta assinatura (mesmo motor do cron). Falha se a assinatura não estiver ativa, não tiver CPF ou já houver uma cobrança pendente válida. - [Atualizar assinatura](https://docs.pay.v4companyamaral.com/api-reference/assinaturas/atualizar-assinatura.md): Atualiza apenas os campos enviados. Use o campo `status` para pausar (`paused`), reativar (`active`) ou cancelar (`canceled`) a assinatura. - [Excluir assinatura](https://docs.pay.v4companyamaral.com/api-reference/assinaturas/excluir-assinatura.md) - [Dados públicos de um link de pagamento](https://docs.pay.v4companyamaral.com/api-reference/checkout-público/dados-públicos-de-um-link-de-pagamento.md): Rota pública usada pela página /pay/:slug. Só retorna links ativos. - [Simular o pagamento de uma cobrança de teste](https://docs.pay.v4companyamaral.com/api-reference/checkout-público/simular-o-pagamento-de-uma-cobrança-de-teste.md): **Só para cobrança criada em modo teste.** Pede ao ambiente de testes do motor de pagamentos que dê a cobrança como paga, como se um Pix real tivesse caído. Dali em diante o caminho é o de produção: o motor entrega o webhook, a cobrança vira `paid` e o webhook do lojista é disparado. É o botão "Simu… - [Validar cupom no checkout do link](https://docs.pay.v4companyamaral.com/api-reference/checkout-público/validar-cupom-no-checkout-do-link.md): Rota pública: valida um cupom do dono do link e retorna o desconto e o total a pagar. O resgate só é contado quando a cobrança é paga. - [Gerar cobrança Pix a partir do link](https://docs.pay.v4companyamaral.com/api-reference/checkout-público/gerar-cobrança-pix-a-partir-do-link.md): Rota pública (com limite por IP): emite a cobrança Pix com o valor do link e retorna o txid para abrir o checkout (/checkout/:txid). - [Dados do comprovante (público)](https://docs.pay.v4companyamaral.com/api-reference/checkout-público/dados-do-comprovante-público.md): Rota pública usada pela página de checkout e pelo comprovante. Devolve a cobrança com o documento do pagador **mascarado no servidor** e o nome/CNPJ da loja que recebe. - [Listar links de pagamento](https://docs.pay.v4companyamaral.com/api-reference/links-de-pagamento/listar-links-de-pagamento.md): Lista os links de pagamento do usuário autenticado (mais recentes primeiro). - [Criar um link de pagamento](https://docs.pay.v4companyamaral.com/api-reference/links-de-pagamento/criar-um-link-de-pagamento.md): Gera um slug único; a URL pública do checkout é montada no frontend com esse slug. - [Atualizar link de pagamento](https://docs.pay.v4companyamaral.com/api-reference/links-de-pagamento/atualizar-link-de-pagamento.md): Atualiza apenas os campos enviados. Use `active` para ativar/desativar o link. - [Excluir link de pagamento](https://docs.pay.v4companyamaral.com/api-reference/links-de-pagamento/excluir-link-de-pagamento.md) - [Resumo do saldo](https://docs.pay.v4companyamaral.com/api-reference/saques/resumo-do-saldo.md): Retorna o total recebido (cobranças pagas), saques pendentes, total sacado e o valor disponível para saque. - [Listar saques](https://docs.pay.v4companyamaral.com/api-reference/saques/listar-saques.md): Lista os saques do usuário autenticado (mais recentes primeiro). - [Solicitar saque](https://docs.pay.v4companyamaral.com/api-reference/saques/solicitar-saque.md): Cria um saque pendente. O valor não pode exceder o saldo disponível. - [Cancelar saque](https://docs.pay.v4companyamaral.com/api-reference/saques/cancelar-saque.md): Cancela um saque que ainda está pendente. - [Listar membros da loja](https://docs.pay.v4companyamaral.com/api-reference/membros-da-loja/listar-membros-da-loja.md) - [Convidar membros](https://docs.pay.v4companyamaral.com/api-reference/membros-da-loja/convidar-membros.md): E-mails com cadastro viram membros ativos na hora; os demais ficam pendentes e ativam automaticamente no cadastro. Papéis: manager (tudo, exceto gerenciar membros), editor (cria/edita, sem excluir, saques ou reembolsos), viewer (somente leitura). Membros operam a loja enviando o header x-store com o… - [Lojas que posso operar como membro](https://docs.pay.v4companyamaral.com/api-reference/membros-da-loja/lojas-que-posso-operar-como-membro.md) - [Mudar o papel de um membro](https://docs.pay.v4companyamaral.com/api-reference/membros-da-loja/mudar-o-papel-de-um-membro.md) - [Remover membro ou cancelar convite](https://docs.pay.v4companyamaral.com/api-reference/membros-da-loja/remover-membro-ou-cancelar-convite.md) - [Listar chaves de API](https://docs.pay.v4companyamaral.com/api-reference/chaves-de-api/listar-chaves-de-api.md) - [Criar chave de API](https://docs.pay.v4companyamaral.com/api-reference/chaves-de-api/criar-chave-de-api.md): A chave completa (v4pay_...) só aparece na resposta de criação — anote na hora. Ela pode ser usada no header Authorization (Bearer) no lugar do token JWT. - [Revogar ou reativar chave de API](https://docs.pay.v4companyamaral.com/api-reference/chaves-de-api/revogar-ou-reativar-chave-de-api.md) - [Excluir chave de API](https://docs.pay.v4companyamaral.com/api-reference/chaves-de-api/excluir-chave-de-api.md) - [Listar webhooks do lojista](https://docs.pay.v4companyamaral.com/api-reference/webhooks-endpoints/listar-webhooks-do-lojista.md) - [Cadastrar webhook do lojista](https://docs.pay.v4companyamaral.com/api-reference/webhooks-endpoints/cadastrar-webhook-do-lojista.md): Endpoint que recebe eventos da V4 Pay (ex.: charge.paid) com assinatura HMAC-SHA256 do corpo no header X-V4Pay-Signature. - [Eventos disponíveis para assinar](https://docs.pay.v4companyamaral.com/api-reference/webhooks-endpoints/eventos-disponíveis-para-assinar.md): Lista os nomes de evento que um endpoint pode assinar. É a mesma lista que o painel mostra ao criar um webhook. - [Atualizar webhook do lojista](https://docs.pay.v4companyamaral.com/api-reference/webhooks-endpoints/atualizar-webhook-do-lojista.md) - [Excluir webhook do lojista](https://docs.pay.v4companyamaral.com/api-reference/webhooks-endpoints/excluir-webhook-do-lojista.md) - [Enviar evento de teste](https://docs.pay.v4companyamaral.com/api-reference/webhooks-endpoints/enviar-evento-de-teste.md): Dispara um evento `test` assinado para o endpoint. - [Emitir cobrança Pix](https://docs.pay.v4companyamaral.com/api-reference/pix/emitir-cobrança-pix.md): 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. - [Listar cobranças Pix](https://docs.pay.v4companyamaral.com/api-reference/pix/listar-cobranças-pix.md): Lista as cobranças Pix do usuário autenticado (as que possuem código Pix). - [Consultar status de uma cobrança Pix](https://docs.pay.v4companyamaral.com/api-reference/pix/consultar-status-de-uma-cobrança-pix.md): Consulta pelo txid uma cobrança do usuário autenticado. - [Cancelar cobrança pendente](https://docs.pay.v4companyamaral.com/api-reference/pix/cancelar-cobrança-pendente.md): Marca a cobrança como `canceled`. Só cobranças com status `pending` podem ser canceladas. ATENÇÃO — o cancelamento NA ORIGEM ainda não foi implementado: a rota responde 502 explicando o motivo. - [Devolver pagamento recebido](https://docs.pay.v4companyamaral.com/api-reference/pix/devolver-pagamento-recebido.md): Devolução (total ou parcial) de um Pix recebido; marca a cobrança como `refunded`. Só cobranças `paid` podem ser devolvidas. ATENÇÃO — a devolução ainda não foi implementada (ela desfaz o split, e isso é decisão de negócio): a rota responde 502 explicando o motivo. - [Simular pagamento (só em modo teste)](https://docs.pay.v4companyamaral.com/api-reference/pix/simular-pagamento-só-em-modo-teste.md): Marca uma cobrança **de teste** como paga, gera um `end_to_end_id` de ensaio e dispara o evento `charge.paid` para os seus webhooks com `simulado: true`. Só funciona quando a requisição está em modo teste; em produção responde 403. A cobrança precisa ser sua e estar `pending`. - [Listar a trilha de auditoria da loja](https://docs.pay.v4companyamaral.com/api-reference/auditoria/listar-a-trilha-de-auditoria-da-loja.md): Retorna as ações de escrita feitas na loja (painel e API), das mais recentes para as mais antigas. Todas as ações de criação, edição, exclusão, cancelamento, reembolso, login e cadastro são registradas automaticamente, com quem fez, a origem e o IP. - [Saúde da API](https://docs.pay.v4companyamaral.com/api-reference/sistema/saúde-da-api.md): Responde 200 quando a API está de pé. Sem autenticação. - [Situação da subconta do lojista](https://docs.pay.v4companyamaral.com/api-reference/conta-de-recebimento/situação-da-subconta-do-lojista.md): Diz se o lojista já tem conta de recebimento **no ambiente da requisição** (teste ou produção). Nunca devolve a chave de API da subconta. - [Cadastrar a empresa e abrir a subconta](https://docs.pay.v4companyamaral.com/api-reference/conta-de-recebimento/cadastrar-a-empresa-e-abrir-a-subconta.md): Abre a conta de recebimento do lojista com os dados da empresa e guarda as credenciais cifradas. Os nove campos obrigatórios são exigência do motor de pagamentos. O `user_id` vem do token, nunca do corpo. A chave de API da subconta **nunca** é devolvida. - [Conferir a aprovação da subconta agora](https://docs.pay.v4companyamaral.com/api-reference/conta-de-recebimento/conferir-a-aprovação-da-subconta-agora.md): Lê no motor de pagamentos, na hora, as quatro frentes da aprovação (dados comerciais, conta bancária, documentos e aprovação geral) e grava. Normalmente não é preciso: o motor avisa por webhook quando algo muda. Serve para logo depois de enviar documentos, quando o lojista quer ver o resultado sem e… - [Situação do cadastro de produção](https://docs.pay.v4companyamaral.com/api-reference/aprovação-de-produção/situação-do-cadastro-de-produção.md): O retrato completo do fluxo — status, dados faltantes, documentos enviados. Todas as rotas de `/producao` devolvem este mesmo formato, para o painel renderizar de uma vez. Sob loja compartilhada (`x-store`), o texto de `reject_reason` é omitido e `tem_motivo_recusa` (boolean) é enviado no lugar: o m… - [Enviar um documento](https://docs.pay.v4companyamaral.com/api-reference/aprovação-de-produção/enviar-um-documento.md): Multipart com os campos `tipo` e `arquivo` (PDF, JPG ou PNG, até 4 MB — o conteúdo é conferido pelos primeiros bytes, não pela extensão). Reenviar um tipo substitui o anterior. Só com status `sandbox` ou `rejected`, só pelo titular e só com sessão do painel (chave de API responde 403 `SOMENTE_PAINEL… - [Remover um documento enviado](https://docs.pay.v4companyamaral.com/api-reference/aprovação-de-produção/remover-um-documento-enviado.md): Mesmas regras de status e acesso do envio. - [Enviar o cadastro para análise](https://docs.pay.v4companyamaral.com/api-reference/aprovação-de-produção/enviar-o-cadastro-para-análise.md): Exige dados da empresa completos e os três documentos; muda o status para `pending`. Depois de uma recusa, reenviar limpa o motivo e volta para a fila. ## OpenAPI Specs - [openapi](/openapi.yaml)