Como funciona o redirectUrl no checkout cripto

O que é o redirectUrl

Você cria um pagamento com um único POST para https://api.qvard.com/api/v1/payment (o cabeçalho x-api-key, o número do pedido como id, o valor como price em dólares americanos). A resposta é 201 com dois campos: id, o identificador do pagamento na Qvard, e redirectUrl, no formato https://my.qvard.com/pay/<id>.

O endereço leva a uma página de pagamento hospedada: uma página mantida pela Qvard, não pelo seu servidor. Você não a constrói, não a hospeda nem a mantém. Sua tarefa é levar o cliente a esse endereço e conhecer depois o resultado pelo webhook.

O que o cliente vê

Na página o cliente:

1. escolhe um ativo e uma rede (ou encontra o que você pré-selecionou com um paymentSystemId);
2. vê o endereço e o valor exato a enviar, com a rede mostrada ao lado do endereço;
3. envia a transferência da própria carteira ou corretora.

A cotação na página fica fixa por uma hora, então o valor não muda enquanto o cliente paga. A página é a mesma não importa a aparência da sua loja, e esse é o ponto: você obtém um checkout cripto funcionando sem construí-lo. Para vê-la antes de integrar, abra uma fatura de demonstração.

Usar o link no checkout

O uso padrão é um redirecionamento no servidor ou um botão, em três passos:

1. O cliente escolhe «Pagar com cripto». Seu servidor cria o seu pedido e o pagamento da Qvard.
2. Seu servidor responde com o redirectUrl, como redirecionamento HTTP ou como um valor que seu front-end usa para navegar.
3. O navegador vai à página; o cliente paga ali.

Crie o pagamento depois de o cliente clicar no botão, não ao montar o carrinho. Nunca envie a chave de API secreta ao navegador: o navegador só recebe o redirectUrl. Um exemplo completo de botão está em botão de pagamento em cripto para sites.

Usar o link fora de um checkout

Como a página fica em um endereço simples, o link também funciona fora de um checkout web:

• Em um e-mail ou PDF de fatura, ao lado dos dados bancários, para que um cliente empresarial possa escolher pagar em cripto (veja pagamentos com stablecoins para faturas B2B).
• Em um chat ou mensagem de suporte, para um pagamento avulso criado à mão com suas próprias ferramentas.
• Atrás de um QR code, se o seu próprio sistema o gera a partir do endereço.

Trate o link como a entrada para aquele único pagamento. Envie-o ao cliente a quem pertence e não o publique. Links de pagamento como produto separado sem código estão em desenvolvimento; hoje você cria o pagamento pela API e compartilha o endereço que ela devolve.

Repetições, novas tentativas e o que acontece depois do pagamento

• O mesmo pedido duas vezes. Enviar o mesmo id para o mesmo método de pagamento devolve o pagamento existente, então um clique duplo ou uma requisição repetida dá o mesmo pagamento e não um segundo.
• Ainda não há URL de retorno. Depois de pagar, o cliente não é enviado de volta ao seu site automaticamente; as URLs de retorno ainda não estão disponíveis. Dê a ele uma página de pedido que mostre o estado real e se atualize enquanto espera.
• O resultado é o webhook. A Qvard chama sua callback URL quando o pagamento está concluído, com o seu id e o estado. Seu endpoint deve responder exatamente HTTP 200 e ser seguro se executar duas vezes. O cliente voltar ao seu site não é prova de pagamento. Veja como proteger webhooks de pagamentos em cripto.

O que o link não faz

Para você não procurar:

• Ele não informa o estado do pagamento; não há rota para ler um pagamento pelo id, então use o webhook e seus registros.
• Ele não traz o cliente de volta ao seu site; as URLs de retorno ainda não estão disponíveis.
• Ele não substitui a sua página de pedido: você ainda precisa de uma que mostre «aguardando», «parcial» ou «pago».

Os formatos de requisição e resposta estão em API de pagamentos em cripto para desenvolvedores, e o fluxo completo em como aceitar pagamentos em cripto em um site.

FAQ