Introdução à API ValidaPay

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.

Detalhe da cobrança para credencial de API. Não use esta rota no loop de pagamento — para isso, `GET /v1/charges/{chargeId}/status`. Cobrança de outra conta responde `404` com `CHARGE_NOT_FOUND`, igual a um ID inexistente. **O que vem** - `saleType`: `ONE_TIME` (avulsa) ou `RECURRING`. Na avulsa, `subscription` e `price` vêm `null`. - `paymentType`: `PIX`, `PIX_AUTOMATICO`, `BOLETO` ou `CREDIT_CARD`. `pix` e `boleto` são excludentes: só o bloco do meio usado vem preenchido; o outro é `null`. Cartão deixa os dois `null`. - `status`: `PENDING`, `PROCESSING`, `AWAITING_PAYMENT`, `PAID`, `FAILED`, `EXPIRED`, `CANCELED`, `ARCHIVED`, `DISPUTE`, `REFUNDED`, `PARTIALLY_REFUNDED`, `CHARGED_BACK`. - `amount` é o valor cobrado do pagador (base da nota). `netAmount` é o líquido do lojista depois da taxa. `fee.amount` é a taxa total; `percentageRate` a alíquota; `percentage` e `fixed` as partes percentual e fixa, em reais. - `address` é o endereço de cobrança do cliente. Sem endereço, `address` é `null`. `zipCode` sai só com dígitos. `cityCode` é o código IBGE, número. - Depois do pagamento, `payer` traz `name` e `document`. Antes, `null`. - PIX (incluindo PIX Automático) preenche `pix` com `emv`, `qrCode`, `dueDate` e `discount` (`type` `PERCENT` ou `FIXED`, `value`, `validUntil`, `originalAmount`). Sem desconto, `discount` é `null`. - Boleto preenche `boleto` com `emv`, `qrCode`, `barCode`, `digitableLine`, `dueDate` e `instructions` (`fine`, `interest` e o mesmo `discount`). Aqui `emv` e `qrCode` são o Bolepix: o mesmo boleto aceita pagamento por Pix. O PDF não vem neste bloco — baixe em `GET /v1/charges/{chargeId}/boleto.pdf`. - `qrCode`, dentro de `pix` e de `boleto`, é a imagem do EMV já renderizada como data URL PNG, pronta para um `<img src>`. Sem EMV, é `null` — cartão deixa o bloco inteiro `null`. - `nf` (`id`, `status`, `number`, `issuedAt`, `pdfUrl`) evita reemitir a nota. Sem nota, `null`. - `subscription.subscriptionId` serve em `DELETE /v1/subscriptions/{subscriptionId}`. Confira `status` e `cancelAtPeriodEnd` antes. `subscription.status`: `PENDING`, `TRIALING`, `ACTIVE`, `PAST_DUE`, `DEFAULT`, `EXPIRED`, `CANCELED`, `COMPLETED`, `ARCHIVED`. **Para que serve** - Nota fiscal: `customer`, `address` (`cityCode`), `amount`, `productName` ou `price.name` - Cancelar assinatura: `subscription.subscriptionId` - Conciliação: `transactionId`, `endToEndId`, `externalTxid`, `grossAmount`, `netAmount`, `fee`, `paidAmount`, `payer` - Cobrar de novo: `pix` / `boleto`, `failureReason`, `expiresAt`

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. PIX e boleto trazem `emv` e `qrCode` — a mesma imagem do detalhe, data URL PNG pronta para exibir. Cartão traz os dois `null`. 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}`.

Cancela uma cobrança em aberto. O cancelamento é definitivo: não existe rota para reabrir a cobrança, o caminho é criar uma nova. **Só cancela cobrança em aberto.** `status` precisa ser `PENDING` ou `AWAITING_PAYMENT`. Qualquer outro valor — incluindo `PAID`, `EXPIRED` e uma cobrança já cancelada — responde `400` com `CHARGE_NOT_CANCELABLE`. Para desfazer um pagamento já liquidado use a devolução Pix ou o estorno de cartão, não esta rota. Cobrança de outra conta responde `404` com `CHARGE_NOT_FOUND`, igual a um ID inexistente. **O que o cancelamento arrasta junto** - A cobrança passa a `CANCELED` e, quando é PIX ou boleto, também é cancelada no provedor — o QR Code e a linha digitável deixam de aceitar pagamento. - Havendo `invoiceId`, a fatura vai junto para `CANCELED`; o campo volta na resposta. - Notas fiscais da cobrança são tratadas e o resultado vem em `notas`: `canceled` são as canceladas na prefeitura, `flagged` as marcadas para cancelamento manual, `failed` as que a prefeitura recusou cancelar e `untouched` as que não exigiam ação. Falha ao tratar notas não impede o cancelamento da cobrança — os quatro contadores voltam zerados. - Sendo a última cobrança em aberto do ciclo de uma assinatura, o ciclo também é cancelado e `cycleNumber` traz o número dele. Fora desse caso, `cycleNumber` é `null`. Cancelar uma cobrança não cancela a assinatura: o próximo ciclo continua gerando cobrança. Para encerrar a recorrência use `DELETE /v1/subscriptions/{subscriptionId}`.

Baixa o PDF do boleto. **Rota pública: não envie `Authorization`.** É o endereço que a API devolve em `pdfUrl` ao criar um boleto, e pode ser aberto direto pelo pagador. Responde o binário do PDF com `Content-Type: application/pdf`, exibido no navegador. Para forçar o download, acrescente `?download=1`. O arquivo é gerado na criação da cobrança, mas não depende disso: se ele não estiver armazenado, a rota o regenera na hora e devolve normalmente. Só responde `404 BOLETO_PDF_NOT_AVAILABLE` quando nem a regeneração é possível. Cobrança que não é boleto responde `400 CHARGE_NOT_BOLETO`.

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.

Cria uma cobrança no **cartão de crédito** e divide o valor com outras contas ValidaPay. O split é aplicado na própria transação do cartão: cada recebedor recebe a parte dele **direto na conta ValidaPay dele**, no prazo de recebimento de cartão, junto com os demais recebíveis. **Case de uso:** _Como plataforma com parceiros, quero vender no cartão e repassar a comissão de cada parceiro na própria venda, sem transferir depois._ ## Como o valor é dividido - **`fixed`** — o recebedor ganha exatamente o valor informado. - **`percentage`** — incide sobre o valor da cobrança **sem a taxa repassada ao comprador**. Com `passFeesToCustomer`, o comprador paga a taxa do cartão, mas o percentual do parceiro é calculado sobre o preço (ex.: cobrança de R$ 100,00 em 3x com repasse, comprador paga R$ 107,10 e o parceiro de 10% recebe R$ 10,00). - **A taxa do cartão sai inteira da sua conta.** Você fica com o valor líquido menos a parte dos recebedores. - O meio centavo de arredondamento fica com a sua conta. ## Quem pode receber O recebedor é identificado pelo **Id Público** da conta (no painel, **Gerenciamento > Minha Conta > Id Público**). No cartão ele precisa: - ter a **mesma configuração de recebimento de cartão** que a sua conta, incluindo o **mesmo prazo de recebimento** (por exemplo, as duas em D+30); - estar **habilitado para receber cartão** na ValidaPay. Uma conta que nunca vendeu no cartão ainda não está habilitada. Se algum recebedor não atender, a cobrança não é criada e a API responde `400` com o motivo. ## Limite do split A soma dos recebedores não pode passar do **valor líquido** da cobrança, já descontada a taxa do cartão. A conta usa o pior caso de parcelas que o comprador pode escolher (`maxInstallments`). Com `passFeesToCustomer`, vale a maior quantidade de parcelas **sem** repasse (`freeInstallments`). ## Pagar agora ou depois - **Com `cardToken`:** o cartão é cobrado na hora e o split já sai aplicado. - **Sem `cardToken`:** a cobrança fica `PENDING` e o comprador paga pelo link. O split configurado na criação é aplicado no pagamento. Se, entre a criação e o pagamento, algum recebedor deixar de poder receber cartão, **a cobrança não é feita**: a API responde `400 SPLIT_NOT_APPLIED` com uma mensagem genérica para o comprador, e a ValidaPay é alertada. Ajuste o split e gere uma nova cobrança. ## Estorno O **estorno total** funciona normalmente. O **estorno parcial** de uma cobrança no cartão com split pode não estar disponível: nesse caso a rota de estorno responde `400 CARD_SPLIT_PARTIAL_REFUND_UNSUPPORTED` e é preciso fazer o estorno total. ## Pix e boleto Esta mesma rota aceita `split` com `paymentMethod` `pix` ou `boleto`. Nesses métodos o valor do recebedor é transferido para a conta dele quando o pagamento é confirmado. > ⚠️ A rota de checkout transparente (`POST /v1/charges`) **não aceita** split no cartão nem no Pix Automático. Para cartão com split, use esta rota. ## Resposta - **`200`** — com `cardToken` e cartão aprovado: `success: true`, `chargeId`, `status: "paid"`. Sem `cardToken`: `status: "PENDING"`, mais as opções de parcelamento. - **`402`** — cartão recusado pelo banco: `success: false`, `status: "failed"` e o motivo em `error`. ## Erros do split - `400 SPLIT_RECIPIENT_NOT_FOUND` — nenhum recebedor com esse Id Público - `400 SPLIT_RECIPIENT_PROVIDER_MISMATCH` — o recebedor tem outra configuração de recebimento de cartão - `400 SPLIT_RECIPIENT_SCHEDULE_MISMATCH` — o recebedor tem outro prazo de recebimento de cartão - `400 SPLIT_RECIPIENT_SELLER_NOT_FOUND` — o recebedor ainda não está habilitado para receber cartão - `400 SPLIT_RECIPIENT_SELLER_INACTIVE` — a habilitação de cartão do recebedor está inativa - `400 SPLIT_RECIPIENT_ACCOUNT_BLOCKED` — a conta do recebedor está bloqueada - `400 SPLIT_DUPLICATE_RECIPIENT` — o mesmo recebedor aparece mais de uma vez - `400 SPLIT_EXCEEDS_NET_AMOUNT` — a soma dos recebedores passa do valor líquido no pior caso de parcelas - `400 SPLIT_NOT_APPLIED` — um recebedor deixou de ser elegível antes do pagamento; a cobrança não foi feita

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:** a criação de cada subconta custa **R$ 15,00**, debitados do saldo da conta master quando a proposta é enviada. Se não houver saldo, a criação é recusada com `409 INSUFFICIENT_BALANCE_FOR_SUBACCOUNT_FEE`. No sandbox não há cobrança. > ⚠️ **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:** a criação de cada subconta custa **R$ 15,00**, debitados do saldo da conta master quando a proposta é enviada. Se não houver saldo, a criação é recusada com `409 INSUFFICIENT_BALANCE_FOR_SUBACCOUNT_FEE`. No sandbox não há cobrança. > ⚠️ **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" } ```

Lista as subcontas associadas à sua _master account_, com o saldo atual de cada uma. A paginação é por cursor: a primeira página dispensa `nextPageToken`; para as seguintes, envie o `nextPageToken` devolvido na resposta anterior. Sem ele, a API recusa `page` maior que 1. Enquanto `hasMore` for `true`, ainda há páginas.

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