O que é esta API

A API Pix do Sicredi é a implementação do padrão do Banco Central para o arranjo Pix, para integração com ERPs ou sistemas próprios via REST. Ela permite que associados PJ automatizem o recebimento com liquidação imediata, 24 horas por dia: cobranças imediatas, com vencimento e recorrentes (Pix Automático), consulta e conciliação de Pix recebidos, devoluções e webhooks de notificação. A autenticação combina mTLS e OAuth2 (client_credentials) e segue o Manual de Padrões para Iniciação do Pix do Bacen, com as recomendações proprietárias do Sicredi descritas nesta página.

Casos de uso principais:

• Cobranças Pix imediatas (QR Code dinâmico)
• Cobranças Pix com vencimento
• Cobranças Pix com recorrência (Pix Automático)
• Consulta e conciliação de Pix recebidos
• Solicitação de devoluções
• Notificações automáticas via webhook

Qual é o seu ponto de partida?

Já tenho certificado e credenciais (Client ID e Client Secret) gerados. Comece no Passo 1, Obter token de acesso.

Ainda não tenho acesso liberado. Veja a seção "Como obter acesso à API Pix" antes de continuar. Essa etapa envolve a sua cooperativa e o Portal do Desenvolvedor, e não é feita por aqui.

Integro por um provedor homologado. O caminho é diferente e mais curto: você não gera certificado no Portal. Veja "Entenda os dois caminhos de integração" logo abaixo.

Entenda os dois caminhos de integração

A maior fonte de dúvida na adesão ao Pix é que existem dois caminhos distintos, com jornadas diferentes:

Antes de começar

O acesso envolve a adesão junto à cooperativa, o cadastro no Portal do Desenvolvedor, a emissão de um certificado digital e a geração das credenciais OAuth2. Na integração individual, todo o ciclo de certificado e credenciais é feito no Portal do Desenvolvedor (developer.sicredi.com.br). O passo a passo completo está em "Como obter acesso à API Pix".

Ambientes:

Passo a passo: sua primeira chamada

1. Obter token de acesso

A API Pix usa OAuth2 Client Credentials sobre mTLS. O token é gerado em POST /oauth/token, com as credenciais no header Authorization: Basic:

curl --location --request POST 'https://api-pix.sicredi.com.br/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=cob.write cob.read webhook.read webhook.write'

O valor de Authorization é a palavra Basic seguida de client_id:client_secret (separados por :) codificados em Base64. O scope lista os escopos desejados, separados por espaço. A chamada exige o certificado mTLS configurado na conexão.

Escopos disponíveis (por modalidade de recebimento):

cob.write / cob.read: cobrança imediata

• cobv.write / cobv.read / lotecobv.write / lotecobv.read: cobrança com vencimento e lotes
• cobr.write / cobr.read: cobrança recorrente (Pix Automático)
• rec.write / rec.read: recorrências (Pix Automático)
• solicrec.write / solicrec.read: solicitações de confirmação de recorrência (Pix Automático)
• pix.read: consulta de Pix recebidos e devoluções
• webhook.write / webhook.read: webhooks

Os escopos são liberados conforme a modalidade contratada na adesão. Se um escopo não estiver habilitado para a credencial, a API retorna 400.

2. Criar cobrança imediata (COB)

Crie uma cobrança Pix imediata com PUT /cob/{txid}. Os dados vão no corpo:

curl --location --request PUT 'https://api-pix.sicredi.com.br/api/v2/cob/SEU_TXID' \ 
  --header 'Authorization: Bearer SEU_ACCESS_TOKEN' \ 
  --header 'Content-Type: application/json' \ 
  --data '{ 
    "calendario": { "expiracao": 3600 }, 
    "devedor": { "cnpj": "12345678000195", "nome": "Empresa Exemplo SA" }, 
    "valor": { "original": "100.00" }, 
    "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906", 
    "solicitacaoPagador": "Pagamento do servico X" 

  }' 

Escopo exigido: cob.write. O txid é alfanumérico de 26 a 35 caracteres, único por CNPJ recebedor.

3. Consultar cobrança

curl --location --request GET 'https://api-pix.sicredi.com.br/api/v2/cob/SEU_TXID' \ 
  --header 'Authorization: Bearer SEU_ACCESS_TOKEN' 
 

Escopo exigido: cob.read. Quando paga, o status passa a CONCLUIDA e o array pix traz o recebimento. Status possíveis: ATIVA, CONCLUIDA, REMOVIDA_PELO_USUARIO_RECEBEDOR, REMOVIDA_PELO_PSP.

4. Configurar webhook (opcional)

