Introdução à API ValidaPay

Devolve a cobrança inteira: situação, valor, comprador, endereço e os dados de pagamento do meio usado. Os blocos `pix` e `boleto` são excludentes — vem preenchido o do `paymentType` da cobrança, e o outro chega como `null`. O mesmo vale para `address`, que é `null` quando o comprador não tem endereço cadastrado. Para acompanhar um pagamento em aberto, prefira `GET /v1/charges/{chargeId}/status`: devolve o essencial e evita carregar comprador e endereço a cada consulta.

Com esta funcionalidade você pode criar um QR Code de cobrança imediata. **Case de uso:** _Como SaaS, quero gerar cobranças preenchendo apenas o valor do produto e nada mais_ **Regras condicionais (COBV):** `name` e `cep` do `customer` só são aceitos junto com `expiration`. Havendo `expiration` e `customer`, o trio `documentNumber`, `name` e `cep` passa a ser obrigatório em bloco. **Resposta:** os campos vêm na raiz — `emv` e `qrCode`, não aninhados sob `pix`. O `qrCode` já é uma data URL PNG pronta para exibir; não é preciso gerar a imagem no seu lado. **Correlação com o pedido:** envie `metadata` na criação e ele volta na resposta e no payload do webhook `payment.success`. É a forma recomendada de amarrar o pagamento ao seu pedido. > ⚠️ **Esta rota não tem idempotência.** `externalId` é aceito e descartado; duas chamadas iguais criam **duas cobranças**. Controle duplicidade no seu lado (índice `pedido → cobrança`) ou use `POST /v1/charges`, que responde `409 DUPLICATE_CHARGE`. O campo `externalTxid` documentado aqui identifica loja, caixa ou vendedor — não serve como chave de idempotência.

Resposta enxuta para acompanhar o pagamento de uma cobrança, sem comprador, endereço, nota fiscal nem split. Pensada para consulta repetida: enquanto `status` for `PENDING` ou `AWAITING_PAYMENT`, a cobrança segue em aberto; `PAID` preenche `paidAt`. O campo `expiresAt` diz até quando o Pix aceita pagamento, evitando uma segunda consulta só para saber a janela. Valores de `status`: `PENDING`, `PROCESSING`, `AWAITING_PAYMENT`, `PAID`, `FAILED`, `EXPIRED`, `CANCELED`, `ARCHIVED`, `DISPUTE`, `REFUNDED`, `PARTIALLY_REFUNDED` e `CHARGED_BACK`. Para o detalhe completo, use `GET /v1/charges/{chargeId}`.

Com esta funcionalidade você pode criar um QR Code de cobrança na sua conta e fazer split para outras contas ValidaPay. **Case de uso:** _Como SaaS, tenho parceiros/afiliados PF ou PJ. Quero gerar cobranças na minha conta preenchendo apenas o valor do produto e fazer split para as contas dos meus parceiros._ Use `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.

Com esta funcionalidade você pode criar um QR Code de cobrança na conta de um _Seller_ e fazer split para a sua conta. **Case de uso:** _Como SaaS tenho vários Sellers, cada um deles possui uma subconta ValidaPay. Quero gerar cobranças para qualquer subconta preenchendo apenas o valor do produto e fazer split para a minha conta Master_ > ⚠️ **Atenção:** O número da subconta é retornado via webhook quando a subconta é aprovada. Use `externalTxid` para identificar a **loja**, o **caixa** ou o **vendedor** responsável pela cobrança.

Com esta funcionalidade você pode criar subcontas Pessoa Física na ValidaPay. Ao criar a subconta ela ficará associada à sua conta (chamaremos de conta Master). Case de uso: _Como SaaS tenho vários Sellers, preciso gerar cobranças para esses Sellers e receber split em cada venda._ > ⚠️ **Atenção:** Não é possível criar uma subconta com mesmo email e telefone da _master account._ > ⚠️ **Atenção:** Dados de renda/faturamento no campo financialDetails são obrigatórios. Os respectivos códigos estão descritos no apêndice Campos Financeiros ao final da sessão Subcontas ValidaPay

Com esta funcionalidade você pode criar subcontas Pessoa Jurídica na ValidaPay. Ao criar a subconta ela ficará associada à sua conta (chamaremos de conta Master). Case de uso: _Como SaaS tenho vários Sellers, preciso gerar cobranças para esses Sellers e receber split em cada venda._ > ⚠️ **Atenção:** Não é possível criar uma subconta com mesmo email e telefone da _master account_ > ⚠️ **Atenção:** Dados de renda/faturamento no campo financialDetails são obrigatórios. Os respectivos códigos estão descritos no apêndice Campos Financeiros ao final da sessão Subcontas ValidaPay

@botton Quando a conta for aprovada, será enviado um evento na URL de webhook cadastrada nas rotas de criação de conta PF e PJ. O evento segue o seguinte layout: ``` json { "event": "account_approved", "status": "CONFIRMED", "account": { "account": "123456", "branch": "0001", "documentNumber": "123456789", "ispb": "13935893", "name": "Werner Heisenberg" }, "onboardingId": "fc0e6dab-8210-4f2d-8fce-2e94990b63ef", "documentNumber": "1234567889", "formId": "7b83fcb4-fe9c-4ad3-8d3a-621fe9c9ffc1", "createdAt": "2025-06-02T17:46:10.1120909" } ```

Com esta rota você poderá listar todas as subcontas associadas à sua _master account_

Com esta rota você poderá listar todas as cobranças que a sua _master account_ gerou em uma subcontas

Com esta funcionalidade você pode verificar o saldo de uma ou várias subcontas > ⚠️ **Atenção:** Para consultar o saldo de várias subcontas envie o header acoountId com o número das subcontas separado por vírgula, por exemplo: 9489623,9489624,9489625

Cria um novo produto ou serviço com nome, descrição, preço e configurações de recorrência. Os produtos criados ficam disponíveis no painel administrativo e podem ser utilizados tanto no checkout transparente (via API) quanto no checkout pro (link de pagamento). Tipos de recorrência em prices[].recurrenceType: - ONE_TIME → Avulsa - WEEKLY → Semanal - MONTHLY → Mensal - QUARTERLY → Trimestral - SEMIANNUAL → Semestral - YEARLY → Anual Case de uso: _Como SaaS, quero cadastrar meus planos como produtos com preços recorrentes, para que meus clientes possam assinar diretamente pelo checkout pro ou pela minha própria interface._

Lista todos os produtos cadastrados com suporte a filtros por status e paginação.

Retorna todos os detalhes de um produto específico, incluindo preço e configurações.

Atualiza as informações de um produto, como nome, descrição ou preço. Mesmos campos de POST (todos opcionais). Para atualizar preço existente, inclua `priceId` no item de `prices[]`.

Remove um produto que não esteja vinculado a assinaturas ativas.

Guarda o produto sem excluí-lo, mantendo o histórico de cobranças vinculadas.