Documentação ValidaPay2

Autentica as credenciais e retorna um token de acesso para uso nas demais rotas da API. # Autenticação M2M (client_credentials) Gera um access token Bearer para chamadas M2M. **Auth:** nenhuma (credenciais no body) | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `grant_type` | ✅ | string | `client_credentials` | | `client_id` | ✅ | string | ID do cliente M2M | | `client_secret` | ✅ | string | Secret do cliente M2M | | `scope` | ✅ | string | Escopos separados por espaço | **Scopes disponíveis:** `pix.cob/read` `pix.cob/write` `wallet/read` `wallet/write` `products/read` `products/write` `proposals/read` `proposals/write` `subscriptions/read` `subscriptions/write` `checkouts/read` `checkouts/write` `customers/read` `customers/write` `subaccounts/read` `coupons/read` `coupons/write` `payment.methods/write`

Envia ou atualiza o formulário de abertura de conta para pessoa física, incluindo dados pessoais e documentos. # Criar/atualizar proposta (Pessoa Física) `documentNumber` com 11 dígitos determina PF. `financialDetails` é obrigatório para finalizar (`status: FINISHED`); sem ele retorna `UNFINISHED`. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `documentNumber` | ✅ | string | CPF 11 dígitos | | `fullName` | ✅ | string | Nome completo | | `phoneNumber` | ✅ | string | E.164 | | `email` | ✅ | string | email válido | | `motherName` | ✅ | string | Nome da mãe | | `birthDate` | ✅ | string | YYYY-MM-DD | | `isPoliticallyExposedPerson` | ✅ | boolean | PEP | | `address.*` | ✅ | object | CEP, logradouro, número, bairro, cidade, UF | | `financialDetails.*` | ✅* | object | renda, profissão, patrimônio (obrig. p/ finalizar) | | `webhookUrl` | ❌ | string | Notificações de onboarding |

Envia ou atualiza o formulário de abertura de conta para pessoa jurídica, incluindo dados da empresa e sócios. # Criar/atualizar proposta (Pessoa Jurídica) `documentNumber` com 14 dígitos determina PJ. Exige ao menos um sócio em `owner[]`. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `documentNumber` | ✅ | string | CNPJ 14 dígitos | | `businessName` | ✅ | string | Razão social | | `tradingName` | ✅ | string | Nome fantasia | | `businessEmail` | ✅ | string | email | | `contactNumber` | ✅ | string | E.164 | | `companyType` | ❌ | string | `PJ` `MEI` `ME` | | `businessAddress` | ✅ | object | Endereço da empresa | | `financialCompanyDetails.declaredCompanyRevenue` | ✅* | string | Faturamento mensal | | `owner[]` | ✅ | array | min 1 sócio | | `owner[].ownerType` | ✅ | string | `REPRESENTANTE` `SOCIO` `DEMAIS SOCIOS` |

Retorna o status e os dados de uma proposta de cadastro específica pelo seu ID. # Consultar proposta `:id` = formId.

Lista todas as subcontas vinculadas à conta principal, com seus dados e status. # Listar subcontas **Auth:** Bearer M2M (master).

Retorna o saldo disponível e a atualizar na carteira da conta autenticada. # Consultar saldo da carteira Retorna o saldo disponível para saque, o saldo pendente (pagamentos ainda sendo processados) e o total da conta. Contas M2M podem consultar o saldo de subcontas passando `accountId`. | Parâmetro | Obrig. | Descrição | |---|---|---| | `accountId` | ❌ | M2M: número da subconta ou lista separada por vírgula |

Lista o extrato de transações da carteira com suporte a filtros por data e paginação. # Listar extrato da carteira Retorna todos os lançamentos financeiros paginados: pagamentos recebidos, PIX enviados e recebidos, saques, repasses, estornos e taxas. Use os filtros para refinar o período ou o tipo de lançamento. | Parâmetro | Obrig. | Descrição | |---|---|---| | `limit` | ❌ | Quantidade por página (padrão 15) | | `lastKey` | ❌ | Token de paginação retornado na resposta anterior | | `startDate` | ❌ | Data inicial (ISO 8601) | | `endDate` | ❌ | Data final (ISO 8601) | | `type` | ❌ | `CREDIT` (entradas) ou `DEBIT` (saídas) | | `category` | ❌ | `PAYMENT` `PIX_IN` `PIX_OUT` `WITHDRAWAL` `SPLIT_IN` `REFUND` `FEE_COLLECTION` | | `accountId` | ❌ | M2M: conta específica |

Adiciona uma anotação interna a uma transação específica para controle próprio. # Anotar transação Grava uma observação livre na transação. Útil para controle interno (conciliação, referência de pedido, etc.). | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `note` | ✅ | string | Texto da anotação (máx. 500 caracteres) | **Erros:** `400 MISSING_NOTE`, `400 INVALID_NOTE`, `404 TRANSACTION_NOT_FOUND`.

Lista os recebimentos futuros previstos, com valor e data estimada de liquidação. # Listar recebimentos Retorna os valores a receber (pagamentos ainda em liquidação) com a data prevista de disponibilização na carteira.

Retorna os recebimentos previstos para um dia específico. # Consultar agenda do dia Retorna o total e o detalhamento dos recebimentos previstos para a data informada em `:day` (formato `YYYY-MM-DD`).

