API ProBulls

Autenticação

Gere uma chave em API → Chaves de API. Envie em todas as requisições:

Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx

Criar cobrança PIX

POST /pix/charge

curl -X POST https://probulls.xyz/api/v1/pix/charge \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 5000,
    "description": "Pedido #123",
    "external_ref": "order_123"
  }'

Resposta

{
  "id": "uuid",
  "status": "pending",
  "amount_cents": 5000,
  "pix": {
    "qr_code_image": "data:image/png;base64,...",
    "copy_paste": "00020126...",
    "expires_at": "2026-06-16T13:30:00Z"
  },
  "external_ref": "order_123",
  "created_at": "2026-06-16T13:00:00Z"
}

Consultar transação

GET /transactions/:id

curl https://probulls.xyz/api/v1/transactions/{id} \
  -H "Authorization: Bearer ak_live_xxx"

Criar saque PIX

POST /pix/withdraw

curl -X POST https://probulls.xyz/api/v1/pix/withdraw \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 10000,
    "pix_key": "user@example.com",
    "pix_key_type": "email"
  }'

Consultar saldo

GET /balance

curl https://probulls.xyz/api/v1/balance \
  -H "Authorization: Bearer ak_live_xxx"

Webhooks

Configure URLs em API → Webhooks. A ProBulls envia eventos em POST com o corpo abaixo e header de assinatura:

x-probulls-signature: sha256=<hex>
x-probulls-event: payment.approved
Content-Type: application/json

{
  "event": "payment.approved",
  "created_at": "2026-06-16T13:05:00Z",
  "data": { "id": "...", "amount_cents": 5000, ... }
}

Validar assinatura (Node)

import crypto from "crypto";
const expected = crypto.createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody).digest("hex");
const got = req.headers["x-probulls-signature"].replace(/^sha256=/,"");
if (expected !== got) return res.status(401).end();

Eventos disponíveis

• payment.approved
• payment.failed
• payment.refunded
• payment.expired
• withdrawal.completed
• withdrawal.failed

Códigos de erro

• 400 — corpo inválido
• 401 — chave de API ausente ou inválida
• 402 — saldo insuficiente (saque)
• 404 — recurso não encontrado
• 502 — falha na adquirente