Hubpay
← Conectar PSPs

Conectar Stark Bank

⏱ Tempo estimado: 15-20 minutos

O Stark Bank usa autenticação ECDSA com par de chaves (pública/privada), o que é mais seguro que API keys simples.

1

Criar conta no Stark Bank

  1. Acesse starkbank.com
  2. Clique em "Abrir conta" ou "Get Started"
  3. O Stark Bank exige CNPJ — é voltado pra empresas
  4. Preencha os dados e envie documentação pra verificação
  5. Aguarde aprovação (pode levar alguns dias)
2

Criar um projeto (Project)

  1. Acesse seu workspace no Stark Bank
  2. Vá em Developers → Projects
  3. Clique em "Create Project"
  4. Dê um nome (ex: "Hubpay")
  5. Copie o Project ID (número longo, ex: 5155165527080960)
3

Gerar par de chaves ECDSA

O Stark Bank usa criptografia ECDSA (curva secp256k1, a mesma do Bitcoin) pra autenticação. Você precisa gerar um par de chaves.

No terminal:

bash
# Gerar chave privada
openssl ecparam -name secp256k1 -genkey -noout -out private-key.pem

# Extrair chave pública
openssl ec -in private-key.pem -pubout -out public-key.pem

Ou usando o SDK do Stark Bank (Node.js):

javascript
const starkbank = require('starkbank');
const [privateKey, publicKey] = starkbank.key.create();
console.log('Chave privada:', privateKey);
console.log('Chave pública:', publicKey);
// Salve ambas em arquivos .pem seguros
4

Registrar chave pública no Stark Bank

  1. No painel Stark Bank, vá em Developers → Projects → seu projeto
  2. Cole a chave pública (public-key.pem) no campo indicado
  3. Salve
⚠️A chave pública é registrada no Stark Bank. A chave privada fica APENAS com você (e será cadastrada no Hubpay, criptografada).
5

Conectar no Hubpay

  1. Acesse hubpay.dev/dashboard/psps
  2. Clique em Conectar novo PSP
  3. Selecione Stark Bank
  4. Selecione o ambiente:
    • Test se está usando sandbox
    • Live se está usando produção
  5. Dê um label (ex: "Stark Bank principal")
  6. Preencha:
    • Project ID: cole o ID do projeto (ex: 5155165527080960)
    • Chave Privada ECDSA: cole o conteúdo completo do arquivo private-key.pem (incluindo -----BEGIN EC PRIVATE KEY----- e -----END EC PRIVATE KEY-----)
    • Ambiente Stark Bank: Sandbox ou Production
  7. Clique em Salvar credencial
💡Sua chave privada é criptografada com AES-256-GCM antes do armazenamento.
6

Configurar webhook

Após salvar, a tela mostrará a URL e o token do webhook. Copie ambos e configure no painel do Stark Bank:

  1. No painel Stark Bank → Developers → Webhooks
  2. Clique em "Create Webhook"
  3. Cole a URL e configure o token no header HTTP x-hubpay-token
  4. Selecione eventos: invoice.created, invoice.paid, invoice.canceled, invoice.expired
  5. Salve
7

Testar

bash
curl -X POST https://api.hubpay.dev/v1/charges \
  -H "Authorization: Bearer hpx_test_SUA_CHAVE_HUBPAY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "provider": "starkbank",
    "description": "Teste Stark Bank"
  }'
⚠️No sandbox do Stark Bank, invoices são pagas automaticamente em poucos segundos. Isso facilita o teste — basta criar e aguardar o webhook de pagamento.

Solução de problemas

ErroCausaSolução
502 com "invalid signature"Chave privada incorreta ou não corresponde à pública registradaRegenere o par de chaves e registre novamente no Stark Bank
502 com "project not found"Project ID incorretoVerifique o ID no painel Stark Bank
502 com "environment mismatch"Credencial de produção usada com ambiente sandbox ou vice-versaConfira o campo "Ambiente Stark Bank" no cadastro
Invoice não gera brcodePode ser limitação temporária do sandboxTente criar outra invoice; o sandbox é eventual

Sobre as chaves ECDSA

  • Chave privada: fica no Hubpay (criptografada) e é usada pra assinar requisições
  • Chave pública: fica registrada no Stark Bank pra validar as assinaturas
  • Se a chave privada for comprometida, gere novo par e atualize em ambos (Stark Bank e Hubpay)
  • O Stark Bank usa curva secp256k1 (mesma do Bitcoin)

Links úteis