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.
/v1/checkout-sessionshttps://api.validapay.com.brhttps://sandbox.validapay.com.brInforme 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
Authorization
string obrigatório
Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.
Escopos requeridos
Body
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,
"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órioallowedPaymentMethodsarray[4]opcionalpixcreditcardboletopix_automaticocustomerobjectopcionalitemsarray[1]opcionalbillingDaynumberopcional1 a 31prorataStartDatestringopcionalinstallmentsnumberopcional1 a 12dueDatestringopcional^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$boletoDueDaysnumberopcional1expirationAfterDueDatenumberopcional0 a 60discountsarray[1]opcionalpassFeesToCustomerbooleanopcionalfreeInstallmentsnumberopcional0 a 12maxInstallmentsnumberopcional1 a 12paymentMethodstringopcionalpixcreditcardboletopix_automaticosubscriptionAllowedPaymentMethodsarray[2]opcionalpixcreditcardboletopix_automaticocreatePendingSubscriptionbooleanopcionalapplyBrandingToAllPricesbooleanopcionalmergeWithNextCyclebooleanopcionalprorataDueDatestringopcional^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$pixInstructionsobjectopcionalboletoInstructionsobjectopcionalorderBumpsarray[1]opcionalprimaryColorstringopcionalsecondaryColorstringopcionalfontColorstringopcionalcompanyNamestringopcionalsuccessUrlstringopcionalurifailureUrlstringopcionalredirectAfterPaymentUrlstringopcionaluriinternationalEnabledbooleanopcionaltermsOfServiceUrlstringopcionaluriprivacyPolicyUrlstringopcionalurimetadataobjectopcionalHeaders
Content-Typeopcionalconst 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▾
{
"id": "cs_abc123",
"url": "https://app.validapay.com.br/pagamento/cs_abc123",
"priceId": "price_abc123"
}400INVALID_DATA▾
{
"error": {
"code": "INVALID_DATA",
"message": "Campo inválido",
"details": []
}
}400PRICE_INACTIVE▾
{
"error": {
"code": "PRICE_INACTIVE",
"message": "Preço está inativo",
"details": null,
"timestamp": "2026-07-14T21:39:36.322Z"
}
}401▾
{
"error": {
"message": "Você não tem permissão para usar este produto",
"code": "FORBIDDEN",
"details": null,
"timestamp": "2026-07-14T21:39:36.322Z"
}
}404▾
{
"error": {
"message": "Preço não encontrado",
"code": "PRICE_NOT_FOUND",
"details": null,
"timestamp": "2026-07-14T21:39:36.322Z"
}
}