Solicita a transferência do saldo disponível para a conta bancária cadastrada. # Realizar saque via PIX Transfere o valor solicitado do saldo disponível da sua carteira para uma chave PIX de destino. O saldo deve ser suficiente para cobrir o valor mais as taxas aplicáveis. O processamento é realizado em instantes durante o horário bancário. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `amount` | ✅ | number | Valor a sacar em reais (maior que zero) | | `pixKey` | ✅ | string | Chave PIX do destinatário | | `pixKeyType` | ✅ | string | Tipo da chave: `CPF` `CNPJ` `EMAIL` `PHONE` `EVP` | | `documentNumber` | ❌ | string | CPF ou CNPJ do titular da chave destino | | `accountId` | ❌ | string | M2M: número da subconta de origem |

Lista todos os saques solicitados com status, valor e data de cada transferência. # Listar saques Retorna o histórico de saques realizados na conta, com status, valor, chave PIX de destino e data de cada operação. Útil para conciliação e auditoria financeira. | Parâmetro | Obrig. | Descrição | |---|---|---| | `limit` | ❌ | Quantidade por página (padrão 15) | | `lastKey` | ❌ | Token de paginação | | `startDate` | ❌ | Data inicial (ISO 8601) | | `endDate` | ❌ | Data final (ISO 8601) | | `accountId` | ❌ | M2M: conta específica |

Envia um valor diretamente para uma chave Pix, sem precisar de conta bancária cadastrada. # Enviar transferência PIX Realiza uma transferência PIX a partir do saldo da carteira para qualquer conta bancária via chave PIX. Diferente do saque, esta operação permite informar um valor livre sem necessidade de pré-cadastro de destinatário. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `amount` | ✅ | number | Valor da transferência em reais | | `pixKey` | ✅ | string | Chave PIX do destinatário | | `pixKeyType` | ✅ | string | Tipo da chave: `CPF` `CNPJ` `EMAIL` `PHONE` `EVP` | | `description` | ❌ | string | Mensagem/descrição para o destinatário | | `accountId` | ❌ | string | M2M: conta de origem |

Verifica se uma chave Pix é válida e retorna os dados do titular antes de realizar uma transferência. # Consultar chave PIX (DICT) Valida e retorna os dados cadastrados para uma chave PIX no Diretório de Identificadores de Contas Transacionais (DICT) do Banco Central. Use esta rota para confirmar se uma chave existe e exibir o nome do titular ao usuário antes de realizar uma transferência. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `pixKey` | ✅ | string | Chave PIX a ser consultada | | `pixKeyType` | ✅ | string | Tipo da chave: `CPF` `CNPJ` `EMAIL` `PHONE` `EVP` |

Inicia o processo de reembolso de uma cobrança já paga, devolvendo o valor ao meio de pagamento original. # Solicitar reembolso Incia o processo de devolução de um pagamento já confirmado. O valor é debitado do seu saldo disponível e devolvido ao cliente pelo mesmo meio de pagamento (PIX ou cartão). Para PIX, informe o `endToEndId`; para cartão, o `chargeId`. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `endToEndId` | ✅* | string | ID E2E do PIX a ser estornado | | `chargeId` | ✅* | string | ID da cobrança a ser estornada | | `amount` | ✅ | number | Valor a reembolsar em reais (pode ser parcial) | | `reason` | ✅ | string | Motivo: `BANK_ERROR` `FRAUD` `CUSTOMER_REQUEST` `PIX_CHANGE_ERROR` | | `accountId` | ❌ | string | M2M: conta específica | *Pelo menos um dos campos marcados com `✅*` é obrigatório.

Consulta o status de um reembolso já solicitado. # Listar reembolsos Retorna o histórico de reembolsos solicitados, com status de processamento, valor, motivo e cobrança original relacionada. | Parâmetro | Obrig. | Descrição | |---|---|---| | `limit` | ❌ | Quantidade por página (padrão 15) | | `lastKey` | ❌ | Token de paginação | | `startDate` | ❌ | Data inicial (ISO 8601) | | `endDate` | ❌ | Data final (ISO 8601) | | `accountId` | ❌ | M2M: conta específica |

Cadastra um endereço para receber avisos automáticos sempre que algo acontecer na sua conta, como um pagamento confirmado ou cancelado. # Registrar webhook | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `url` | ✅ | string | Endpoint HTTPS | | `events` | ❌ | string[] | Eventos a escutar (vazio = todos) | | `authToken` | ❌ | string | Header de auth enviado nos disparos | **Eventos:** `charge.created` `payment.success` `payment.failed` `payment.overdue` `subscription.created` `subscription.activated` `subscription.canceled` `subscription.renewed` `subscription.trial` `subscription.upgraded` `subscription.item_added` `subscription.downgrade_scheduled` `onboarding.documentscopy` `onboarding.proposal` `onboarding.backgroundcheck` `onboarding.create` `refund.requested` `refund.confirmed` `refund.failed` `med.infraction.updated` `med.balance.blocked` `med.balance.unblocked` `med.refund.opened` `med.refund.closed`

Lista todos os endereços de notificação cadastrados na conta. # Listar webhooks

Retorna os detalhes de um endereço de notificação específico. # Consultar webhook

Atualiza o endereço ou os eventos que disparam a notificação. # Atualizar webhook | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `url` | ❌ | string | Novo endpoint | | `events` | ❌ | string[] | Novos eventos | | `status` | ❌ | string | `active` `inactive` | | `authToken` | ❌ | string | Novo token |

Remove um endereço de notificação da conta. # Deletar webhook

Envia um aviso de teste para o endereço configurado, permitindo validar se as notificações estão chegando corretamente. # Testar webhook (payload fake) Obrigatório `webhookId` ou `url`. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `webhookId` | ✅* | string | ID do webhook registrado | | `url` | ✅* | string | URL alternativa | | `entity` | ✅ | string | Tipo de evento para gerar payload |

