Links de pagamento: guia

O que é um link

Um link de pagamento é um invólucro em torno dos pagamentos. Cada cliente que paga por ele recebe um pagamento próprio, na mesma página de pagamento hospedada de qualquer outro pagamento da Qvard.

Um pagamento é uma fatura com taxa fixa. O link é um ponto de entrada reutilizável que cria esses pagamentos. Um link pode criar muitos pagamentos, mas não substitui o pagamento.

O link tem moeda própria: a que o comprador vê e paga. Cada pagamento fixa sua cotação na criação. As cotações atuais estão na página «Cotações de moedas».

Criar um link no painel

No painel, abra a seção «Links de pagamento» e configure o link. As opções são:

• Valor: fixo, ou informado pelo cliente com mínimo e máximo.
• Limite de pagamentos: sem limite, um único pagamento ou N pagamentos.
• Prazo: 1, 7 ou 30 dias, ou sem prazo.
• E-mail do comprador: não perguntar, opcional ou obrigatório.

Cada link tem o seu próprio endereço: https://qvard.com/l/<slug>. O cliente o abre, escolhe o token e a rede, e depois vê a página de pagamento habitual.

Você pode baixar o link como QR code em PNG, para faturas impressas, recibos e cartazes. O botão «Compartilhar» entrega o link para enviar por qualquer canal.

Um link por cliente pela API

Para saber com certeza quem paga, crie um pagamento para cada cliente pela API, a partir do seu servidor, e envie ao cliente o redirectUrl da resposta. A chave secreta (qvard_sk_…) deve ficar apenas no seu servidor.

Exemplo de solicitação

# Create a payment for one customer
curl -X POST https://api.qvard.com/api/v1/payment \
  -H 'x-api-key: qvard_sk_YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"price":12499.00,"currency":"INR","id":"order-123"}'

# The response contains "data": { "redirectUrl": "https://my.qvard.com/pay/..." }
# Send that redirectUrl to the customer.

// Run on your server only: the secret key must not reach the browser
async function createPaymentLink(orderId, amount) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ price: amount, currency: 'INR', id: orderId })
  });
  if (!res.ok) throw new Error('Qvard API error: ' + res.status);
  const payment = await res.json();
  return payment.data.redirectUrl; // send this link to the customer
}

// Usage inside an async handler: const link = await createPaymentLink('order-123', 10);

A resposta traz o id do pagamento e um redirectUrl, por exemplo https://my.qvard.com/pay/<uuid>. Envie ao cliente o redirectUrl. O id na solicitação é o número do seu pedido.

Nunca coloque a chave secreta (qvard_sk_…) em código executado no navegador nem em um repositório público. Crie os pagamentos somente no servidor.

Venda limitada e link de uso único

Um link de uso único aceita um pagamento, o que combina com uma fatura. Um link com limite de N pagamentos aceita N pagamentos e então para, o que combina com uma oferta limitada, por exemplo 100 vagas.

Status do link

• Ativo: o link aceita pagamentos.
• Desativado: você desligou o link no painel. Ele não aceita pagamentos até ser ligado de novo.
• Expirado: o prazo (1, 7 ou 30 dias) passou.
• Esgotado: o limite de pagamentos foi atingido.

Webhook de pagamentos de um link

Os pagamentos criados a partir de um link usam o mesmo webhook e o mesmo cabeçalho X-Qvard-Signature. O corpo deles tem dois campos extras opcionais: paymentLink, que é o slug do link, e customerEmail, o e-mail informado pelo cliente, se o link o pedia. Os demais pagamentos não têm esses campos.

Como verificar a assinatura do webhook

O que o link não informa

Um link reutilizável não mostra quem pagou. O webhook informa o pagamento, não o comprador.

O campo customerEmail é opcional e não é verificado: o cliente digita e ninguém confere. Se precisar saber quem comprou, crie um pagamento pela API para cada comprador.

Referência da API