# ValidaPay API

> API REST para Pix, checkout transparente, links de pagamento, assinaturas, split, subcontas, saques, devoluções e notas fiscais. Valores sempre em reais (BRL), nunca em centavos. Autenticação OAuth2 client_credentials.

## Ambientes

| Ambiente | API | OAuth |
|---|---|---|
| Produção | https://api.validapay.com.br | https://oauth2.validapay.com.br/auth/token |
| Sandbox | https://sandbox.validapay.com.br | https://oauth2-sandbox.validapay.com.br/auth/token |

## Recursos para agentes de IA

- **Servidor MCP: https://docs.validapay.com.br/mcp** — consulta a documentação sob demanda, sem carregar tudo. Peça ao usuário para adicionar essa URL nos conectores da IA dele.
- Contrato OpenAPI 3.1: https://docs.validapay.com.br/openapi.json
- Guia de integração (skill): https://docs.validapay.com.br/api/ai-skill
- Documentação completa em texto: https://docs.validapay.com.br/llms-full.txt
- Collection Postman (JSON válido): https://docs.validapay.com.br/collection.json

Markdown de qualquer página: acrescente `.md` à URL.

## Prefixos de identificador

- `cha_` — cobrança
- `prod_` — produto
- `price_` — preço
- `pl_` — link de pagamento
- `cs_` — sessão de checkout
- `cus_` — cliente
- `pm_` — cartão tokenizado
- `sub_` — assinatura
- `item_` — item de assinatura
- `ref_` — devolução
- `wdr_` — saque

## Guias

