Links de pagamento

Criar sessão de pagamento

Cria um acesso temporário e seguro a uma página de pagamento, com cliente e configurações pré-preenchidos. É de uso único: expira após o pagamento.

Informe o priceId de um preço já cadastrado. Opcionalmente, envie os dados do cliente, restrinja as formas de pagamento e personalize a aparência.

A resposta inclui o id da sessão e a url de pagamento hospedada pela ValidaPay.

Formas de pagamento aceitas em allowedPaymentMethods: pix, creditcard, boleto e pix_automatico. O Pix Automático está disponível apenas para contas PJ (conta ValidaPay cadastrada com CNPJ) e exige um preço recorrente (recurrenceType WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY): o cliente autoriza a recorrência uma única vez no aplicativo do banco e os ciclos seguintes são debitados automaticamente. Enquanto a autorização não é confirmada pelo banco do pagador, a assinatura fica com status PENDING. O valor mínimo por cobrança é de R$ 4,99.

Erros: 400 PIX_AUTOMATICO_PJ_ONLY (conta PF) e 400 PIX_AUTOMATICO_MIN_AMOUNT (valor abaixo do mínimo).

Ao informar termsOfServiceUrl e/ou privacyPolicyUrl, o checkout exibe um aceite obrigatório com os links: o cliente só consegue finalizar a compra depois de marcar que leu e concorda. O texto do aceite se adapta a um ou aos dois links. Sem esses campos, nenhum aceite é exibido.

Case de uso:

Como SaaS, quero gerar um link de pagamento nominal para cada cliente no momento da contratação, com uso único para evitar cobranças duplicadas.

POST/v1/checkout-sessions
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string · header · required

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

checkouts/write

Body

application/json

Content-Type:application/json
{
  "priceId": "price_abc123",
  "allowedPaymentMethods": [
    "pix",
    "creditcard",
    "boleto",
    "pix_automatico"
  ],
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "51999999999",
    "address": {
      "type": "BILLING",
      "street": "Rua das Flores",
      "number": "123",
      "complement": "Apto 4",
      "neighborhood": "Centro",
      "city": "Porto Alegre",
      "state": "RS",
      "zipCode": "90010000",
      "country": "BR",
      "cityCode": "4314902"
    }
  },
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "billingDay": 15,
  "prorataStartDate": "2026-06-11",
  "installments": 1,
  "dueDate": "2026-07-30",
  "boletoDueDays": 7,
  "expirationAfterDueDate": 30,
  "discounts": [
    {
      "type": "PERCENTAGE",
      "value": 10,
      "paymentMethod": "pix",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "maxInstallments": 12,
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0,
    "discount": {
      "amount": 10.00,
      "modality": "fixed",
      "limitDate": "2026-07-28"
    }
  },
  "orderBumps": [
    {
      "priceId": "price_bump123",
      "callToAction": "Adicionar ao pedido",
      "title": "Produto adicional",
      "description": "Descrição do order bump",
      "showImage": true
    }
  ],
  "primaryColor": "#6366f1",
  "secondaryColor": "#818cf8",
  "fontColor": "#ffffff",
  "companyName": "Minha Empresa",
  "successUrl": "https://meusite.com/sucesso",
  "failureUrl": "https://meusite.com/falha",
  "termsOfServiceUrl": "https://meusite.com/termos-de-servico",
  "privacyPolicyUrl": "https://meusite.com/politica-de-privacidade",
  "metadata": { "referencia": "pedido-001" }
}

Schema

priceIdstringRequired

Preço da sessão (deve começar com price_)

allowedPaymentMethods[4]arrayOptional
Valores aceitos:pixcreditcardboletopix_automatico

Métodos exibidos: pix, creditcard, boleto, pix_automatico (só conta PJ; omitir usa o padrão do price)

customerobjectOptional

Pré-preenche os dados do cliente no checkout

items[1]arrayOptional

Lista de { priceId, quantity } (sobrescreve o item principal)

billingDaynumberOptional
Regra:1 a 31

Dia do mês das cobranças recorrentes (1 a 31)

prorataStartDatestringOptional

Início do cálculo de pró-rata (YYYY-MM-DD)

installmentsnumberOptional
Regra:1 a 12

Parcelas fixas da sessão (1 a 12)