Retorna a lista de todos os eventos disponíveis para receber notificações, como pagamento aprovado, assinatura cancelada, entre outros. # Histórico de disparos

Reenvia a notificação de um evento que não foi entregue ou precisa ser processado novamente. # Reenviar disparo `:id` = webhookEventId.

Cria um novo produto ou serviço com nome, descrição, preço e configurações de recorrência. # Criar produto **Scopes:** `products/write` | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `name` | ✅ | string | Nome do produto | | `type` | ❌ | string | `RECURRING` `ONE_TIME` (default RECURRING) | | `statementDescriptor` | ❌ | string | max 22 chars | | `prices[].amount` | ✅ | number | Valor em reais (> 0) | | `prices[].recurrenceType` | ✅ | string | `WEEKLY` `MONTHLY` `QUARTERLY` `SEMIANNUAL` `YEARLY` `ONE_TIME` | | `prices[].recurrenceInterval` | ❌ | number | min 1 (ex: 2 = bimestral) | | `prices[].trialDays` | ❌ | number | ≥ 0 | | `prices[].compareAtPrice` | ❌ | number | Preço "de" |

Lista todos os produtos cadastrados com suporte a filtros por status e paginação. # Listar produtos **Scopes:** `products/read`

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

Atualiza as informações de um produto, como nome, descrição ou preço. # Atualizar produto 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. # Deletar produto

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

Cria um novo cliente com dados pessoais como nome, CPF/CNPJ, e-mail e endereço. # Criar cliente **Scopes:** `customers/write` | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `name` | ✅ | string | Nome completo | | `phone` | ✅ | string | E.164 | | `email` | ❌ | string | email válido | | `document` | ✅ | string | CPF (11) ou CNPJ (14), só dígitos | | `upsert` | ❌ | boolean | Se `true`, retorna existente sem erro |

Lista todos os clientes cadastrados com suporte a busca por nome, documento e paginação. # Listar clientes **Scopes:** `customers/read`

Retorna todos os dados cadastrais de um cliente específico pelo seu ID. # Consultar cliente Retorna `addresses`, `subscriptions` (com ciclos e upgrades), `ltv`.

Atualiza os dados cadastrais de um cliente, como endereço, telefone ou e-mail. # Atualizar cliente | Campo | Obrig. | Tipo | |---|---|---| | `name` | ❌ | string | | `email` | ❌ | string | | `phone` | ❌ | string | | `document` | ❌ | string |

Remove o cadastro de um cliente que não possua cobranças ou assinaturas ativas. # Deletar cliente

Cria um cupom de desconto com valor fixo ou percentual, limite de usos e período de validade. # Criar cupom **Scopes:** `coupons/write` | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `code` | ✅ | string | Código único (case-insensitive), max 50 | | `discountType` | ✅ | string | `PERCENTAGE` `FIXED` | | `discountValue` | ✅ | number | > 0; ≤ 100 se PERCENTAGE | | `maxCycles` | ❌ | number | Ciclos com desconto (null = infinito) | | `maxRedemptions` | ❌ | number | Usos totais (null = ilimitado) | | `minAmount` | ❌ | number | Valor mínimo p/ aplicar | | `maxDiscount` | ❌ | number | Teto de desconto em reais | | `validFrom`/`validUntil` | ❌ | string | ISO 8601 | | `productIds` | ❌ | string[] | Restringe a produtos | | `firstTimeOnly` | ❌ | boolean | Só 1ª compra | | `appliesTo` | ❌ | string | `RECURRING` `ONE_TIME` `ALL` |

Lista todos os cupons cadastrados com informações de uso e validade. # Listar cupons **Scopes:** `coupons/read`

Retorna os detalhes de um cupom específico, incluindo regras de uso e quantidade restante. # Consultar cupom

Atualiza as configurações de um cupom, como validade ou limite de usos. # Atualizar cupom Mesmos campos de POST exceto `code` (todos opcionais).

Atualiza parcialmente um cupom, alterando apenas os campos enviados na requisição. # Alterar status do cupom | Campo | Obrig. | Tipo | Valores | |---|---|---|---| | `status` | ✅ | string | `ACTIVE` `PAUSED` `INACTIVE` |

Remove um cupom, impedindo novos usos sem afetar descontos já aplicados. # Deletar cupom

Verifica se um cupom pode ser usado e retorna o valor do desconto que será aplicado. # Validar cupom (público) **Auth:** nenhuma. `:id` = código do cupom. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `amount` | ❌ | number | Valor para validar contra minAmount | | `productIds` | ❌ | string[] | Produtos do carrinho | | `chargeType` | ❌ | string | `RECURRING` `ONE_TIME` (default RECURRING) | | `customerDocument` | ❌ | string | Para validar firstTimeOnly |

