API de pagamentos em cripto para desenvolvedores

A API da Qvard é deliberadamente pequena. Três rotas cobrem todo o ciclo: criar um pagamento, verificar se um método de pagamento está disponível e enviar um saque. Esta referência descreve cada uma como funciona hoje, com os erros que você vai encontrar, e é honesta sobre o que a API não tem, para que você não construa sobre um recurso que não existe.

O que a API cobre

A API pública fica em https://api.qvard.com/api/v1 e tem três rotas:

POST /payment: criar um pagamento e obter o endereço da página de pagamento hospedada.
GET /method/:id/info: verificar se um método de pagamento do seu projeto está pronto para aceitar pagamentos.
POST /payout: enviar um saque para um endereço cripto.

Os resultados chegam por webhook: a Qvard chama uma URL que você salvou no projeto quando um pagamento é concluído. Não há rota para ler um pagamento pelo id, então o webhook é como você descobre o resultado. Todo o resto, como o painel, os saldos e as configurações, é feito na interface web.

Autenticação

Cada requisição leva a chave de API do seu projeto no cabeçalho x-api-key. Não há tokens a renovar nem OAuth. Uma chave ausente ou desconhecida devolve 401 com a mensagem error.wrong.api.key.

Trate a chave como uma senha: mantenha-a no servidor, em uma variável de ambiente ou em um gerenciador de segredos, e nunca em código de front-end ou em um repositório público. Essa mesma chave é a que a Qvard devolve a você no cabeçalho x-api-key do webhook, então um vazamento afeta os dois sentidos.

Criar um pagamento

POST /api/v1/payment recebe um corpo JSON:

id (string, obrigatório): seu próprio identificador do pedido ou da fatura. Ele volta no webhook.
price (número, obrigatório): o valor em dólares americanos. O cliente paga o equivalente no ativo e na rede que escolher.
paymentSystemId (número, opcional): um método de pagamento do seu projeto. Se você o passar, a página de pagamento abre com esse ativo e essa rede selecionados.

A resposta é 201 com dois campos: id, o identificador do pagamento no lado da Qvard, e redirectUrl, o endereço da página de pagamento hospedada, no formato https://my.qvard.com/pay/<id>. Redirecione o cliente para lá, ou coloque o link em um e-mail.

A chamada é idempotente por id e método de pagamento: enviar o mesmo id de novo para o mesmo método devolve o pagamento existente em vez de criar um segundo, então é seguro repetir após um timeout. Note que o código de status é 201, não 200.

curlcreate-payment.sh

curl -X POST https://api.qvard.com/api/v1/payment \
  -H "x-api-key: $QVARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "order-1042", "price": 49.9 }'

# 201 Created
# { "id": "6f1c2d3e-...", "redirectUrl": "https://my.qvard.com/pay/6f1c2d3e-..." }

# 401 { "message": "error.wrong.api.key" }
# 400 { "message": "Error validation", "errors": { "price": "..." } }

Erros

Os erros têm uma forma só, um corpo JSON com uma message:

400: o corpo falhou na validação. A mensagem é Error validation e um objeto errors associa cada campo ao seu primeiro problema, por exemplo um id ausente ou um price que não é número. Um valor abaixo do mínimo do método escolhido é rejeitado da mesma forma.
401: o cabeçalho x-api-key está ausente ou é desconhecido (error.wrong.api.key).
404: na rota de informações do método, um id de método que não existe (error.notfound).

Registre o corpo completo da resposta ao receber um 4xx; a mensagem indica o campo a corrigir. Não repita um 400 ou 401 sem mudar algo, mas repita um timeout ou um 5xx, o que é seguro graças à idempotência acima.

Estados do pagamento e o webhook

Um pagamento tem um de quatro estados: wait (criado, não pago), partial (chegou menos que o valor total), completed (chegou o valor total) e rejected.

O webhook é enviado quando o pagamento está concluído: a Qvard faz um POST para a callback URL do seu projeto com um JSON pequeno contendo o seu id e o status, e coloca a sua chave de API no cabeçalho x-api-key. Seu endpoint deve responder exatamente HTTP 200; qualquer outro status, um timeout ou um redirecionamento conta como entrega falha e é repetido, cinco tentativas no total em cerca de seis minutos. O cabeçalho é de autenticação, não uma assinatura criptográfica, então compare-o com a sua chave em tempo constante. Torne o tratador idempotente, porque uma entrega pode chegar duas vezes.

Os detalhes, com código, estão em como proteger webhooks de pagamentos em cripto, e o fluxo inteiro é percorrido em como aceitar pagamentos em cripto em um site.

Verificar se um método está pronto

GET /api/v1/method/:id/info recebe o id numérico de um método de pagamento do seu projeto e responde 200 com três campos:

server: detalhes sobre o estado do método.
isReady: true quando o método está pronto para aceitar um pagamento.
isActive: true quando o método não está offline, mesmo que ainda esteja se atualizando com a rede.

Use antes de oferecer um ativo e uma rede específicos no seu checkout, por exemplo para ocultar um método temporariamente indisponível. Um id desconhecido devolve 404. É opcional: se você deixa o cliente escolher na página de pagamento, não precisa dele.

Saques

POST /api/v1/payout envia fundos do seu saldo para um endereço cripto. O corpo JSON tem:

id (string, obrigatório): seu próprio identificador do saque, usado para evitar duplicidade em novas tentativas, então enviar o mesmo id duas vezes não paga duas vezes.
price (número, obrigatório): o valor na cripto do método, não em dólares.
methodId (número, obrigatório): o método de pagamento do seu projeto.
address (string, obrigatório): o endereço de destino.
comment (string, opcional).

Uma chamada bem-sucedida devolve 201. Saques movimentam dinheiro de verdade, então teste com um valor pequeno, confira duas vezes o endereço e a rede do método e confirme com a Qvard que os saques pela API estão habilitados para o seu projeto. O saque para conta bancária em moeda fiduciária não está disponível; um saque vai para um endereço cripto e custa apenas a taxa de rede.

O que a API ainda não tem

Para poupar você de procurar:

Nenhum endpoint para buscar um pagamento pelo id, então confie no webhook e nos seus próprios registros.
Nenhuma assinatura do webhook; a autenticação é o cabeçalho x-api-key.
Nenhum sandbox: um ambiente de testes separado está no roadmap, então use pequenos valores reais. Uma fatura de demonstração mostra a página de pagamento sem pagar.
Nenhuma URL de retorno após o pagamento: o cliente volta ao seu site por conta própria.
Nenhum plugin pronto para plataformas de loja, e os links de pagamento estão em desenvolvimento.

Para formatos e exemplos, veja a documentação para desenvolvedores. Para as condições comerciais, a página de preços.

FAQ

Em que moeda defino o preço?

Em dólares americanos. O cliente paga o equivalente no ativo e na rede que escolher na página de pagamento, a uma cotação fixa por uma hora. O saque é a exceção: seu valor é na cripto do método.

É seguro repetir a criação de um pagamento?

Sim. Enviar o mesmo id para o mesmo método de pagamento devolve o pagamento existente, então repetir após um timeout não cria duplicata.

Como descubro o resultado de um pagamento?

Pelo webhook, enviado quando o pagamento é concluído. Não há rota para ler um pagamento pelo id, então guarde o id que você envia e faça o casamento quando o webhook chegar.

Existe sandbox?

Ainda não. Um ambiente de testes separado está planejado. Por ora use pequenos valores reais e uma fatura de demonstração para ver a página de pagamento.