dueDatestringOptional
Regra:^\d{4}-\d{2}-\d{2}$

Vencimento do boleto (YYYY-MM-DD, maior que hoje)

boletoDueDaysnumberOptional
Regra:1

Dias até o vencimento (mín. 1; ignorado se dueDate informado)

expirationAfterDueDatenumberOptional
Regra:0 a 60

Dias após o vencimento que o boleto aceita pagamento (0 a 60)

discounts[1]arrayOptional

Descontos aplicados à sessão

passFeesToCustomerbooleanOptional

Repassa as taxas ao cliente (default false)

freeInstallmentsnumberOptional
Regra:0 a 12

Parcelas sem juros (1 a 12, default 1)

maxInstallmentsnumberOptional

Limite máximo de parcelas exibido (1 a 12)

boletoInstructionsobjectOptional

Regras de multa/juros/desconto do boleto

orderBumps[1]arrayOptional

Produtos adicionais exibidos no checkout

primaryColorstringOptional

Cor primária em hex

secondaryColorstringOptional

Cor secundária em hex

fontColorstringOptional

Cor do texto em hex

companyNamestringOptional

Nome da empresa exibido no checkout

successUrlstringOptional

Redireciona após pagamento aprovado

failureUrlstringOptional

Redireciona após pagamento recusado

termsOfServiceUrlstringOptional

Termos de serviço exibidos no checkout para aceite do cliente

privacyPolicyUrlstringOptional

Política de privacidade exibida no checkout para aceite do cliente

metadataobject

Headers

NameTypeValueRequired
Content-Type-application/jsonOptional
const url = 'https://sandbox.validapay.com.br/v1/checkout-sessions';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "priceId": "price_abc123",
  "allowedPaymentMethods": [
    "pix",
    "creditcard",
    "boleto",
    "pix_automatico"
  ],
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "documentNumber": "12345678901",
    "phone": "51999999999",
    "address": {
      "type": "BILLING",
      "street": "Rua das Flores",
      "number": "123",
      "complement": "Apto 4",
      "neighborhood": "Centro",
      "city": "Porto Alegre",
      "state": "RS",
      "zipCode": "90010000",
      "country": "BR",
      "cityCode": "4314902"
    }
  },
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "billingDay": 15,
  "prorataStartDate": "2026-06-11",
  "installments": 1,
  "dueDate": "2026-07-30",
  "boletoDueDays": 7,
  "expirationAfterDueDate": 30,
  "discounts": [
    {
      "type": "PERCENTAGE",
      "value": 10,
      "paymentMethod": "pix",
      "fromCycle": 1,
      "toCycle": 3,
      "durationMonths": 3
    }
  ],
  "passFeesToCustomer": false,
  "freeInstallments": 1,
  "maxInstallments": 12,
  "boletoInstructions": {
    "fine": 2.0,
    "interest": 1.0,
    "discount": {
      "amount": 10.00,
      "modality": "fixed",
      "limitDate": "2026-07-28"
    }
  },
  "orderBumps": [
    {
      "priceId": "price_bump123",
      "callToAction": "Adicionar ao pedido",
      "title": "Produto adicional",
      "description": "Descrição do order bump",
      "showImage": true
    }
  ],
  "primaryColor": "#6366f1",
  "secondaryColor": "#818cf8",
  "fontColor": "#ffffff",
  "companyName": "Minha Empresa",
  "successUrl": "https://meusite.com/sucesso",
  "failureUrl": "https://meusite.com/falha",
  "termsOfServiceUrl": "https://meusite.com/termos-de-servico",
  "privacyPolicyUrl": "https://meusite.com/politica-de-privacidade",
  "metadata": { "referencia": "pedido-001" }
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200200
{
  "id": "cs_abc123",
  "url": "https://app.validapay.com.br/pagamento/cs_abc123",
  "priceId": "price_abc123"
}
400400
{
  "error": {
    "code": "INVALID_DATA",
    "message": "Campo inválido",
    "details": []
  }
}
401401
{
    "error": {
        "message": "Você não tem permissão para usar este produto",
        "code": "FORBIDDEN",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
404404
{
    "error": {
        "message": "Preço não encontrado",
        "code": "PRICE_NOT_FOUND",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Atualizar link de pagamento

Próximo →

Buscar sessão de pagamento