Cria uma cobrança Pix para seu cliente. # Criar cobrança Cria uma cobrança avulsa para o seu cliente. O método de pagamento é definido no campo `paymentMethod` — escolha entre Pix, boleto ou cartão de crédito. **Autenticação:** token de acesso (Bearer). Se você opera como conta principal e quer emitir a cobrança em nome de uma subconta, informe o número dela no cabeçalho `X-Sub-Account`. **Métodos de pagamento disponíveis:** | Método (`paymentMethod`) | Como o cliente paga | |---|---| | `pix` | QR Code / Pix Copia e Cola, com pagamento na hora | | `boleto` | Boleto bancário com data de vencimento | | `creditcard` | Cartão de crédito, à vista ou parcelado | **Campos principais:** | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `paymentMethod` | ✅ | string | Método de pagamento: `pix`, `boleto` ou `creditcard` | | `amount` | ✅ | number | Valor da cobrança, em reais | | `title` | ✅ | string | Título da cobrança (2 a 100 caracteres) | | `description` | ❌ | string | Descrição exibida ao cliente (até 500 caracteres) | | `expiration` | ❌ | string | Prazo máximo de pagamento após o vencimento. Formato: `YYYY-MM-DD` — ex: `"2026-12-31"`. Se omitido: sem expiração. **Deve ser posterior a `dueDate` quando ambos forem informados.** | | `dueDate` | ❌ | string | Data de vencimento do Pix (sem juros até essa data). Formato: `YYYY-MM-DD` — ex: `"2026-12-01"`. Se omitido: hoje + 30 dias. | | `boletoDueDays` | ❌ | number | Prazo do boleto em dias (1 a 60) — alternativa ao `dueDate` | | `customer` | ❌ | object | Dados do cliente (nome, documento, e-mail, telefone) | | `customer.address` | ❌ | object | Endereço do cliente — obrigatório para boleto | | `boletoInstructions.fine` | ❌ | number | Multa por atraso, em % (0.1 a 100) | | `boletoInstructions.interest` | ❌ | number | Juros mensais por atraso, em % | | `boletoInstructions.discount` | ❌ | object | Desconto: `amount`, `modality` (`fixed`/`percent`) e `limitDate` (formato `YYYY-MM-DD`, deve ser anterior ao `dueDate`) | | `card` | ✅* | object | Dados do cartão (número, CVV, nome, validade no formato `MM/YYYY` — ex: `"12/2027"`) — obrigatório para cartão | | `tokenId` | ❌ | string | Token de um cartão já salvo (alternativa a `card`) | | `installments` | ❌ | number | Número de parcelas (1 a 12, padrão 1) | | `passFeesToCustomer` | ❌ | boolean | Repassa as taxas ao cliente | | `freeInstallments` | ❌ | number | Parcelas sem juros (1 a 12, padrão 1) | | `split` | ❌ | array | Divisão do valor entre contas (`type`, `accountNumber`, `amount`) | | `metadata` | ❌ | object | Dados adicionais de sua escolha | | `externalTxid` | ❌ | string | Identificador externo único da cobrança | | `nfConfigId` | ❌ | string | Configuração de nota fiscal a ser usada | > Os campos marcados com `*` são obrigatórios conforme o método de pagamento escolhido. **⚠️ Relação entre `dueDate` e `expiration`:** - `dueDate` = data até a qual o cliente paga sem juros/multa - `expiration` = prazo máximo para pagamento após o vencimento (com juros/multa se configurados) - **Regra:** `expiration` deve ser uma data posterior a `dueDate` - Se `expiration` for omitido, o padrão é `dueDate` + 30 dias Exemplo com ambos os campos: ```json { "paymentMethod": "pix", "amount": 100.0, "title": "Mensalidade Junho", "dueDate": "2026-07-01", "expiration": "2026-07-31" } ``` **Scope OAuth necessário:** `pix.cob/write`

Cria uma cobrança via boleto bancário para seu cliente. # Criar cobrança Cria uma cobrança avulsa para o seu cliente. O método de pagamento é definido no campo `paymentMethod` — escolha entre Pix, boleto ou cartão de crédito. **Autenticação:** token de acesso (Bearer). Se você opera como conta principal e quer emitir a cobrança em nome de uma subconta, informe o número dela no cabeçalho `X-Sub-Account`. **Métodos de pagamento disponíveis:** | Método (`paymentMethod`) | Como o cliente paga | |---|---| | `pix` | QR Code / Pix Copia e Cola, com pagamento na hora | | `boleto` | Boleto bancário com data de vencimento | | `creditcard` | Cartão de crédito, à vista ou parcelado | **Campos principais:** | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `paymentMethod` | ✅ | string | Método de pagamento: `pix`, `boleto` ou `creditcard` | | `amount` | ✅ | number | Valor da cobrança, em reais | | `title` | ✅ | string | Título da cobrança (2 a 100 caracteres) | | `description` | ❌ | string | Descrição exibida ao cliente (até 500 caracteres) | | `dueDate` | ❌ | string | Data de vencimento do boleto. Formato: `YYYY-MM-DD` — ex: `"2026-07-30"`. Se omitido: hoje + 30 dias. | | `boletoDueDays` | ❌ | number | Prazo em dias até o vencimento (1 a 60) — alternativa ao `dueDate` | | `expirationAfterDueDate` | ❌ | number | Dias extras para pagamento após o vencimento (padrão: 30) | | `customer` | ❌ | object | Dados do cliente | | `customer.name` | ❌ | string | Nome completo | | `customer.documentNumber` | ❌ | string | CPF (11 dígitos) ou CNPJ (14 dígitos) | | `customer.email` | ❌ | string | E-mail | | `customer.phone` | ❌ | string | Telefone com DDI (+55...) | | `customer.address` | ✅ | object | **Obrigatório para boleto.** Endereço completo do pagador | | `customer.address.street` | ✅ | string | Logradouro | | `customer.address.number` | ✅ | string | Número | | `customer.address.neighborhood` | ✅ | string | Bairro | | `customer.address.city` | ✅ | string | Cidade | | `customer.address.state` | ✅ | string | UF (2 letras, ex: `"SP"`) | | `customer.address.zipCode` | ✅ | string | CEP (8 dígitos, ex: `"01310100"`) | | `customer.address.complement` | ❌ | string | Complemento | | `boletoInstructions.fine` | ❌ | number | Multa por atraso em % (0.1 a 100) | | `boletoInstructions.interest` | ❌ | number | Juros mensais por atraso em % | | `boletoInstructions.discount.amount` | ❌ | number | Valor do desconto | | `boletoInstructions.discount.modality` | ❌ | string | `"fixed"` (valor fixo) ou `"percent"` (percentual) | | `boletoInstructions.discount.limitDate` | ❌ | string | Data limite para o desconto. Formato: `YYYY-MM-DD` — ex: `"2026-07-28"`. Deve ser anterior ao `dueDate`. | | `split` | ❌ | array | Divisão do valor entre contas (`type`, `accountNumber`, `amount`) | | `metadata` | ❌ | object | Dados adicionais de sua escolha | | `externalTxid` | ❌ | string | Identificador externo único da cobrança | | `nfConfigId` | ❌ | string | Configuração de nota fiscal a ser usada | **⚠️ `customer.address` é obrigatório para boleto.** Sem o endereço completo do pagador a emissão falhará. **Scope OAuth necessário:** `checkouts/write`

