Dashboard

Links de pagamento

Criar link de pagamento

Cria uma página de pagamento (payment link) configurável, com produtos, formas de pagamento aceitas, cupons e aparência personalizada. O link é reutilizável e não fica vinculado a um cliente específico.

É obrigatório informar priceId (preço já cadastrado) ou product (produto com preços inline).

Formas de pagamento suportadas: pix, creditcard, boleto e pix_automatico.

Pix Automático está disponível apenas para contas PJ (conta ValidaPay cadastrada com CNPJ) e só é aceito em preços recorrentes (recurrenceType WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY). O cliente autoriza a recorrência uma única vez no aplicativo do banco e as cobranças seguintes são debitadas automaticamente, sem novo QR Code a cada ciclo. Até o banco do pagador confirmar a autorização, 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 criar um link de pagamento reutilizável para uma oferta — definindo cores, parcelamento e order bumps — e compartilhá-lo com vários clientes.

POST/v1/checkouts
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_xxx",
  "product": {
    "name": "Plano Premium",
    "description": "Acesso completo a plataforma",
    "type": "RECURRING",
    "prices": [
      {
        "title": "Mensal",
        "amount": 99.9,
        "recurrenceType": "MONTHLY"
      }
    ]
  },
  "allowedPaymentMethods": [
    "pix",
    "creditcard",
    "boleto",
    "pix_automatico"
  ],
  "successUrl": "https://meusite.com/obrigado",
  "cancelUrl": "https://meusite.com/cancelado",
  "redirectAfterPaymentUrl": "https://meusite.com/redirect",
  "termsOfServiceUrl": "https://meusite.com/termos-de-servico",
  "privacyPolicyUrl": "https://meusite.com/politica-de-privacidade",
  "successMessage": "Obrigado pela compra!",
  "maxInstallments": 12,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "checkoutName": "Oferta Black Friday",
  "primaryColor": "#7C3AED",
  "secondaryColor": "#EDE9FE",
  "fontColor": "#1F2937",
  "showProductImage": true,
  "metadata": {},
  "companyName": "Minha Empresa",
  "description": "Assinatura mensal com acesso completo",
  "showProductImage": true,
  "orderBumps": [
    {
      "priceId": "price_yyy",
      "productId": "prod_bump123",
      "title": "Leve tambem o suporte premium",
      "description": "Atendimento prioritario por mais R$ 49",
      "callToAction": "Adicionar ao pedido",
      "showImage": true
    }
  ],
  "orderBumpLabel": "Oferta especial",
  "orderBumpDisplayMode": "checkbox"
}

Schema

priceIdstringobrigatório
ID do preço já cadastrado (obrigatório priceId OU product)
allowedPaymentMethodsarray[4]obrigatório
Formas de pagamento aceitas: pix, creditcard, boleto, pix_automatico (só conta PJ, em preço recorrente)
Valores aceitos:pixcreditcardboletopix_automatico
productobjectopcional
Cria o produto junto com o link. Alternativa a priceId; informe um dos dois. Aceita os mesmos campos de POST /v1/products, incluindo messageRuler e fiscal
successUrlstringopcional
Redireciona após pagamento aprovado
Regra:uri
cancelUrlstringopcional
Redireciona ao cancelar
Regra:uri
redirectAfterPaymentUrlstringopcional
URL de redirecionamento pós-pagamento
Regra:uri
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
successMessagestringopcional
Mensagem exibida após o pagamento
maxInstallmentsnumberopcional
Limite de parcelas (1 a 12)
Regra:1 a 12
freeInstallmentsnumberopcional
Parcelas sem juros (1 a 12, default 1)
Regra:0 a 12
passFeesToCustomerbooleanopcional
Repassa as taxas ao cliente (default false)
checkoutNamestringopcional
Nome interno do checkout
primaryColorstringopcional
Cor primária em hex
secondaryColorstringopcional
Cor secundária em hex
fontColorstringopcional
Cor do texto em hex
showProductImagebooleanopcional
Mostra a imagem do produto principal (default true)
metadataobjectopcional
Objeto livre, aceita as chaves e valores que você quiser
companyNamestringopcional
Nome da empresa exibido no topo do checkout
descriptionstringopcional
Texto de apoio exibido no checkout
orderBumpsarray[1]opcional
Ofertas adicionais oferecidas antes de finalizar a compra
orderBumpLabelstringopcional
Rótulo exibido acima das ofertas adicionais
orderBumpDisplayModestringopcional
Como as ofertas aparecem no checkout

Headers

Content-Typeopcional
application/json
const url = 'https://sandbox.validapay.com.br/v1/checkouts';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "priceId": "price_xxx",
  "product": {
    "name": "Plano Premium",
    "description": "Acesso completo a plataforma",
    "type": "RECURRING",
    "prices": [
      {
        "title": "Mensal",
        "amount": 99.9,
        "recurrenceType": "MONTHLY"
      }
    ]
  },
  "allowedPaymentMethods": [
    "pix",
    "creditcard",
    "boleto",
    "pix_automatico"
  ],
  "successUrl": "https://meusite.com/obrigado",
  "cancelUrl": "https://meusite.com/cancelado",
  "redirectAfterPaymentUrl": "https://meusite.com/redirect",
  "termsOfServiceUrl": "https://meusite.com/termos-de-servico",
  "privacyPolicyUrl": "https://meusite.com/politica-de-privacidade",
  "successMessage": "Obrigado pela compra!",
  "maxInstallments": 12,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "checkoutName": "Oferta Black Friday",
  "primaryColor": "#7C3AED",
  "secondaryColor": "#EDE9FE",
  "fontColor": "#1F2937",
  "showProductImage": true,
  "metadata": {},
  "companyName": "Minha Empresa",
  "description": "Assinatura mensal com acesso completo",
  "showProductImage": true,
  "orderBumps": [
    {
      "priceId": "price_yyy",
      "productId": "prod_bump123",
      "title": "Leve tambem o suporte premium",
      "description": "Atendimento prioritario por mais R$ 49",
      "callToAction": "Adicionar ao pedido",
      "showImage": true
    }
  ],
  "orderBumpLabel": "Oferta especial",
  "orderBumpDisplayMode": "checkbox"
})
};

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

Response Examples

200200▾
JSON
{
  "id": "pl_xxx",
  "url": "https://app.validapay.com.br/pagamento/pl_xxx",
  "priceId": "price_xxx"
}

← Anterior

Arquivar Produto

Próximo →

Listar links de pagamento