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:
- Produção (
kuaryx_...): cobranças reais, pagas em XRP na rede principal. Entregue quando o seu acesso é liberado. - Teste (
kuaryx_test_...): gere no painel do lojista, em Integração (API). Cobranças de teste nunca movimentam XRP, não têm taxa e respondem com"livemode": false.
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
| Campo | Tipo | Descrição |
|---|---|---|
amount_brl | texto decimal | Obrigatório. Valor em reais; a Kuaryx converte para XRP pela cotação do momento (Binance conferida com CoinGecko). |
description | texto | Aparece para o cliente no checkout. |
external_reference | texto até 255 | O id do pedido na sua loja. Dá para filtrar a lista por ele. |
expires_in_minutes | 1 a 1440 | Prazo para pagar. Padrão: 15 minutos. |
metadata | objeto | Até 20 chaves suas (texto até 40, valores simples até 500). Volta na API e nos webhooks. |
customer_email | E-mail do comprador, para a sua conciliação. | |
success_url | URL http(s) | Para onde o checkout leva o cliente depois do pagamento, com ?kuaryx_charge_id=... no fim. |
cancel_url | URL 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:
limit: 1 a 500 (padrão 100).created_before: para a próxima página, ocreated_atda última cobrança recebida.status_filter: um dos status.external_reference: o id do pedido na sua loja.
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
| Status | Quando |
|---|---|
pending | Criada, nada recebido ainda. |
underpaid | Recebeu parte do valor dentro do prazo. |
paid | Recebeu o valor certo dentro do prazo. Pode liberar o pedido. |
overpaid | Recebeu mais que o valor; o extra fica na sua carteira. |
late_payment | O dinheiro chegou depois do prazo. Você decide se libera. |
expired | O 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
401: chave ausente ou inválida.403: ação de outro modo (por exemplo, simular pagamento com a chave de produção).404: cobrança não existe ou é do outro modo.409:Idempotency-Keyjá usada no outro modo.422: campo inválido; o corpo explica qual.503: cotação indisponível no momento. Tente de novo em alguns segundos.
Dúvidas sobre integração: [email protected]. Para assistentes de IA, o resumo desta página está em /llms.txt.