Cria uma cobrança via cartão de crédito para seu cliente. # Criar cobrança Cria uma cobrança avulsa para o seu cliente. O método de pagamento é definido no campo `paymentMethod` — escolha entre Pix, boleto ou cartão de crédito. **Autenticação:** token de acesso (Bearer). Se você opera como conta principal e quer emitir a cobrança em nome de uma subconta, informe o número dela no cabeçalho `X-Sub-Account`. **Métodos de pagamento disponíveis:** | Método (`paymentMethod`) | Como o cliente paga | |---|---| | `pix` | QR Code / Pix Copia e Cola, com pagamento na hora | | `boleto` | Boleto bancário com data de vencimento | | `creditcard` | Cartão de crédito, à vista ou parcelado | **Cartão — duas formas de enviar:** - **`paymentMethodId`** (recomendado): ID de um cartão já tokenizado via `/v1/payment-methods/tokenize`. Não trafega dados sensíveis. - **`card`** (dados brutos): o cartão é tokenizado e **salvo** automaticamente no cliente, ficando reutilizável como `paymentMethodId` nas próximas cobranças. > ⚠️ **`customer` é obrigatório quando o cartão é enviado para pagamento** (via `card` ou `paymentMethodId`), pois o cartão é vinculado a um cliente — informe ao menos `customer.documentNumber`. Se você apenas **cria** a cobrança (sem cartão, para capturar depois), `customer` é opcional e o retorno traz `installmentOptions`. **Campos principais:** | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `paymentMethod` | ✅ | string | Método de pagamento: `pix`, `boleto` ou `creditcard` | | `amount` | ✅ | number | Valor da cobrança, em reais | | `title` | ✅ | string | Título da cobrança (2 a 100 caracteres) | | `description` | ❌ | string | Descrição exibida ao cliente (até 500 caracteres) | | `customer` | ✅* | object | Dados do cliente. Obrigatório quando há `card` ou `paymentMethodId`. Campos: `name`, `documentNumber`, `email`, `phone`, `address` | | `paymentMethodId` | ✅* | string | ID de cartão tokenizado. Alternativa a `card`. | | `card` | ✅* | object | Dados brutos do cartão. Alternativa a `paymentMethodId`. Campos: `number` (13-19 dígitos), `cvv` (3-4 dígitos), `name`, `expiration` (`MM/YYYY`) | | `installments` | ❌ | number | Número de parcelas (1 a 12, padrão 1) | | `passFeesToCustomer` | ❌ | boolean | Repassa as taxas ao cliente | | `freeInstallments` | ❌ | number | Parcelas sem juros (1 a 12, padrão 1) | | `split` | ❌ | array | Divisão do valor entre contas (`type`, `accountNumber`, `amount`) | | `metadata` | ❌ | object | Dados adicionais de sua escolha | | `nfConfigId` | ❌ | string | Configuração de nota fiscal a ser usada | > Os campos marcados com `*` são obrigatórios conforme o cenário. Para cobrar cartão, envie `card` **ou** `paymentMethodId` (nunca os dois) e inclua `customer`. **Scope OAuth necessário:** `checkouts/write`

Lista todas as cobranças da conta com filtros por status, método de pagamento e data. # Listar cobranças

Retorna o status atualizado e todos os detalhes de uma cobrança, incluindo se já foi paga. # Consultar cobrança

Cancela uma cobrança que ainda não foi paga, invalidando o Pix ou boleto gerado. # Cancelar cobrança

Guarda uma cobrança do histórico sem cancelá-la, útil para organizar cobranças antigas. # Arquivar cobrança Só cobranças canceladas podem ser arquivadas.

Retorna o arquivo PDF do boleto para enviar ou exibir ao cliente. # PDF do boleto (público) Retorna PDF em base64 com `Content-Type: application/pdf`.

Cria uma página de pagamento configurável com produtos, formas de pagamento aceitas, cupons e aparência personalizada. # Criar payment link (oferta) **Scopes:** `checkouts/write`. Link reutilizável, sem cliente pré-preenchido. Obrigatório `priceId` ou `product`. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `priceId` | ✅* | string | ID do preço | | `product` | ✅* | object | Produto + preços inline (alternativa) | | `allowedPaymentMethods` | ✅ | string[] | `pix` `creditcard` `boleto` | | `successUrl`/`cancelUrl`/`redirectAfterPaymentUrl` | ❌ | string | URLs | | `maxInstallments` | ❌ | number | 1–12 | | `freeInstallments` | ❌ | number | 1–12 (default 1) | | `passFeesToCustomer` | ❌ | boolean | default false | | `primaryColor`/`secondaryColor`/`fontColor` | ❌ | string | hex | | `showProductImage` | ❌ | boolean | default true | | `orderBumps` | ❌ | array | Produtos adicionais |

