Como autenticar na API da Rhuar?

Use o header Authorization: Bearer {access_token}. O token é obtido via POST /api/login ou POST /api/register e pode ser gerenciado em /api/keys.

Como criar uma cobrança PIX?

Faça POST /api/deposito com amount e callback_url opcional. A resposta traz o brcode (copia-e-cola PIX) para o pagador.

Como verificar a assinatura de um webhook?

Calcule sha256= mais o HMAC-SHA256 de timestamp.'.'.body usando o webhook_secret, compare com o header X-Blimx-Signature usando comparação de tempo constante e rejeite timestamps fora de ±300 segundos.

Documentação — Rhuar Pagamentos PIX (API REST)

Visão geral

A API Rhuar é uma API REST para pagamentos PIX. Com ela você cria cobranças (cash-in), faz pagamentos (cash-out), consulta saldo e extrato e recebe webhooks assinados quando um evento ocorre. A integração é server-to-server, autenticada por Bearer Token.

Base URL: https://api.rhuar.com · Todas as requisições devem enviar Accept: application/json.

Procurando a referência sempre atualizada? Veja a documentação JSON viva ou a documentação para LLMs.

Autenticação

Inclua o token em toda requisição protegida:

Authorization: Bearer {access_token}

Obtenha o primeiro token via POST /api/register (cadastro) ou POST /api/login. Crie chaves adicionais nomeadas em POST /api/keys — o token é mostrado uma única vez. Tokens não expiram; revogue em DELETE /api/keys/{id} se comprometidos. Sem token válido, a API responde 401 em JSON.

Cobranças — receber dinheiro (cash-in)

POST /api/deposito — cria uma cobrança PIX.

{ "amount": 100.00, // obrigatório "callback_url": "https://seu.site/webhook", // opcional (anti-SSRF) "expires_in": 5 // opcional, minutos }

A resposta traz txid e brcode (PIX copia-e-cola; gere o QR a partir dele). Quando o pagador paga, a Rhuar confirma com o banco, credita o saldo e dispara o webhook deposito.concluido.

Método	Rota	Descrição
POST	`/api/deposito`	Cria cobrança PIX
GET	`/api/deposito/{txid}`	Consulta uma cobrança
GET	`/api/depositos`	Lista cobranças (cap 500)

Pagamentos — enviar dinheiro (cash-out)

POST /api/saque — envia um PIX para uma chave.

{ "amount": 50.00, // obrigatório "pix_key": "12345678901", // obrigatório, 11–77 chars "callback_url": "https://seu.site/webhook" }

O saldo (saque + taxa) é reservado de forma atômica antes do envio. Em caso de falha, saque e taxa são estornados automaticamente. A confirmação final chega pelo webhook saque.concluido ou saque.falhou.

Método	Rota	Descrição
POST	`/api/saque`	Cria um pagamento PIX
GET	`/api/saque/{e2e}`	Consulta um pagamento
GET	`/api/saques`	Lista pagamentos (cap 500)

Saldo & extrato

Método	Rota	Descrição
GET	`/api/saldo`	Saldo atual da conta
GET	`/api/extrato`	Extrato de transações (cap 500)
GET	`/api/webhook-secret`	ROTACIONA: invalida o anterior e retorna um novo segredo (consultar = perdi o secret)

Webhooks

Quando um evento ocorre, a Rhuar faz um POST assinado para a sua callback_url. Eventos: deposito.concluido, saque.concluido, saque.falhou.

Header	Descrição
`X-Blimx-Event`	Nome do evento
`X-Blimx-Timestamp`	Unix timestamp do envio
`X-Blimx-Signature`	`sha256=HMAC-SHA256(timestamp."."body, webhook_secret)`

Verifique a assinatura sempre, com comparação de tempo constante, e rejeite timestamps fora de ±300s:

// PHP $expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $secret); abort_unless(hash_equals($expected, $sig) && abs(time() - (int)$ts) <= 300, 403);

Deduplique por txid (cobrança) e e2e (pagamento) — em caso de retry, o mesmo evento pode chegar mais de uma vez.

Códigos de resposta

Código	Significado
`200`	Sucesso
`201`	Recurso criado
`401`	Não autenticado / credenciais inválidas
`404`	Recurso não encontrado
`422`	Validação (inclui saldo insuficiente, SSRF, valor acima do máximo)
`429`	Rate limit excedido
`500`	Erro interno