API Keys Dashboard Entrar
API Reference

Documentacao AstraPay

Cada usuario cria sua propria API Key no painel e usa essa chave para gerar PIX, consultar status e listar transacoes.

Comecar pela API Key Endpoints PIX Auth API

Quickstart

Fluxo correto: o usuario cria a conta, gera a propria API Key em /api-keys e usa essa chave somente no backend. Na criacao de cobrancas, envie uma chave de idempotencia para nunca duplicar um PIX em tentativas repetidas.

Usuario gera a chave

Cada conta tem suas proprias API Keys. Nao existe PIX anonimo fora de uma conta.

Backend envia a cobranca

Use X-Api-Key e envie valor, descricao e dados opcionais do pagador.

PIX fica vinculado

Exiba o QR Code ou o campo pix_copy_paste para o cliente pagar.

curl -X POST http://72.60.140.55/api/v1/pix \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: astrapay_SUA_CHAVE" \
  -H "X-Idempotency-Key: pedido-1234" \
  -d '{"valor":29.90,"descricao":"Pedido #1234"}'

Autenticacao

Use API Key para integracoes externas. Use Bearer Token apenas no app/painel do usuario.

Bearer Token Dashboard / App interna

Token retornado no login. Ele serve para o dashboard e endpoints de conta do usuario.

curl -X POST http://72.60.140.55/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"seu@email.com","password":"SuaSenha1"}'

# Response:
{
  "success": true,
  "data": {
    "token": "abc123...",
    "user": { "id": 1, "name": "...", "email": "...", "tier": "basic" }
  }
}

# Use the token:
curl http://72.60.140.55/api/auth/me \
  -H "Authorization: Bearer abc123..."
API Key Integracao externa por usuario

Chave para integracao server-to-server. Cada usuario gera a propria chave no painel em API Keys.

curl -X POST http://72.60.140.55/api/v1/pix \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: astrapay_SUA_CHAVE_AQUI" \
  -d '{"valor":29.90,"descricao":"Pedido #1234"}'

API v1 - PIX (API Key)

Base URL: http://72.60.140.55/api/v1

Metodo URL Auth Descricao
POST /pix API Key Criar nova cobranca PIX
GET /pix/{id} API Key Consultar status de um PIX
GET /balance API Key Consultar saldo do usuario
GET /transactions API Key Listar transacoes (paginado)
POST /webhook API Key Cadastrar URL para receber eventos PIX
POST /api/v1/pix

Cria uma nova cobranca PIX.

Parametros (JSON Body)

CampoTipoObrig.Descricao
valorfloatSimValor em reais (ex: 29.90)
descricaostringNaoDescricao da cobranca
payer_namestringNaoNome do pagador
payer_cpf_cnpjstringNaoCPF/CNPJ do pagador

curl

curl -X POST http://72.60.140.55/api/v1/pix \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: astrapay_..." \
  -H "X-Idempotency-Key: pedido-1234" \
  -d '{"valor":29.90,"descricao":"Pedido #1234"}'

JavaScript (fetch)

fetch('http://72.60.140.55/api/v1/pix', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'astrapay_...',
    'X-Idempotency-Key': 'pedido-1234',
  },
  body: JSON.stringify({
    valor: 29.90,
    descricao: 'Pedido #1234',
  }),
}).then(r => r.json())
  .then(data => console.log(data));

Resposta (201 Created)

{
  "success": true,
  "data": {
    "transaction": {
      "id": 42,
      "amount": 29.90,
      "net_amount": 29.45,
      "fee_amount": 0.45,
      "status": "pending",
      "pix_copy_paste": "00020126360014br.gov.bcb.pix...",
      "pix_qrcode_url": "data:image/png;base64,...",
      "pix_expiration": "2026-07-20T15:00:00",
      "description": "Pedido #1234"
    },
    "idempotent_replay": false
  }
}
GET /api/v1/pix/{id}

Consulta o status e detalhes de uma transacao PIX.

curl

curl http://72.60.140.55/api/v1/pix/42 \
  -H "X-Api-Key: astrapay_..."

JS fetch

fetch('http://72.60.140.55/api/v1/pix/42', {
  headers: { 'X-Api-Key': 'astrapay_...' }
}).then(r => r.json())
  .then(data => {
    if (data.data.transaction.status === 'confirmed') {
      console.log('Pago!');
    }
  });

Auth API (Bearer Token)

Endpoints para autenticacao e gerenciamento de conta de usuario.

Metodo URL Auth Descricao
POST /api/auth/register Publico Criar nova conta
POST /api/auth/login Publico Login de usuario
POST /api/auth/verify-email Publico Verificar email
GET /api/auth/me Bearer Dados do usuario logado
POST /api/auth/register

Cria uma nova conta AstraPay. Senha deve ter 8+ caracteres, 1 maiuscula e 1 numero.

curl

curl -X POST http://72.60.140.55/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Seu Nome",
    "email": "seu@email.com",
    "password": "Senha123",
    "cpf": "000.000.000-00"
  }'

Resposta (201)

{
  "success": true,
  "data": {
    "token": "abc123...",
    "user": { "id": 1, "name": "Seu Nome", ... },
    "message": "Conta criada com sucesso."
  }
}
POST /api/auth/login

Realiza login e retorna um Bearer token valido por 24 horas.

curl

curl -X POST http://72.60.140.55/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"seu@email.com","password":"Senha123"}'

Resposta (200)

{
  "success": true,
  "data": {
    "token": "abc123...",
    "user": { "id": 1, "name": "...", "email": "...", "tier": "basic" }
  }
}
POST /api/auth/verify-email

Confirma o email do usuario usando o token enviado.

curl -X POST http://72.60.140.55/api/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token":"abc123..."}'

# Response (200):
{ "success": true, "data": { "message": "Email verificado com sucesso", "tier_upgraded_to": "basic" } }

PIX (Bearer Token)

Endpoints autenticados usados pelo dashboard.

Metodo URL Auth Descricao
POST /api/pix/create Bearer Criar cobranca PIX
GET /api/pix/status Bearer Consultar status (?id=X)
GET /api/pix/list Bearer Listar transacoes
GET /api/pix/stats Bearer Estatisticas de PIX

Rate Limits

60

req/min (API Key)

Limite padrao por chave

30

req/min (Bearer)

Limite global por IP

429

Limite excedido

Header Retry-After incluso

Webhooks

Cadastre uma URL HTTPS para receber pix.updated sempre que o status da cobranca mudar. A URL recebe uma assinatura HMAC SHA-256 para seu backend validar a origem.

curl -X POST http://72.60.140.55/api/v1/webhook \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: astrapay_..." \
  -d '{"url":"https://sua-loja.com/webhooks/astrapay","events":["pix.updated"]}'

# A resposta retorna signing_secret uma unica vez.
// Payload recebido
{
  "id": "evt_...",
  "event": "pix.updated",
  "created_at": "2026-09-15T20:00:00+00:00",
  "data": { "transaction": { "id": 42, "status": "confirmed" } }
}

// Assinatura para validar
HMAC_SHA256(timestamp + "." + raw_body, signing_secret)
// Headers: X-AstraPay-Timestamp e X-AstraPay-Signature: v1=...