Lista todas as páginas de pagamento criadas com seus status e configurações. # Listar checkouts

Retorna os detalhes completos de uma página de pagamento, incluindo produtos e formas aceitas. # Consultar checkout Aceita `cha_*` (charge), `cs*` (sessão), `price_*` (preço), `pl*` (payment link). Auth opcional (público).

Atualiza as configurações de uma página de pagamento, como produtos ou formas de pagamento disponíveis. # Atualizar checkout | Campo | Obrig. | Tipo | |---|---|---| | `priceId` | ❌ | string | | `discounts` | ❌ | array | | `trialDays` | ❌ | number | | `maxInstallments` | ❌ | number | | `primaryColor`/`secondaryColor`/`fontColor` | ❌ | string (hex) | | `showProductImage` | ❌ | boolean | | `applyBrandingToAllPrices` | ❌ | boolean |

Este é o endpoint onde o pagamento é de fato processado. O cliente preenche os dados diretamente na sua página e você envia para cá. # Efetuar pagamento via checkout transparente Use esta rota para **concluir uma compra** a partir de uma sessão de checkout já criada. Não precisa de login — qualquer pessoa com o ID da sessão pode pagar. Quando o pagamento é aprovado, a sessão é marcada como paga e não pode ser usada novamente. **Autenticação:** não é necessária. --- ## Identificação da sessão (obrigatório — um dos dois) | Campo | Tipo | Descrição | |---|---|---| | `sessionId` | texto | ID da sessão criada pelo vendedor. Começa com `cs_` (produção) ou `SANDBOX_cs_` (sandbox) | | `checkoutId` | texto | Mesmo que `sessionId` — aceito como alternativa | --- ## Forma de pagamento | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `paymentMethod` | ✅ | texto | Forma de pagamento: `pix`, `creditcard` ou `boleto` | **Cartão de crédito** — preencha `card` OU `tokenId`: | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `card.number` | ✅* | texto | Número do cartão (13 a 19 dígitos, só números) | | `card.cvv` | ✅* | texto | Código de segurança (3 ou 4 dígitos) | | `card.name` | ✅* | texto | Nome exatamente como está no cartão | | `card.expiration` | ✅* | texto | Validade no formato `MM/YYYY` (ex: `12/2027`) | | `paymentMethodId` | ✅* | texto | ID de cartão tokenizado via `/v1/payment-methods/tokenize` — substitui `card` | | `tokenId` | ✅* | texto | Token de cartão salvo em pagamento anterior — substitui `card` | | `cardInfo.brand` | ❌ | texto | Bandeira do cartão tokenizado (ex: `VISA`) | | `cardInfo.maskedNumber` | ❌ | texto | Número mascarado do cartão tokenizado (ex: `411111******1111`) | | `cardInfo.holderName` | ❌ | texto | Nome do titular do cartão tokenizado | | `cardInfo.expiration` | ❌ | texto | Validade do cartão tokenizado (`MM/YYYY`) | *Para cartão, preencha `card` com os dados brutos, **ou** `paymentMethodId` com um cartão tokenizado, **ou** `tokenId` com um token salvo. --- ## Dados do comprador Se a sessão já foi criada com dados do cliente, eles são preenchidos automaticamente. Os campos enviados aqui sobrescrevem os da sessão. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `customer.name` | ✅ | texto | Nome completo do comprador | | `customer.email` | ✅ | texto | E-mail do comprador | | `customer.documentNumber` | ✅ | texto | CPF (11 dígitos) ou CNPJ (14 dígitos), somente números | | `customer.phone` | ❌ | texto | Telefone no formato internacional (ex: `+5511999998888`) | | `customer.cep` | ❌ | texto | CEP com 8 dígitos — necessário para PIX com dados do pagador | | `customer.address.street` | ✅ boleto | texto | Rua ou logradouro | | `customer.address.number` | ✅ boleto | texto | Número da residência | | `customer.address.complement` | ❌ | texto | Complemento (apto, sala, etc.) | | `customer.address.neighborhood` | ✅ boleto | texto | Bairro | | `customer.address.city` | ✅ boleto | texto | Cidade | | `customer.address.state` | ✅ boleto | texto | Estado com 2 letras (ex: `SP`) | | `customer.address.zipCode` | ✅ boleto | texto | CEP com 8 dígitos | | `customer.address.country` | ❌ | texto | País (padrão `BR`) | | `customer.address.cityCode` | ❌ | texto | Código IBGE da cidade — necessário para emissão de nota fiscal | | `customer.metadata` | ❌ | objeto | Informações extras do cliente (chave-valor livre) | *Campos marcados como "✅ boleto" são obrigatórios apenas quando `paymentMethod` é `boleto`. --- ## Produto ou valor Se a sessão já tem produtos configurados, não é necessário enviar. Para alterar ou usar uma cobrança avulsa: | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `items[].priceId` | ✅* | texto | ID do preço do produto (`price_...`) | | `items[].quantity` | ❌ | número | Quantidade (padrão: 1) | | `items[].isOrderBump` | ❌ | sim/não | Marcar como produto adicional (order bump) | | `amount` | ✅* | número | Valor em reais para cobrança avulsa — use quando não há `items` | | `description` | ❌ | texto | Descrição da cobrança avulsa | *Envie `items` com produtos **ou** `amount` com valor avulso — um dos dois é obrigatório. --- ## Parcelamento | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `installments` | ❌ | número | Quantidade de parcelas (1 a 12, padrão 1). Limite por tipo de plano: anual→12, semestral→6, trimestral→3, avulso→12 | | `passFeesToCustomer` | ❌ | sim/não | Repassar as taxas da plataforma para o comprador (padrão: não) | | `freeInstallments` | ❌ | número | Quantidade de parcelas sem juros (0 a 12, padrão 1) | --- ## Recorrência | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `billingDay` | ❌ | número | Dia do mês em que as cobranças recorrentes serão geradas (1 a 31) | | `prorataStartDate` | ❌ | texto | Data de início para cálculo de pró-rata (YYYY-MM-DD) | | `recurrencyStartDate` | ❌ | texto | Data de início da recorrência (YYYY-MM-DD, hoje ou futura) | --- ## Boleto | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `dueDate` | ❌ | texto | Data de vencimento do boleto (YYYY-MM-DD, deve ser maior que hoje) | | `boletoDueDays` | ❌ | número | Dias até o vencimento a partir de hoje (mínimo 1) — calculado automaticamente se `dueDate` for informado | | `expirationAfterDueDate` | ❌ | número | Dias para o boleto ser cancelado após o vencimento (0 a 60) | | `boletoInstructions.fine` | ❌ | número | Multa por atraso em porcentagem (0.1 a 100). A soma de `fine + interest` não pode passar de 60% | | `boletoInstructions.interest` | ❌ | número | Juros mensais por atraso em porcentagem (0.1 a 100) | | `boletoInstructions.discount.amount` | ❌ | número | Valor do desconto para pagamento antecipado | | `boletoInstructions.discount.modality` | ❌ | texto | Tipo do desconto: `fixed` (valor em reais) ou `percent` (porcentagem). Padrão: `fixed` | | `boletoInstructions.discount.limitDate` | ❌ | texto | Data limite para usar o desconto (YYYY-MM-DD, deve ser antes de `dueDate`) | --- ## PIX com dados do pagador | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `expiration` | ❌ | texto | Data de expiração do QR Code PIX (YYYY-MM-DD, não pode ser passada) | --- ## Cupom e descontos | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `couponCode` | ❌ | texto | Código de cupom de desconto | | `discounts` | ❌ | lista | Descontos manuais — sobrescrevem os da sessão. Cada item deve ter `type` (`PERCENTAGE` ou `FIXED`) e `amount` ou `value`. Campos opcionais: `paymentMethod`, `fromCycle`, `toCycle`, `durationMonths` | --- ## Split de pagamento | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `split[].type` | ✅ | texto | Tipo do repasse: `percentage` (porcentagem) ou `fixed` (valor fixo) | | `split[].accountNumber` | ❌ | texto | Número da conta que vai receber o repasse | | `split[].amount` | ✅ | número | Valor ou porcentagem do repasse | --- ## Outros | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `metadata` | ❌ | objeto | Informações extras (chave-valor livre) que ficam salvas na cobrança | | `nfConfigId` | ❌ | texto | ID da configuração de nota fiscal. Quando informado, o endereço do comprador é obrigatório | | `dfp_id` | ❌ | texto | ID de device fingerprint — usado para análise antifraude | --- **Erros comuns:** `404 SESSION_NOT_FOUND` (sessão não existe), `400 SESSION_INACTIVE` (sessão já foi paga ou expirou), `400 INVALID_DATA` (campo inválido), `402` (pagamento recusado pelo banco).

