Links de pagamento e checkout

Uma URL pública que cobra por você: como criar links, como o checkout funciona e onde entram cupom e produto.

Esta página é para quem quer cobrar sem integrar: cria um link, manda ao cliente e pronto. Também explica o que acontece do lado público, que é o mesmo caminho usado pelo checkout de qualquer cobrança.

Link de pagamento

POST /payment-links (ou Links de pagamento no painel) cria uma URL reutilizável:

curl -X POST https://v4pay-api.vercel.app/payment-links \
  -H "Authorization: Bearer v4pay_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 49.9, "description": "Consultoria avulsa" }'

• amount obrigatório, em reais, mínimo R$ 5,00 (400 com codigo: VALOR_MINIMO);
• product_id opcional vincula um produto do seu catálogo;
• a resposta traz o slug — a página pública é https://pay.v4companyamaral.com/pay/{slug};
• o link é do ambiente em que foi criado: link de teste abre um checkout de teste, e a cobrança emitida nasce no ambiente do link, sempre.

Cada pagamento pelo link gera uma cobrança nova — o link continua valendo até você desativá-lo (PUT /payment-links/{id} com active: false).

O checkout público

O pagador não tem conta, então as rotas de checkout não exigem credencial:

O que a página faz	Rota
Carrega os dados do link	GET /checkout/link/{slug}
Valida um cupom digitado	GET /checkout/link/{slug}/coupon?code=…
Emite a cobrança com os dados do pagador	POST /checkout/link/{slug}/pay
Acompanha uma cobrança (QR, status)	GET /checkout/{txid}
Simula o pagamento (só em teste)	POST /checkout/{txid}/simular-pagamento

O POST …/pay exige nome, e-mail e CPF ou CNPJ válido do pagador (dígitos verificadores conferidos) e tem limite de 10 emissões por IP a cada 10 minutos — é uma rota aberta na internet.

Se o dono do link ainda não passou pela aprovação de produção, o pagador vê apenas 409 com codigo: LINK_INDISPONIVEL (“Este link de pagamento está temporariamente indisponível.”). A situação cadastral do lojista nunca é exposta a quem paga.

Cupom no checkout

Cupons criados em POST /coupons valem no checkout: o pagador digita o código, a página valida em GET /checkout/link/{slug}/coupon e o desconto é recalculado no servidor na emissão — o valor final nunca vem do navegador. Cupom que deixaria o total abaixo de R$ 5,00 é recusado (VALOR_MINIMO).

Cobrança por produto

O caminho inverso do link: em vez de uma URL pública, a sua integração emite direto por POST /pix com product_id — o preço vem do catálogo, com cupom e URLs de retorno (success_url / cancel_url). Os detalhes estão em Cobranças.