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 · header · required

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
{
  "priceId": "price_xxx",
  "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": {},
  "orderBumps": [
    {
      "priceId": "price_yyy",
      "label": "Adicionar suporte premium",
      "displayMode": "checkbox"
    }
  ]
}

Schema

priceIdstringRequired

ID do preço já cadastrado (obrigatório priceId OU product)

allowedPaymentMethods[4]arrayRequired
Valores aceitos:pixcreditcardboletopix_automatico

Formas de pagamento aceitas: pix, creditcard, boleto, pix_automatico (só conta PJ, em preço recorrente)

successUrlstringOptional

Redireciona após pagamento aprovado

cancelUrlstringOptional

Redireciona ao cancelar

redirectAfterPaymentUrlstringOptional

URL de redirecionamento pós-pagamento

termsOfServiceUrlstringOptional

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

privacyPolicyUrlstringOptional

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

successMessagestringOptional

Mensagem exibida após o pagamento

maxInstallmentsnumberOptional

Limite de parcelas (1 a 12)

freeInstallmentsnumberOptional
Regra:0 a 12

Parcelas sem juros (1 a 12, default 1)

passFeesToCustomerbooleanOptional

Repassa as taxas ao cliente (default false)

checkoutNamestringOptional

Nome interno do checkout

primaryColorstringOptional

Cor primária em hex

secondaryColorstringOptional

Cor secundária em hex

fontColorstringOptional

Cor do texto em hex

showProductImagebooleanOptional

Exibir imagem do produto (default true)

metadataobject
orderBumps[1]arrayOptional

Produtos adicionais oferecidos no checkout

Headers

NameTypeValueRequired
Content-Type-application/jsonOptional
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",
  "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": {},
  "orderBumps": [
    {
      "priceId": "price_yyy",
      "label": "Adicionar suporte premium",
      "displayMode": "checkbox"
    }
  ]
})
};

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

Response Examples

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

← Anterior

Arquivar Produto

Próximo →

Listar links de pagamento