Cria um acesso temporário e seguro a uma página de pagamento, com validade e uso único. # POST /v1/checkout-sessions — Criar Sessão de Checkout **Auth:** Bearer (Cognito) ou M2M (`checkouts/write`) Cria um link de pagamento nominal com cliente e configurações pré-preenchidas. Uso único — expira após o pagamento. ## Resposta ```json { "id": "cs_abc123", "url": "https://app.validapay.com.br/pagamento/cs_abc123", "priceId": "price_abc123" } ``` ## Referência dos campos | Campo | Obrig. | Tipo | Descrição | |-------|--------|------|------------| | `priceId` | ✅ | `string` | Deve começar com `price_`. Deve pertencer à conta autenticada | | `allowedPaymentMethods` | — | `string[]` | Métodos exibidos: `pix` `creditcard` `boleto`. Omitir = usa padrão do price | | `customer.name` | — | `string` | Pré-preenche o nome no checkout | | `customer.email` | — | `string` | Usado para localizar cliente existente pelo `documentNumber` | | `customer.documentNumber` | — | `string` | CPF (11) ou CNPJ (14 dígitos) | | `customer.phone` | — | `string` | Telefone | | `customer.address` | — | `object` | Endereço completo. Obrigatório para boleto no momento do pagamento | | `customer.address.type` | — | `string` | Tipo do endereço (ex: `BILLING`) | | `customer.address.cityCode` | — | `string` | Código IBGE — obrigatório para emissão de nota fiscal | | `items` | — | `array` | Lista de `{ priceId, quantity }`. Sobrescreve o item principal para multi-produto | | `billingDay` | — | `number` | 1–31. Dia do mês para cobranças recorrentes | | `prorataStartDate` | — | `string` | `YYYY-MM-DD`. Data de início para cálculo de prorata | | `installments` | — | `number` | 1–12. Parcelas fixas para a sessão | | `dueDate` | — | `string` | `YYYY-MM-DD` (deve ser maior que hoje). Deriva `boletoDueDays` automaticamente | | `boletoDueDays` | — | `number` | Dias para vencimento do boleto (mín. 1). Ignorado se `dueDate` for informado | | `expirationAfterDueDate` | — | `number` | 0–60. Dias após vencimento que o boleto ainda aceita pagamento | | `discounts` | — | `array` | Descontos aplicados à sessão. Cada item: `{ type, value, paymentMethod?, fromCycle?, toCycle?, durationMonths? }` | | `discounts[].type` | — | `string` | `PERCENTAGE` ou `FIXED` | | `discounts[].value` | — | `number` | Valor do desconto | | `discounts[].paymentMethod` | — | `string` | Restringir a um método: `pix` `creditcard` `boleto` | | `discounts[].fromCycle` | — | `number` | Ciclo inicial de aplicação | | `discounts[].toCycle` | — | `number` | Ciclo final de aplicação | | `discounts[].durationMonths` | — | `number` | Duração em meses | | `passFeesToCustomer` | — | `boolean` | Repassa taxas ao cliente. Default `false` | | `freeInstallments` | — | `number` | 1–12. Parcelas sem juros. Default `1` | | `maxInstallments` | — | `number` | 1–12. Limite máximo de parcelas exibido | | `boletoInstructions.fine` | — | `number` | Multa em % (0.1–100). `fine + interest` ≤ 60% | | `boletoInstructions.interest` | — | `number` | Juros mensais em % (0.1–100) | | `boletoInstructions.discount.amount` | — | `number` | Valor do desconto antecipado | | `boletoInstructions.discount.modality` | — | `string` | `fixed` (R$) ou `percent` (%) | | `boletoInstructions.discount.limitDate` | — | `string` | `YYYY-MM-DD` — deve ser anterior ao `dueDate` | | `orderBumps` | — | `array` | Produtos adicionais exibidos no checkout | | `orderBumps[].priceId` | ✅ | `string` | priceId do produto adicional | | `orderBumps[].callToAction` | — | `string` | Texto do botão de adicionar | | `orderBumps[].title` | — | `string` | Título exibido | | `orderBumps[].description` | — | `string` | Descrição exibida | | `orderBumps[].showImage` | — | `boolean` | Exibir imagem do produto | | `primaryColor` | — | `string` | Cor primária (hex) | | `secondaryColor` | — | `string` | Cor secundária (hex) | | `fontColor` | — | `string` | Cor do texto (hex) | | `companyName` | — | `string` | Nome da empresa exibido no checkout | | `successUrl` | — | `string` | Redireciona após pagamento aprovado | | `failureUrl` | — | `string` | Redireciona após pagamento recusado | | `metadata` | — | `object` | Dados livres persistidos na sessão |

