Hubpay
← Conectar PSPs

Conectar Sicoob

⏱ Tempo estimado: 20-30 minutos

O Sicoob é o maior sistema de cooperativas de crédito do Brasil. A API Pix usa autenticação OAuth2 com certificado ICP-Brasil (A1).

⚠️A API Pix do Sicoob está disponível apenas para cooperados (PF e PJ). Você precisa ter conta em uma cooperativa Sicoob.
1

Ser cooperado do Sicoob

  1. Você precisa ser cooperado (associado) do Sicoob
  2. Abra conta em uma cooperativa Sicoob ou use sua conta existente
  3. Solicite adesão à API Pix junto à sua agência/cooperativa
2

Cadastrar chave Pix

  1. No app Sicoob ou Internet Banking, cadastre uma chave Pix
  2. Pode ser CNPJ, CPF, email, telefone ou aleatória
  3. Copie e guarde a chave
3

Obter certificado ICP-Brasil (A1)

O Sicoob usa certificado digital ICP-Brasil pra autenticação — não gera certificado próprio como Efí, Inter ou Sicredi.

Se você já tem um certificado A1 (formato .pfx ou .p12), converta para .pem e .key:

bash
# Extrair certificado
openssl pkcs12 -in certificado.pfx -clcerts -nokeys -out certificado.pem

# Extrair chave privada
openssl pkcs12 -in certificado.pfx -nocerts -nodes -out chave.pem

Quando pedir a senha, use a senha do certificado.

⚠️Certificados ICP-Brasil tipo A3 são em token/cartão físico — NÃO funcionam via API (não é possível exportar a chave privada). Se seu certificado é A3, adquira um A1.

Se não tem certificado A1, adquira um junto a uma Autoridade Certificadora credenciada (Certisign, Serasa, Valid, etc.). Custo médio: R$ 100-200/ano.

4

Criar aplicativo no Portal Developers

  1. Acesse developers.sicoob.com.br
  2. Cadastre-se com seus dados de cooperado
  3. Crie um novo Aplicativo
  4. Informe os dados da conta bancária
  5. Faça upload do certificado (formato .cer ou .pem, apenas a parte pública)
  6. Selecione os escopos: cob.read, cob.write, pix.read, webhook.write, webhook.read
  7. Copie o Client ID gerado
💡O Sicoob não gera Client Secret pra API Pix — a autenticação é via certificado mTLS + Client ID.
5

Conectar no Hubpay

  1. Acesse hubpay.dev/dashboard/psps
  2. Clique em Conectar novo PSP
  3. Selecione Sicoob
  4. Selecione o ambiente:
    • Test = sandbox
    • Live = produção
  5. Preencha:
    • Client ID: do Portal Developers
    • Chave Pix: chave cadastrada no Sicoob
    • Certificado (.pem): conteúdo do certificado
    • Chave Privada (.key): conteúdo da chave privada
  6. Clique em Salvar credencial
💡🔒 Certificado e chave privada criptografados com AES-256-GCM antes do armazenamento.
6

Configurar webhook

Após salvar, siga as instruções na tela do dashboard.

⚠️Peculiaridade do Sicoob: ao registrar o webhook, o Sicoob adiciona automaticamente /pix ao final da URL. O Hubpay já trata isso — use a URL exatamente como mostrada.
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": "sicoob",
    "description": "Teste Sicoob"
  }'

Solução de problemas

ErroCausaSolução
502 com "SSL" ou "mTLS"Certificado ICP-Brasil inválido ou expiradoConfirme que converteu corretamente de .pfx pra .pem/.key.
502 com "OAuth 401"Client ID incorreto ou certificado não correspondeVerifique no Portal Developers. Confirme que o certificado é o mesmo registrado.
502 com "chave Pix"Chave não cadastradaCadastre chave Pix na conta Sicoob.
Webhook não chegaURL sem /pixO Hubpay já trata automaticamente. Verifique se o webhook está registrado na API Pix Sicoob.
"Certificado expirado"Certificado A1 venceu (validade 1 ano)Renove com a Autoridade Certificadora e atualize no Hubpay.
"Não é cooperado"Conta não é do sistema SicoobA API é exclusiva para cooperados.

Comparação com outros PSPs que usam mTLS

AspectoEfíBanco InterSicrediSicoob
CertificadoGerado pelo Efí (.p12)Gerado pelo Inter (.crt+.key)Gerado pelo Sicredi (.crt+.key)ICP-Brasil A1 (.pfx→.pem+.key)
Client SecretSimSimSimNão (auth via mTLS)
OAuth URLefipay.com.brbancointer.com.brsicredi.com.brauth.sicoob.com.br (Keycloak)
Webhook /pixNãoNãoNãoSim (adiciona /pix na URL)
API PixPadrão BCBPadrão BCBPadrão BCBPadrão BCB
Tipo contaPF e PJSomente PJSomente PJCooperados (PF e PJ)

Links úteis