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.

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

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.

Pagamento internacional (internationalEnabled): com internationalEnabled: true, o checkout passa a aceitar compradores de fora do Brasil. Ele detecta o país do visitante (com seletor para trocar), traduz a página para o idioma do país e mostra o valor aproximado na moeda local; a cobrança continua sendo em reais. Para comprador estrangeiro, o checkout aceita somente cartão de crédito à vista, sem documento e com endereço internacional completo. Comprador brasileiro continua vendo o checkout de sempre. Inclua creditcard em allowedPaymentMethods, senão o comprador estrangeiro não tem como pagar.

A função precisa ser habilitada na sua conta: entre em contato com o suporte da ValidaPay para solicitar a habilitação. Sem ela, enviar internationalEnabled: true retorna 403 INTERNATIONAL_CHECKOUT_NOT_ENABLED e a sessão não é criada. Regras completas do comprador estrangeiro em Gerar cobrança Cartão internacional.

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.

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",
  "redirectAfterPaymentUrl": "https://meusite.com/obrigado",
  "internationalEnabled": true,
  "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
redirectAfterPaymentUrlstringopcional
Redireciona sozinho para esta URL alguns segundos após o pagamento ser confirmado no checkout
Regra:uri
internationalEnabledbooleanopcional
Aceita pagamento de compradores de fora do Brasil (default false). Exige a habilitação do pagamento internacional na conta: entre em contato com o suporte da ValidaPay para solicitar. Sem ela, true retorna 403 INTERNATIONAL_CHECKOUT_NOT_ENABLED
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
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",
  "redirectAfterPaymentUrl": "https://meusite.com/obrigado",
  "internationalEnabled": true,
  "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

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