Documentação da API AuraPay

Começar

O seu sistema cria a cobrança, o cliente paga com Pix e o processador confirma o resultado. A AuraPay regista o pagamento e disponibiliza o valor líquido na carteira.

https://aurapay.site/api/public/v1

1. Crie uma integração em API e Integrações → Integrações e chaves.
2. Gere uma chave de API (comece pelo ambiente Sandbox).
3. Faça a primeira requisição para criar uma cobrança Pix.
4. Apresente o QR Code ou o código copia-e-cola ao seu cliente.
5. Receba a confirmação automática via webhook e atualize a encomenda.
6. Valide a integração e ative o ambiente de produção.

Autenticação

Todas as requisições usam o cabeçalho Authorization: Bearer SUA_CHAVE_SECRETA. As chaves de produção começam por ak_live_ e as de teste por ak_test_.

Nunca coloque a chave secreta numa página HTML pública ou numa aplicação móvel distribuída: guarde-a num backend que controla. HTTPS é obrigatório.

Cobranças Pix

Envie um corpo JSON com amount em reais. currency aceita BRL; description identifica a compra e external_reference liga a cobrança ao pedido do seu sistema. As respostas abaixo são exemplos, não transações reais.

curl -X POST "https://aurapay.site/api/public/v1/pix/charges" \
  -H "Authorization: Bearer SUA_CHAVE_SECRETA" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-12345" \
  -d '{
    "amount": 50.00,
    "currency": "BRL",
    "description": "Compra na minha loja",
    "external_reference": "pedido-12345"
  }'

{
  "id": "8f3e…",
  "status": "pending",
  "amount": 50.00,
  "currency": "BRL",
  "external_reference": "pedido-12345",
  "environment": "production",
  "pix": {
    "copy_paste": "00020126…",
    "qrcode": "data:image/svg+xml,…"
  },
  "fee_percentage": 5,
  "platform_fee": 0,
  "net_amount": 0,
  "created_at": "2026-10-19T05:00:00Z",
  "expires_at": "2026-10-19T05:30:00Z"
}

Consultar: GET /pix/charges/{id} · Cancelar (só pendentes): POST /pix/charges/{id}/cancel. Valor mínimo R$ 10,00, máximo R$ 100.000,00.

Estados de pagamento

A confirmação resulta sempre do processador de pagamentos — nunca de uma página de retorno do cliente.

Idempotência

Envie o cabeçalho Idempotency-Key ao criar cobranças. Se a requisição for repetida (falha de rede, timeout), a API devolve a cobrança original em vez de criar uma duplicada. A chave é única por integração.

Webhooks

Registe um endpoint HTTPS em Webhooks. Cada entrega é assinada com HMAC-SHA256 no cabeçalho x-aurapay-signature: t={timestamp},v1={assinatura}, calculada sobre {timestamp}.{corpo} com o segredo do endpoint. Rejeite mensagens com mais de 5 minutos.

const crypto = require("crypto");

function validar(segredo, cabecalho, corpoBruto) {
  const partes = Object.fromEntries(
    cabecalho.split(",").map((p) => p.split("="))
  );
  const esperado = crypto
    .createHmac("sha256", segredo)
    .update(partes.t + "." + corpoBruto)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(partes.v1), Buffer.from(esperado)
  );
}

import hmac, hashlib

def validar(segredo: str, cabecalho: str, corpo: bytes) -> bool:
    partes = dict(p.split("=") for p in cabecalho.split(","))
    esperado = hmac.new(
        segredo.encode(),
        (partes["t"] + ".").encode() + corpo,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(partes["v1"], esperado)

function validar($segredo, $cabecalho, $corpo) {
  parse_str(str_replace(",", "&", $cabecalho), $p);
  $esperado = hash_hmac("sha256", $p["t"] . "." . $corpo, $segredo);
  return hash_equals($p["v1"], $esperado);
}

Entregas falhadas são repetidas automaticamente (1 min, 5 min, 30 min, 2 h — máx. 5 tentativas). A sua aplicação deve tratar eventos repetidos de forma idempotente.

Taxas e liquidação

Exemplo de cálculo para um pagamento confirmado de R$ 100,00.

Sem assinatura nem mensalidade de R$ 50,00. A taxa de 5% + R$ 1,00 aplica-se apenas a novas transações efetivamente pagas — nunca a cobranças pendentes, falhadas ou expiradas. Cobranças de Sandbox não movimentam dinheiro nem têm taxas. O líquido entra na sua carteira AuraPay. Solicite o saque manual no seu painel; a AuraPay não efetua pagamentos automáticos.

Códigos de erro

Exemplos de integração

const res = await fetch("https://aurapay.site/api/public/v1/pix/charges", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.AURAPAY_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "pedido-12345",
  },
  body: JSON.stringify({
    amount: 50.0,
    currency: "BRL",
    description: "Compra na minha loja",
    external_reference: "pedido-12345",
  }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(error.code + ": " + error.message);
}
const cobranca = await res.json();
console.log(cobranca.pix.copy_paste); // apresentar ao cliente

$ch = curl_init("https://aurapay.site/api/public/v1/pix/charges");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("AURAPAY_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: pedido-12345",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => 50.00,
    "currency" => "BRL",
    "description" => "Compra na minha loja",
    "external_reference" => "pedido-12345",
  ]),
]);
$cobranca = json_decode(curl_exec($ch), true);
echo $cobranca["pix"]["copy_paste"];

import os, requests

res = requests.post(
    "https://aurapay.site/api/public/v1/pix/charges",
    headers={
        "Authorization": "Bearer " + os.environ["AURAPAY_KEY"],
        "Idempotency-Key": "pedido-12345",
    },
    json={
        "amount": 50.00,
        "currency": "BRL",
        "description": "Compra na minha loja",
        "external_reference": "pedido-12345",
    },
    timeout=15,
)
res.raise_for_status()
cobranca = res.json()
print(cobranca["pix"]["copy_paste"])

OpenAPI

A especificação OpenAPI 3.0 da API está disponível em https://aurapay.site/api/public/v1/openapi.json (JSON). Corresponde exatamente aos endpoints implementados.

Sandbox e produção

Os dois ambientes usam a mesma referência de endpoints; o ambiente é determinado pela chave. Não misture credenciais ou resultados de teste com transações reais.

Segurança e boas práticas

• Proteja as credenciais. Guarde chaves e segredos no seu servidor, nunca no código público, em imagens, mensagens ou registos de erro. Revogue uma chave comprometida no painel e substitua-a.
• Use apenas as permissões necessárias. Cada chave está associada a uma integração e a permissões específicas. Uma resposta 403 pode indicar falta de permissão ou suspensão.
• Confirme no servidor. Uma página de sucesso ou um comprovativo enviado pelo cliente não confirma o pagamento. Consulte a cobrança ou valide o evento assinado do processador.
• Trate repetições e falhas. Use idempotência, valide assinaturas sobre o corpo original e não entregue o mesmo pedido duas vezes. Em caso de 429, reduza a frequência e volte a tentar após o intervalo indicado.
• Minimize dados pessoais. Envie apenas o necessário e não inclua palavras-passe, documentos ou outros dados sensíveis em descrições e metadados.