Checkouts

Criar Sessão de Checkout

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

Autenticação

bearerAuthorizationstring · header · obrigatório

Envie no header:

Authorization: Bearer {{token}}

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

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

Referência dos campos

CampoObrig.TipoDescrição
priceId✅stringDeve começar com price_. Deve pertencer à conta autenticada
allowedPaymentMethods—string[]Métodos exibidos: pix creditcard boleto. Omitir = usa padrão do price
customer.name—stringPré-preenche o nome no checkout
customer.email—stringUsado para localizar cliente existente pelo documentNumber
customer.documentNumber—stringCPF (11) ou CNPJ (14 dígitos)
customer.phone—stringTelefone
customer.address—objectEndereço completo. Obrigatório para boleto no momento do pagamento
customer.address.type—stringTipo do endereço (ex: BILLING)
customer.address.cityCode—stringCódigo IBGE — obrigatório para emissão de nota fiscal
items—arrayLista de { priceId, quantity }. Sobrescreve o item principal para multi-produto
billingDay—number1–31. Dia do mês para cobranças recorrentes
prorataStartDate—stringYYYY-MM-DD. Data de início para cálculo de prorata
installments—number1–12. Parcelas fixas para a sessão
dueDate—stringYYYY-MM-DD (deve ser maior que hoje). Deriva boletoDueDays automaticamente
boletoDueDays—numberDias para vencimento do boleto (mín. 1). Ignorado se dueDate for informado
expirationAfterDueDate—number0–60. Dias após vencimento que o boleto ainda aceita pagamento
discounts—arrayDescontos aplicados à sessão. Cada item: { type, value, paymentMethod?, fromCycle?, toCycle?, durationMonths? }
discounts[].type—stringPERCENTAGE ou FIXED
discounts[].value—numberValor do desconto
discounts[].paymentMethod—stringRestringir a um método: pix creditcard boleto
discounts[].fromCycle—numberCiclo inicial de aplicação
discounts[].toCycle—numberCiclo final de aplicação
discounts[].durationMonths—numberDuração em meses
passFeesToCustomer—booleanRepassa taxas ao cliente. Default false
freeInstallments—number1–12. Parcelas sem juros. Default 1
maxInstallments—number1–12. Limite máximo de parcelas exibido
boletoInstructions.fine—numberMulta em % (0.1–100). fine + interest ≤ 60%
boletoInstructions.interest—numberJuros mensais em % (0.1–100)
boletoInstructions.discount.amount—numberValor do desconto antecipado
boletoInstructions.discount.modality—stringfixed (R$) ou percent (%)
boletoInstructions.discount.limitDate—stringYYYY-MM-DD — deve ser anterior ao dueDate
orderBumps—arrayProdutos adicionais exibidos no checkout
orderBumps[].priceId✅stringpriceId do produto adicional
orderBumps[].callToAction—stringTexto do botão de adicionar
orderBumps[].title—stringTítulo exibido
orderBumps[].description—stringDescrição exibida
orderBumps[].showImage—booleanExibir imagem do produto
primaryColor—stringCor primária (hex)
secondaryColor—stringCor secundária (hex)
fontColor—stringCor do texto (hex)
companyName—stringNome da empresa exibido no checkout
successUrl—stringRedireciona após pagamento aprovado
failureUrl—stringRedireciona após pagamento recusado
metadata—objectDados livres persistidos na sessão

Body

application/json

Content-Type:application/json
{
  "priceId": "price_abc123",

  "allowedPaymentMethods": ["pix", "creditcard", "boleto"],

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

  "metadata": { "referencia": "pedido-001" }
}

Schema

FieldTypeRequiredDescription
priceId
string-
-
allowedPaymentMethods[3]
array-
-
customer
object-
-
items[1]
array-
-
billingDay
number-
-
prorataStartDate
string-
-
installments
number-
-
dueDate
string-
-
boletoDueDays
number-
-
expirationAfterDueDate
number-
-
discounts[1]
array-
-
passFeesToCustomer
boolean-
-
freeInstallments
number-
-
maxInstallments
number-
-
boletoInstructions
object-
-
orderBumps[1]
array-
-
primaryColor
string-
-
secondaryColor
string-
-
fontColor
string-
-
companyName
string-
-
successUrl
string-
-
failureUrl
string-
-
metadata
object-
-

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"],

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

  "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
{
  "code": "FORBIDDEN",
  "message": "Você não tem permissão para usar este produto"
}
404404
{
  "code": "PRICE_NOT_FOUND"
}

← Anterior

Checkout Transparente

Próximo →

Buscar Sessão de Checkout