Retorna os dados de um acesso temporário ativo, como produtos disponíveis e formas de pagamento. # Consultar sessão de checkout

Lista todas as assinaturas com filtros por status, cliente e plano. # Listar assinaturas **Scopes:** `subscriptions/read`

Retorna os detalhes completos de uma assinatura, incluindo o ciclo atual, a data da próxima cobrança e o histórico de pagamentos. # Consultar assinatura Retorna `customer`, `items`, `upgrades`, `billingCycles`, `coupon`.

Altera informações de uma assinatura ativa, como o plano contratado ou o dia de cobrança, sem precisar cancelar e recriar. # Atualizar assinatura (genérico) Comportamento depende dos campos enviados. Este request cancela. | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `action` | ❌ | string | `cancel` | | `reason` | ❌ | string | Motivo | | `old.itemId` | ❌ | string | Item a alterar (upgrade/downgrade) | | `new.priceId` | ❌ | string | Novo preço | | `new.quantity` | ❌ | number | Nova quantidade |

Altera informações de um item dentro de uma assinatura ativa. # Atualizar assinatura — upgrade/downgrade de item Ver descrição do request de cancelamento para a tabela de campos.

Cancela uma assinatura, interrompendo todas as cobranças futuras. # Cancelar assinatura | Campo | Obrig. | Tipo | |---|---|---| | `reason` | ❌ | string |

Adiciona um novo produto ou serviço a uma assinatura já existente. # Adicionar item à assinatura | Campo | Obrig. | Tipo | Descrição | |---|---|---|---| | `priceId` | ✅ | string | Preço do item | | `quantity` | ❌ | number | ≥ 1 (default 1) | | `type` | ❌ | string | `RECURRING` `ONE_TIME` (default RECURRING) | | `boletoInstructions` | ❌ | object | Para assinaturas boleto | | `expirationAfterDueDate` | ❌ | number | 0–60 |

Atualiza a quantidade ou o preço de um item dentro de uma assinatura ativa. # Upgrade/downgrade de item `:id` = subscriptionId, `:itemId` = ID do item. Pelo menos `priceId` ou `quantity`. | Campo | Obrig. | Tipo | |---|---|---| | `priceId` | ✅* | string | | `quantity` | ✅* | number | | `boletoInstructions` | ❌ | object | | `expirationAfterDueDate` | ❌ | number |

Gera uma cobrança pelo valor proporcional ao período já utilizado no mês, útil quando o cliente muda de plano no meio do ciclo. # Calcular pró-rata (sem cobrar) | Campo | Obrig. | Tipo | |---|---|---| | `old.priceId` | ✅ | string | | `old.quantity` | ❌ | number | | `new.priceId` | ✅ | string | | `new.quantity` | ❌ | number |