Documentação da API

Base URL

https://eletrapay.com/api/v1

Esta é a URL base da API do EletraPay. Em ambiente de testes, use uma API key com prefixo sk_test_.

Autenticação

Todas as requisições devem incluir o header Authorization com sua API key no formato Bearer sk_live_... (produção) ou Bearer sk_test_... (sandbox). Gere suas chaves em Configurações → API Keys.

Authorization: Bearer sk_live_SUA_API_KEY

Criar cobrança Pix

Cria uma cobrança Pix e retorna o QR Code (EMV payload + imagem base64) pronto para exibir ao seu cliente. A cobrança expira em 30 minutos por padrão.

Headers

Body (JSON)

Exemplo de requisição

curl -X POST https://eletrapay.com/api/v1/payments \
  -H "Authorization: Bearer sk_live_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-12345" \
  -d '{
    "amount_cents": 9990,
    "description": "Pedido #12345: Camiseta Premium",
    "customer": {
      "name": "João Silva",
      "email": "joao@exemplo.com.br",
      "tax_id": "12345678901"
    },
    "utm": {
      "source": "facebook",
      "medium": "cpc",
      "campaign": "camiseta-verao",
      "term": null,
      "content": "banner-v2"
    },
    "customer_ip": "189.50.123.45"
  }'

Resposta de sucesso. HTTP 201

{
  "id": "pay_abc123def456",
  "amount_cents": 9990,
  "status": "pending",
  "pix": {
    "txid": "TX123456789",
    "emv_payload": "00020126580014br.gov.bcb.pix...",
    "qr_code_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  },
  "expires_at": "2025-01-15T14:30:00.000Z",
  "requires_review": false
}

Campos da resposta

Consultar cobrança

Retorna os detalhes e o status atual de uma cobrança. Use para verificar se o pagamento foi confirmado nos casos em que o webhook não for recebido.

Exemplo

curl https://eletrapay.com/api/v1/payments/pay_abc123def456 \
  -H "Authorization: Bearer sk_live_SUA_API_KEY"

Resposta. HTTP 200

{
  "id": "pay_abc123def456",
  "amount_cents": 9990,
  "net_cents": 9791,
  "fee_cents": 199,
  "status": "approved",
  "created_at": "2025-01-15T14:00:00.000Z",
  "paid_at": "2025-01-15T14:05:33.000Z",
  "expires_at": "2025-01-15T14:30:00.000Z",
  "pix": {
    "txid": "TX123456789",
    "emv_payload": "00020126580014br.gov.bcb.pix...",
    "qr_code_data_url": "data:image/png;base64,..."
  },
  "requires_review": false,
  "risk_score": 12,
  "risk_decision": "approved"
}

Status possíveis

Listar cobranças

Retorna as cobranças da loja associada à API key, paginadas por offset.

Query params

Exemplo

curl "https://eletrapay.com/api/v1/payments?limit=10&status=approved" \
  -H "Authorization: Bearer sk_live_SUA_API_KEY"

Resposta. HTTP 200

{
  "data": [
    {
      "id": "pay_abc123def456",
      "amount_cents": 9990,
      "net_cents": 9791,
      "fee_cents": 199,
      "status": "approved",
      "created_at": "2025-01-15T14:00:00.000Z",
      "paid_at": "2025-01-15T14:05:33.000Z",
      "requires_review": false
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

Webhooks

O EletraPay envia um POST para a URL configurada na sua loja sempre que o status de uma cobrança mudar. Configure a URL em Configurações → Webhooks no painel.

Payload do webhook

{
  "event": "payment.approved",
  "payment": {
    "id": "pay_abc123def456",
    "amount_cents": 9990,
    "net_cents": 9791,
    "status": "approved",
    "paid_at": "2025-01-15T14:05:33.000Z"
  }
}

Eventos disponíveis

Validando a assinatura

Cada request de webhook inclui o header X-EletraPay-Signature com um HMAC-SHA256 do body usando o segredo configurado no painel. Sempre valide antes de processar o evento.

// Node.js
const crypto = require("crypto");

function isValidSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

// Express.js, exemplo completo
app.post("/webhook/EletraPay", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-EletraPay-Signature"];
  if (!isValidSignature(req.body.toString(), sig, process.env.EletraPay_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "invalid_signature" });
  }

  const { event, payment } = JSON.parse(req.body);

  if (event === "payment.approved") {
    // Liberar o pedido do cliente
    await fulfillOrder(payment.id);
  }

  res.json({ ok: true });
});

Códigos de erro

Erros retornam sempre o formato { "error": "<code>", "message": "<descricao>" }. Erros de validação incluem também o campo issues.

Exemplo de erro de validação

{
  "error": "validation_failed",
  "message": "Payload inválido.",
  "issues": [
    { "path": "customer.tax_id", "message": "String must contain at least 11 character(s)" },
    { "path": "amount_cents", "message": "Expected number, received string" }
  ]
}

Idempotência

Sempre envie o header Idempotency-Key em requisições de criação de cobrança. Se a requisição falhar por timeout ou erro de rede e você reenviar, o servidor retornará o mesmo resultado sem criar uma cobrança duplicada. Use qualquer string única por operação, o ID do pedido no seu sistema é uma boa escolha.

// Use o ID do pedido do seu sistema
Idempotency-Key: pedido-12345

// Ou gere um UUID
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

A chave tem validade de 24 horas. Reusar a mesma chave com um payload diferente retorna 409 idempotency_conflict.