- [Introdução à API ValidaPay](https://docs.validapay.com.br/comece-aqui/introducao.md): Visão geral da API, ambientes, autenticação OAuth2 e primeiros passos da integração.
- [Collections e ambiente Postman](https://docs.validapay.com.br/comece-aqui/collections.md): Como importar a collection e o environment de sandbox para testar a API.
- [Integração assistida por IA](https://docs.validapay.com.br/comece-aqui/integracao-mcp.md): Servidor MCP, llms.txt e OpenAPI para conectar Claude, Cursor ou ChatGPT à documentação.
- [Webhooks](https://docs.validapay.com.br/comece-aqui/webhooks.md): Catálogo de eventos, assinatura HMAC, retentativas e boas práticas de recebimento.
- [Split de pagamento](https://docs.validapay.com.br/comece-aqui/split-pagamento.md): Divisão automática de valores entre a conta master e subcontas recebedoras.
- [Tokenização de cartão](https://docs.validapay.com.br/comece-aqui/tokenizacao.md): SDK @validapay/tokenize para gerar paymentMethodId sem trafegar PAN ou CVV.
- [Canais de suporte](https://docs.validapay.com.br/comece-aqui/canais-suporte.md): Como acionar o suporte técnico e comercial da ValidaPay.
- [Assinaturas — visão geral](https://docs.validapay.com.br/assinaturas-overview.md): Modelo de domínio, status, ciclos, itens e como assinaturas são criadas.
- [Assinaturas — eventos](https://docs.validapay.com.br/assinaturas-eventos.md): Eventos de webhook do ciclo de vida de assinaturas e seus payloads.
- [Subcontas — visão geral](https://docs.validapay.com.br/subcontas-overview.md): Onboarding de subcontas, propostas, status e operação via X-Sub-Account.
- [Subcontas — eventos](https://docs.validapay.com.br/subcontas-eventos.md): Eventos de onboarding e MED emitidos durante o ciclo de vida da subconta.
- [Subcontas — dados financeiros](https://docs.validapay.com.br/subcontas-financial-details.md): Saldo, extrato e detalhes financeiros por subconta.
- [Notas fiscais — visão geral](https://docs.validapay.com.br/notas-fiscais-overview.md): Configuração fiscal, padrão municipal ou nacional, momento da emissão e status da nota.
- [Devoluções — eventos](https://docs.validapay.com.br/devolucoes-eventos.md): Eventos de devolução Pix e estorno de cartão.

## Endpoints

### Geral

- [POST /auth/token](https://docs.validapay.com.br/documentacao-validapay2/post-autenticacao.md)

### Pix

- [GET /v1/charges/:chargeId](https://docs.validapay.com.br/documentacao-validapay2/get-status-de-cobranca.md)
- [POST /v1/charges/pix](https://docs.validapay.com.br/documentacao-validapay2/post-cobranca-imediata.md): Com esta funcionalidade você pode criar um QR Code de cobrança imediata.

### Split de pagamentos

- [POST /v1/charges/pix](https://docs.validapay.com.br/documentacao-validapay2/post-cobranca-imediata-com-split.md): Com esta funcionalidade você pode criar um QR Code de cobrança na sua conta e fazer split para outras contas ValidaPay.
- [POST /v1/charges/pix](https://docs.validapay.com.br/documentacao-validapay2/post-split-para-conta-master.md): Com esta funcionalidade você pode criar um QR Code de cobrança na conta de um _Seller_ e fazer split para a sua conta.
- [GET /v1/charges/:chargeId](https://docs.validapay.com.br/documentacao-validapay2/get-status-de-cobranca-com-split.md)

### Subcontas ValidaPay

- [POST /v1/proposals](https://docs.validapay.com.br/documentacao-validapay2/post-criar-subconta-pf.md): Com esta funcionalidade você pode criar subcontas Pessoa Física na ValidaPay. Ao criar a subconta ela ficará associada à
- [POST /v1/proposals](https://docs.validapay.com.br/documentacao-validapay2/post-criar-subconta-pj.md): Com esta funcionalidade você pode criar subcontas Pessoa Jurídica na ValidaPay. Ao criar a subconta ela ficará associada
- [GET /v1/proposals/:formId](https://docs.validapay.com.br/documentacao-validapay2/get-status-de-subconta.md): @botton
- [GET /v1/accounts/subaccounts](https://docs.validapay.com.br/documentacao-validapay2/get-listar-subcontas.md): Com esta rota você poderá listar todas as subcontas associadas à sua _master account_
- [GET /v1/charges](https://docs.validapay.com.br/documentacao-validapay2/get-listar-cobrancas.md): Com esta rota você poderá listar todas as cobranças que a sua _master account_ gerou em uma subcontas
- [GET /v1/wallet/balance](https://docs.validapay.com.br/documentacao-validapay2/get-saldo-subcontas.md): Com esta funcionalidade você pode verificar o saldo de uma ou várias subcontas

### Produtos

- [POST /v1/products](https://docs.validapay.com.br/documentacao-validapay2/post-criar-produto.md): Cria um novo produto ou serviço com nome, descrição, preço e configurações de recorrência.
- [GET /v1/products](https://docs.validapay.com.br/documentacao-validapay2/get-listar-produtos.md): Lista todos os produtos cadastrados com suporte a filtros por status e paginação.
- [GET /v1/products/:id](https://docs.validapay.com.br/documentacao-validapay2/get-buscar-produto.md): Retorna todos os detalhes de um produto específico, incluindo preço e configurações.
- [PUT /v1/products/:id](https://docs.validapay.com.br/documentacao-validapay2/put-atualizar-produto.md): Atualiza as informações de um produto, como nome, descrição ou preço.
- [DELETE /v1/products/:id](https://docs.validapay.com.br/documentacao-validapay2/delete-remover-produto.md): Remove um produto que não esteja vinculado a assinaturas ativas.
- [POST /v1/products/:id/archive](https://docs.validapay.com.br/documentacao-validapay2/post-arquivar-produto.md): Guarda o produto sem excluí-lo, mantendo o histórico de cobranças vinculadas.

### Links de pagamento

- [POST /v1/checkouts](https://docs.validapay.com.br/documentacao-validapay2/post-criar-link-de-pagamento.md): Cria uma página de pagamento (payment link) configurável, com produtos, formas de pagamento aceitas, cupons e aparência 
- [GET /v1/checkouts](https://docs.validapay.com.br/documentacao-validapay2/get-listar-links-de-pagamento.md): Lista todas as páginas de pagamento (checkouts) criadas, com seus status e configurações. Suporta paginação e filtros po
- [GET /v1/checkouts/:id](https://docs.validapay.com.br/documentacao-validapay2/get-buscar-link-de-pagamento.md): Retorna os detalhes completos de uma página de pagamento, incluindo produtos e formas de pagamento aceitas.
- [PUT /v1/checkouts/:id](https://docs.validapay.com.br/documentacao-validapay2/put-atualizar-link-de-pagamento.md): Atualiza as configurações de uma página de pagamento, como preço vinculado, parcelamento ou aparência. Todos os campos s
- [POST /v1/checkout-sessions](https://docs.validapay.com.br/documentacao-validapay2/post-criar-sessao-de-pagamento.md): Cria um acesso temporário e seguro a uma página de pagamento, com cliente e configurações pré-preenchidos. É de uso únic
- [GET /v1/checkout-sessions/:id](https://docs.validapay.com.br/documentacao-validapay2/get-buscar-sessao-de-pagamento.md): Retorna os dados de uma sessão de checkout ativa, como produtos disponíveis e formas de pagamento.

### Checkout Transparente

- [POST /v1/charges](https://docs.validapay.com.br/documentacao-validapay2/post-gerar-cobranca-pix.md): Gera uma cobrança PIX pelo checkout transparente. O cliente informa os dados diretamente na sua própria interface e você
- [POST /v1/charges](https://docs.validapay.com.br/documentacao-validapay2/post-gerar-cobranca-pix-automatico.md): Inicia uma assinatura com Pix Automático pelo checkout transparente. O cliente informa os dados na sua própria interface
- [POST /v1/charges](https://docs.validapay.com.br/documentacao-validapay2/post-gerar-cobranca-boleto.md): Gera uma cobrança via boleto pelo checkout transparente. O cliente informa os dados na sua própria interface e você os e
- [POST /v1/charges](https://docs.validapay.com.br/documentacao-validapay2/post-gerar-cobranca-cartao.md): Gera uma cobrança via cartão de crédito pelo checkout transparente. O cliente informa os dados na sua própria interface 

### Simular pagamentos

- [POST /v1/wallet/pay/:chargeId](https://docs.validapay.com.br/documentacao-validapay2/post-pagar-em-sandbox.md): Confirma o pagamento de uma cobrança do sandbox sem dinheiro de verdade. A ValidaPay envia ao seu webhook o mesmo evento

### Saques

- [POST /v1/wallet/withdraw](https://docs.validapay.com.br/documentacao-validapay2/post-saque-subconta.md): Com esta funcionalidade você pode criar um saque em uma subconta associada à sua _master account._
- [POST /v1/wallet/withdraw](https://docs.validapay.com.br/documentacao-validapay2/post-saque-master-account.md): Com esta funcionalidade você pode criar um saque da sua _conta ValidaPay._

### Extratos

- [GET /v1/wallet/transactions](https://docs.validapay.com.br/documentacao-validapay2/get-extrato-subconta.md): Com esta funcionalidade você pode isualizar movimentações em uma subconta associada a sua _master account_
- [GET /v1/wallet/transactions](https://docs.validapay.com.br/documentacao-validapay2/get-extrato-conta-master.md): Com esta funcionalidade você pode isualizar movimentações na sua conta

### Devolução Pix

- [POST /v1/wallet/refunds](https://docs.validapay.com.br/documentacao-validapay2/post-criar-devolucao-pix.md): Cria uma devolução PIX a partir do endToEndId da transação original. A devolução pode ser parcial ou total.
- [GET /v1/wallet/refunds](https://docs.validapay.com.br/documentacao-validapay2/get-consultar-status-da-devolucao-pix.md): Consulta se uma devolução PIX foi confirmada.

### Estorno Cartão

- [POST /v1/wallet/refunds](https://docs.validapay.com.br/documentacao-validapay2/post-criar-estorno-de-cartao.md): Cria um estorno de cartão de crédito a partir do chargeId da cobrança original. O estorno pode ser parcial ou total.
- [GET /v1/wallet/refunds](https://docs.validapay.com.br/documentacao-validapay2/get-consultar-status-do-estorno.md): Consulta se um estorno de cartão foi confirmado.

### Clientes

- [POST /v1/customers](https://docs.validapay.com.br/documentacao-validapay2/post-criar-cliente.md): Cadastra um cliente na sua conta a partir do CPF/CNPJ, com endereço opcional.
- [GET /v1/customers](https://docs.validapay.com.br/documentacao-validapay2/get-listar-clientes.md): Lista os clientes cadastrados na sua conta, com busca por texto e paginação por cursor.
- [GET /v1/customers](https://docs.validapay.com.br/documentacao-validapay2/get-buscar-cliente-por-documento.md): Busca direta de um único cliente pelo CPF/CNPJ exato, retornando junto o endereço padrão dele.
- [GET /v1/customers/:customerId](https://docs.validapay.com.br/documentacao-validapay2/get-detalhar-cliente.md): Retorna os dados completos de um cliente, incluindo todos os endereços cadastrados e o histórico de assinaturas.
- [PATCH /v1/customers/:customerId](https://docs.validapay.com.br/documentacao-validapay2/patch-atualizar-cliente.md): Atualiza os dados de um cliente. Envie apenas os campos que deseja alterar.
- [DELETE /v1/customers/:customerId](https://docs.validapay.com.br/documentacao-validapay2/delete-remover-cliente.md): Remove um cliente da sua conta.

### Assinaturas

- [GET /v1/subscriptions](https://docs.validapay.com.br/documentacao-validapay2/get-listar-assinaturas.md): Lista todas as assinaturas da conta com suporte a filtros por status, cliente, método de pagamento, produto e período.
- [GET /v1/subscriptions/:subscriptionId](https://docs.validapay.com.br/documentacao-validapay2/get-buscar-assinatura.md): Retorna os detalhes completos de uma assinatura específica.
- [PATCH /v1/subscriptions/:subscriptionId](https://docs.validapay.com.br/documentacao-validapay2/patch-atualizar-assinatura-item.md): Realiza upgrade ou downgrade de um item da assinatura. Envie old.itemId do item atual e new.priceId (e opcionalmente new
- [PATCH /v1/subscriptions/:subscriptionId](https://docs.validapay.com.br/documentacao-validapay2/patch-cancelar-item.md): Remove um item da assinatura sem cancelar a assinatura inteira.
- [DELETE /v1/subscriptions/:subscriptionId](https://docs.validapay.com.br/documentacao-validapay2/delete-cancelar-assinatura.md): Cancela uma assinatura ativa, interrompendo todas as cobranças futuras. Rota recomendada para cancelamento (preferir em 
- [POST /v1/subscriptions/:subscriptionId/items](https://docs.validapay.com.br/documentacao-validapay2/post-adicionar-item.md): Adiciona um novo produto ou serviço a uma assinatura já existente.
- [PUT /v1/subscriptions/:subscriptionId/items/:itemId](https://docs.validapay.com.br/documentacao-validapay2/put-atualizar-item.md): Rota canônica para upgrade ou downgrade de plano. Altera o priceId ou quantity de um item específico.
- [POST /v1/subscriptions/:subscriptionId/prorata](https://docs.validapay.com.br/documentacao-validapay2/post-calcular-pro-rata.md): Calcula o valor de pro rata para uma troca de plano sem efetuar cobrança.

### Notas Fiscais

- [GET /v1/invoices/notas](https://docs.validapay.com.br/documentacao-validapay2/get-listar-notas-fiscais.md): Lista as notas fiscais da conta, da mais recente para a mais antiga.
- [GET /v1/invoices/notas/summary](https://docs.validapay.com.br/documentacao-validapay2/get-resumo-de-notas-fiscais.md): Totais de notas da conta por status, em quantidade e em valor.
- [GET /v1/invoices/notas/:notaid](https://docs.validapay.com.br/documentacao-validapay2/get-consultar-nota-fiscal.md): Retorna uma nota pelo invoiceId devolvido na listagem — que na nota avulsa é o ref informado na emissão, e na nota de co
- [POST /v1/invoices/notas](https://docs.validapay.com.br/documentacao-validapay2/post-emitir-nota-fiscal.md): Emite uma nota fiscal de serviço avulsa, sem vínculo com cobrança ou assinatura.
- [POST /v1/invoices/notas/:notaid/emitir](https://docs.validapay.com.br/documentacao-validapay2/post-emitir-nota-de-uma-cobranca.md): Emite a nota de uma cobrança que já existe — a que nunca emitiu e também a que falhou. O identificador na URL é o da cob
- [POST /v1/invoices/notas/:notaid/verificar-emissao](https://docs.validapay.com.br/documentacao-validapay2/post-verificar-dados-para-emissao.md): Confere se uma cobrança tem tudo o que a nota fiscal exige, sem emitir nada. O identificador na URL é o da cobrança, com
- [DELETE /v1/invoices/notas/:notaid](https://docs.validapay.com.br/documentacao-validapay2/delete-cancelar-nota-fiscal.md): Cancela na prefeitura uma nota fiscal já autorizada. O identificador é o invoiceId da listagem.
- [POST /v1/invoices/notas/:notaid/reemitir](https://docs.validapay.com.br/documentacao-validapay2/post-reemitir-nota-fiscal.md): Gera uma nova nota para uma emissão que falhou na prefeitura. O identificador é o invoiceId da listagem.
- [POST /v1/invoices/notas/:notaid/reenviar](https://docs.validapay.com.br/documentacao-validapay2/post-reenviar-nota-por-e-mail.md): Reenvia por e-mail uma nota já autorizada. O identificador é o invoiceId da listagem.
- [GET /v1/invoices/notas/config](https://docs.validapay.com.br/documentacao-validapay2/get-listar-configuracoes-fiscais.md): Lista as configurações fiscais da conta.
- [GET /v1/invoices/notas/config/:configid](https://docs.validapay.com.br/documentacao-validapay2/get-consultar-configuracao-fiscal.md): Retorna uma configuração fiscal pelo id.
- [POST /v1/invoices/notas/config](https://docs.validapay.com.br/documentacao-validapay2/post-criar-configuracao-fiscal.md): Cadastra a empresa emissora: CNPJ, regime tributário, certificado digital e os tributos que entram na nota.
- [PUT /v1/invoices/notas/config/:configid](https://docs.validapay.com.br/documentacao-validapay2/put-atualizar-configuracao-fiscal.md): Atualiza uma configuração fiscal. Envie apenas os campos que mudam — os demais são preservados.
- [DELETE /v1/invoices/notas/config/:configid](https://docs.validapay.com.br/documentacao-validapay2/delete-excluir-configuracao-fiscal.md): Remove uma configuração fiscal da conta.

## Eventos de webhook

Payloads completos no contrato OpenAPI, seção `webhooks`.

- `subscription.created`: Assinatura criada, aguardando primeiro pagamento.
- `subscription.trial`: Assinatura entrou em período de teste. Não carrega objeto `trial`: o prazo está em `items[].price.trialDays`.
- `subscription.activated`: Assinatura ativada após confirmação de pagamento.
- `subscription.renewed`: Ciclo renovado e pago. Quando emitido pelo motor de cobrança, acrescenta os campos do próximo ciclo.
- `subscription.upgraded`: Plano da assinatura alterado para cima.
- `subscription.item_added`: Novo item adicionado à assinatura.
- `subscription.item_removed`: Item removido da assinatura.
- `subscription.downgrade_scheduled`: Downgrade agendado para o fim do ciclo.
- `subscription.canceled`: Assinatura cancelada. O ciclo corrente continua no payload, com o status em que ficou.
- `subscription.expired`: Assinatura expirada. O evento é assinável e o caminho de envio existe no backend; confirme com o time se algum fluxo já o dispara.
- `subscription.cancel_scheduled`: Cancelamento agendado; assinatura segue ativa até o fim do ciclo.
- `payment.success`: Pagamento confirmado. O payload difere entre cobrança avulsa via Pix direto e cobrança vinculada a uma assinatura.
- `payment.overdue`: Ciclo vencido sem pagamento. A assinatura passa a `DEFAULT` quando estava `ACTIVE`, ou a `PAST_DUE` quando estava `PENDING` ou `TRIALING`.
- `charge.expired`: Cobrança expirou sem pagamento. Só ocorre a partir de PENDING, PROCESSING ou AWAITING_PAYMENT; o `status` no payload é o da COBRANÇA.
- `payment.failed`: Tentativa de pagamento falhou. Schema próprio: não carrega a base de assinatura e usa `accountId`.
- `charge.created`: Cobrança gerada. Traz a base da assinatura mais os dados da cobrança — atenção: `status` aqui é o status da COBRANÇA.
- `refund.requested`: Devolução registrada e em processamento.
- `refund.confirmed`: Valor devolvido ao pagador.
- `refund.failed`: Devolução recusada ou falhou. O status enviado é `ERROR`.
- `onboarding.create`: Conta da subconta criada.
- `onboarding.backgroundcheck`: Análise de background concluída.
- `onboarding.documentscopy`: Etapa de documentoscopia atualizada.
- `onboarding.proposal`: Status final da proposta.
- `med.infraction.updated`: Infração do MED atualizada.
- `med.balance.blocked`: Saldo bloqueado por ordem do MED.
- `med.balance.unblocked`: Saldo desbloqueado.
- `med.refund.opened`: Processo de devolução do MED aberto.
- `med.refund.closed`: Processo de devolução do MED encerrado.

## Suporte

- E-mail: contato@validapay.com.br
- Credenciais: https://app.validapay.com.br/integracao/api