API da Kuaryx

Crie cobranças em XRP pela sua loja virtual. O cliente paga e o valor vai direto para a sua carteira na XRP Ledger. A Kuaryx avisa a sua loja por webhook assim que o pagamento é validado no ledger.

Só XRP, sem custódia. A Kuaryx não guarda dinheiro, não faz saque, não converte moeda. O valor em reais serve só para calcular quanto XRP cobrar.

Início rápido

Endereço base: https://api.kuaryx.com. Toda chamada leva a sua chave no cabeçalho X-Api-Key.

curl https://api.kuaryx.com/api/charges \
  -H "X-Api-Key: $KUARYX_KEY" \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_brl": "149.90",
    "description": "Pedido #1042",
    "external_reference": "1042",
    "customer_email": "[email protected]",
    "metadata": { "order_id": "1042" },
    "success_url": "https://sualoja.com.br/obrigado",
    "cancel_url": "https://sualoja.com.br/carrinho"
  }'

A resposta traz checkout_url. Mande o cliente para lá. Quando o pagamento for validado, sua loja recebe o webhook charge.paid e o cliente volta para o success_url.

Chaves e modo teste

Cada lojista tem duas chaves:

Na tela de pagamento de uma cobrança de teste aparece o botão Simular pagamento. Pela API, use:

curl -X POST https://api.kuaryx.com/api/charges/{id}/simulate-payment \
  -H "X-Api-Key: $KUARYX_TEST_KEY"

A cobrança fica paid e o seu webhook recebe charge.paid com "livemode": false, igual ao fluxo real. Cada chave só enxerga as cobranças do próprio modo. Guarde as chaves no servidor, nunca no navegador ou no app.

Criar cobrança

POST/api/charges

CampoTipoDescrição
amount_brltexto decimalObrigatório. Valor em reais; a Kuaryx converte para XRP pela cotação do momento (Binance conferida com CoinGecko).
descriptiontextoAparece para o cliente no checkout.
external_referencetexto até 255O id do pedido na sua loja. Dá para filtrar a lista por ele.
expires_in_minutes1 a 1440Prazo para pagar. Padrão: 15 minutos.
metadataobjetoAté 20 chaves suas (texto até 40, valores simples até 500). Volta na API e nos webhooks.
customer_emaile-mailE-mail do comprador, para a sua conciliação.
success_urlURL http(s)Para onde o checkout leva o cliente depois do pagamento, com ?kuaryx_charge_id=... no fim.
cancel_urlURL http(s)Link "Voltar para a loja" no checkout.

Idempotência

Envie o cabeçalho Idempotency-Key (por exemplo, o id do pedido). Se a mesma chave chegar de novo, a API devolve a cobrança criada da primeira vez em vez de criar outra. Isso evita cobrança em dobro quando a rede falha no meio da chamada.

Resposta

{
  "id": "a48a66cf-69c5-41b9-85b9-e0b770fa9126",
  "status": "pending",
  "livemode": true,
  "amount_brl": "149.90",
  "expected_drops": 25843104,
  "rate_brl_per_xrp": "5.800400",
  "xrpl_address": "r...",
  "destination_tag": 1535424629,
  "external_reference": "1042",
  "metadata": { "order_id": "1042" },
  "customer_email": "[email protected]",
  "checkout_url": "https://api.kuaryx.com/pay/a48a66cf-...",
  "expires_at": "2026-11-16T15:40:08Z",
  "paid_at": null
}

Valores em XRP vêm em drops: 1 XRP = 1.000.000 drops.

Checkout

O checkout_url mostra o valor em XRP, o tempo restante e o QR para pagar. Ele acompanha o ledger sozinho: quando o pagamento é validado, mostra a confirmação e leva o cliente ao success_url. Se você não informar success_url, o cliente vê o comprovante da Kuaryx.

Lojistas no plano de mensalidade aceitam qualquer carteira XRP (com a tag de destino). Com taxa por venda, o pagamento é feito pelo app Kuaryx, que separa a taxa na mesma transação.

Não libere o pedido pelo retorno do cliente. O success_url é só navegação. Confirme pelo webhook ou consultando a cobrança com a sua chave.

Consultar cobranças

GET/api/charges/{id} devolve uma cobrança.

GET/api/charges lista da mais nova para a mais antiga. Parâmetros:

GET/api/charges/summary traz o total de vendas de hoje e do mês.

Webhooks

A cada mudança de status a Kuaryx faz um POST para a URL de webhook da sua loja, com o corpo em JSON:

{
  "event": "charge.paid",
  "livemode": true,
  "timestamp": 1794842722,
  "charge": {
    "id": "a48a66cf-...", "status": "paid", "livemode": true,
    "amount_brl": "149.90", "expected_drops": 25843104, "fee_drops": 0,
    "destination_tag": 1535424629, "external_reference": "1042",
    "metadata": { "order_id": "1042" }, "customer_email": "[email protected]",
    "created_at": "...", "expires_at": "...", "paid_at": "..."
  }
}

Eventos: charge.paid, charge.overpaid, charge.underpaid, charge.late_payment, charge.expired. Responda com qualquer código 2xx. Se falhar, a Kuaryx tenta de novo depois de 1 min, 5 min, 30 min, 2 h e 12 h; trate eventos repetidos pelo charge.id.

Confira a assinatura

O cabeçalho X-Kuaryx-Signature traz sha256= seguido do HMAC-SHA256, em hexadecimal, do corpo exato recebido, usando o segredo de webhook da sua loja. Calcule sobre os bytes crus, antes de interpretar o JSON.

// Node.js (Express)
app.post('/kuaryx', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.KUARYX_WEBHOOK_SECRET)
    .update(req.body).digest('hex');
  const got = req.get('X-Kuaryx-Signature') || '';
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  if (event.event === 'charge.paid') { /* libere o pedido event.charge.external_reference */ }
  res.sendStatus(200);
});
// PHP
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, getenv('KUARYX_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_KUARYX_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode($body, true);

Status da cobrança

StatusQuando
pendingCriada, nada recebido ainda.
underpaidRecebeu parte do valor dentro do prazo.
paidRecebeu o valor certo dentro do prazo. Pode liberar o pedido.
overpaidRecebeu mais que o valor; o extra fica na sua carteira.
late_paymentO dinheiro chegou depois do prazo. Você decide se libera.
expiredO prazo acabou sem o valor completo.

Só contam transações validadas na XRP Ledger, pelo valor que de fato chegou (delivered_amount), com a tag de destino da cobrança.

Erros

Dúvidas sobre integração: [email protected]. Para assistentes de IA, o resumo desta página está em /llms.txt.