curl --location --request PUT 'https://api-pix.sicredi.com.br/api/v2/webhook/SUA_CHAVE_PIX' \ 
  --header 'Authorization: Bearer SEU_ACCESS_TOKEN' \ 
  --header 'Content-Type: application/json' \ 
  --data '{ "webhookUrl": "https://seu-sistema.com/webhook/pix" }' 

Escopo exigido: webhook.write.

5. Consultar Pix recebido

curl --location --request GET 'https://api-pix.sicredi.com.br/api/v2/pix/E12345678202606241520abcdef12345' \ 

  --header 'Authorization: Bearer SEU_ACCESS_TOKEN' 

Escopo exigido: pix.read. O txid associa o Pix à cobrança que o originou, quando houver.

6. Consultar Pix recebidos por período (conciliação)

curl --location --request GET 'https://api-pix.sicredi.com.br/api/v2/pix?inicio=2026-06-01T00:00:00Z&fim=2026-06-01T23:59:59Z' \  

  --header 'Authorization: Bearer SEU_ACCESS_TOKEN' 

Parâmetros (query):

• inicio (RFC 3339, obrigatório): início do período
• fim (RFC 3339, obrigatório): fim do período
• cpf ou cnpj (opcional): filtra pelo documento do pagador, não podem ser enviados juntos
• txIdPresente (opcional): filtra recebimentos que possuem txid
• devolucaoPresente (opcional): filtra recebimentos que possuem devolução
• paginacao.paginaAtual e paginacao.itensPorPagina (opcional)

Escopo exigido: pix.read.

7. Tratamento de erros

A API Pix segue o padrão de erros do Bacen (RFC 7807, application/problem+json).

Como obter acesso à API Pix

Esta seção detalha a jornada de adesão da integração individual. Se você já tem certificado e credenciais, volte ao Passo 1.

Autenticação em detalhe

A API Pix autentica em servidor próprio (api-pix.sicredi.com.br/oauth/token), diferente das demais APIs da família Multipag. O par Client ID e Client Secret vai codificado em Base64 no header Authorization: Basic, e a conexão exige o certificado mTLS.

Boas práticas de token:

• Reaproveite o access_token enquanto válido. A validade está em expires_in (segundos) na resposta.
• Não gere um token novo a cada chamada. Excesso de geração pode acionar mecanismos de segurança e causar bloqueio temporário.
• Quando o token expirar, gere um novo com as mesmas credenciais.

Pix Automático: modelos de implementação e regras

O Pix Automático (recorrência) tem quatro jornadas reguladas pelo Bacen. A escolha depende de como a autorização da recorrência é obtida do pagador.

O detalhamento normativo de cada jornada está na documentação oficial do Bacen (Manual de Padrões para Iniciação do Pix).

Regras operacionais (Pix Automático):

• Prazo de aceite: a solicitação de recorrência pode permanecer pendente por até 30 dias.
• Janela de envio das cobranças: as instruções devem ser enviadas entre 2 e 10 dias antes da liquidação.
• Cancelamento: até 22h do dia anterior à liquidação.
• Liquidação: janela principal das 00h às 08h. Havendo saldo insuficiente, há nova tentativa entre 18h e 21h.

Retentativa de cobrança recorrente:

POST /v1/cobr/{txid}/retentativa/{data} 

Registra uma nova tentativa de cobrança recorrente para a data informada.

Conciliação avançada

Além dos filtros por período e documento, a consulta GET /pix aceita txIdPresente e devolucaoPresente para refinar o resultado.

Por parametrização a nível de cooperativa, o retorno da conciliação pode incluir dados adicionais do pagador, inclusive nos webhooks:

• Nome do pagador
• Documento do pagador
• Dados bancários do pagador

Essa customização é habilitada pela cooperativa. Consulte o suporte para avaliar a disponibilidade.

Pix Saque e Pix Troco

Para operações de Pix Saque e Pix Troco, o ISPB do facilitador Sicredi é 01181521, informado nos campos:

• retirada.saque.prestadorDoServicoDeSaque
• retirada.troco.prestadorDoServicoDeSaque

Esses campos são enviados no corpo da requisição de cobrança que originar o saque ou o troco.

Próximos passos

Precisa de ajuda?

Suporte técnico e integração: Portal do Desenvolvedor (developer.sicredi.com.br), menu Suporte, Abrir chamado, Suporte Técnico API Pix. Os chamados são atendidos pelo time PJ Tech.

Atendimento ao associado (dúvidas cadastrais e de cooperativa, não para integração da API): 0800 724 7220, WhatsApp (51) 3358 4770.