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 obrigatório

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

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,
  "paymentMethod": "pix",
  "subscriptionAllowedPaymentMethods": ["pix", "creditcard"],
  "createPendingSubscription": false,
  "applyBrandingToAllPrices": false,
  "mergeWithNextCycle": false,
  "prorataDueDate": "2026-09-20",
  "pixInstructions": {
    "discount": {
      "amount": 10.0,
      "modality": "fixed",
      "daysBeforeDue": 3
    }
  },
  "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

priceIdstringobrigatório

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

allowedPaymentMethodsarray[4]opcional

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

Valores aceitos:pixcreditcardboletopix_automatico

customerobjectopcional

Pré-preenche os dados do cliente no checkout

itemsarray[1]opcional

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

billingDaynumberopcional

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

Regra:1 a 31

prorataStartDatestringopcional

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

installmentsnumberopcional

Parcelas fixas da sessão (1 a 12)

Regra:1 a 12

dueDatestringopcional

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

Regra:^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

boletoDueDaysnumberopcional

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

Regra:1

expirationAfterDueDatenumberopcional

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

Regra:0 a 60

discountsarray[1]opcional

Descontos aplicados à sessão

passFeesToCustomerbooleanopcional

Repassa as taxas ao cliente (default false)

freeInstallmentsnumberopcional

Parcelas sem juros (1 a 12, default 1)

Regra:0 a 12

maxInstallmentsnumberopcional

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

Regra:1 a 12

paymentMethodstringopcional

Meio de pagamento já escolhido, quando a sessão nasce definida

Valores aceitos:pixcreditcardboletopix_automatico

subscriptionAllowedPaymentMethodsarray[2]opcional

Meios aceitos nas renovações da assinatura

Valores aceitos:pixcreditcardboletopix_automatico

createPendingSubscriptionbooleanopcional

Cria a assinatura como pendente antes do primeiro pagamento

applyBrandingToAllPricesbooleanopcional

Repete a identidade visual em todos os preços da sessão

mergeWithNextCyclebooleanopcional

Junta a cobrança pro rata com o próximo ciclo em vez de cobrar agora

prorataDueDatestringopcional

Vencimento da cobrança pro rata (YYYY-MM-DD)

Regra:^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

pixInstructionsobjectopcional

Desconto por antecipação no Pix com vencimento

boletoInstructionsobjectopcional

Regras de multa/juros/desconto do boleto

orderBumpsarray[1]opcional

Produtos adicionais exibidos no checkout

primaryColorstringopcional

Cor primária em hex

secondaryColorstringopcional

Cor secundária em hex

fontColorstringopcional

Cor do texto em hex

companyNamestringopcional

Nome da empresa exibido no checkout

successUrlstringopcional

Redireciona após pagamento aprovado

Regra:uri

failureUrlstringopcional

Redireciona após pagamento recusado

termsOfServiceUrlstringopcional

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

Regra:uri

privacyPolicyUrlstringopcional

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

Regra:uri

metadataobjectopcional

Objeto livre, aceita as chaves e valores que você quiser ("referência" é só exemplo); persistido na sessão

Headers

Content-Typeopcional

application/json

← Anterior

Atualizar link de pagamento

Buscar sessão de pagamento

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,
  "paymentMethod": "pix",
  "subscriptionAllowedPaymentMethods": ["pix", "creditcard"],
  "createPendingSubscription": false,
  "applyBrandingToAllPrices": false,
  "mergeWithNextCycle": false,
  "prorataDueDate": "2026-09-20",
  "pixInstructions": {
    "discount": {
      "amount": 10.0,
      "modality": "fixed",
      "daysBeforeDue": 3
    }
  },
  "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▾

JSON

{
  "id": "cs_abc123",
  "url": "https://app.validapay.com.br/pagamento/cs_abc123",
  "priceId": "price_abc123"
}

400400▾

JSON

{
  "error": {
    "code": "INVALID_DATA",
    "message": "Campo inválido",
    "details": []
  }
}

401401▾

JSON

{
    "error": {
        "message": "Você não tem permissão para usar este produto",
        "code": "FORBIDDEN",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

404404▾

JSON

{
    "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

Buscar sessão de pagamento