API Pix Sicredi

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 requisições REST. Ela permite que associados PJ automatizem o recebimento com liquidação imediata, 24 horas por dia, todos os dias do ano: você gerencia cobranças imediatas, cobranças com vencimento e cobranças recorrentes (Pix Automático), consulta Pix recebidos, solicita devoluções e configura webhooks para notificação em tempo real. A autenticação combina mTLS e OAuth2 (client_credentials), e a API segue integralmente a especificação do Bacen (Manual de Padrões para Iniciação do Pix), 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

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. Todo o ciclo de certificado e credenciais é feito no Portal do Desenvolvedor (developer.sicredi.com.br).

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 em 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'

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.

Resposta esperada:

{

  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",

  "token_type": "bearer",

  "expires_in": 3599,

  "scope": "cob.read cob.write webhook.read webhook.write",

  "jti": "9569d3a5-7725-4c23-b055-4f8901096644"

}

2. Criar cobrança imediata (COB)

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

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 serviço X"
  }'

Parâmetros (path):

• txid (string, obrigatório): identificador da transação, definido por você. Alfanumérico, de 26 a 35 caracteres (^[a-zA-Z0-9]35$), único por CPF/CNPJ recebedor

Parâmetros (body):

• calendario.expiracao (inteiro, obrigatório): tempo de expiração da cobrança, em segundos
• valor.original (string, obrigatório): valor da cobrança, no formato decimal com ponto (ex.: 100.00)
• chave (string, obrigatório): chave Pix recebedora, cadastrada no Sicredi
• devedor.cnpj ou devedor.cpf (string, opcional): documento do devedor
• devedor.nome (string, opcional): nome do devedor
• solicitacaoPagador (string, opcional): texto exibido ao pagador
• valor.modalidadeAlteracao (inteiro, opcional): 0 trava a alteração de valor pelo pagador; 1 permite

Escopo exigido: cob.write.

Resposta esperada (201 Created):

{
  "calendario": { "criacao": "2026-06-24T15:20:50.337Z", "expiracao": 3600 },
  "txid": "SEU_TXID",
  "revisao": 0,
  "status": "ATIVA",
  "devedor": { "cnpj": "12345678000195", "nome": "Empresa Exemplo SA" },
  "valor": { "original": "100.00" },
  "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
  "pixCopiaECola": "00020126...",
  "location": "pix.sicredi.com.br/qr/v2/..."
}

3. Consultar cobrança

Verifique o status de uma cobrança com GET /cob/{txid}:

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

Parâmetros (path):

• txid (string, obrigatório): identificador da cobrança a consultar

Escopo exigido: cob.read.

Resposta esperada (200 OK):

{
  "txid": "SEU_TXID",
  "status": "CONCLUIDA",
  "valor": { "original": "100.00" },
  "pix": [
    {
      "endToEndId": "E12345678202606241520abcdef12345",
      "txid": "SEU_TXID",
      "valor": "100.00",
      "horario": "2026-06-24T15:25:59.411Z"
    }
  	]
}

Quando a cobrança é paga, o status passa a CONCLUIDA e o array pix traz o recebimento correspondente, com endToEndId e horario.

4. Configurar webhook (opcional)

Receba notificações automáticas quando um Pix for recebido, com PUT /webhook/{chave}:

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

Parâmetros (path):

• chave (string, obrigatório): chave Pix para a qual o webhook será registrado

Parâmetros (body):

• webhookUrl (string, obrigatório): endpoint HTTPS que receberá as notificações

Escopo exigido: webhook.write.

5. Consultar Pix recebido

Consulte um Pix específico pelo EndToEndId, com GET /pix/{e2eid}:

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

Parâmetros (path):

• e2eid (string, obrigatório): EndToEndId do Pix a consultar

Escopo exigido: pix.read.

Resposta esperada (200 OK):

{
  "endToEndId": "E12345678202606241520abcdef12345",
  "txid": "SEU_TXID",
  "valor": "100.00",
  "horario": "2026-06-24T15:25:59.411Z",
  "infoPagador": "Pagamento do serviço X"
}

Retorna os dados de um único recebimento. O txid associa o Pix à cobrança que o originou, quando houver.

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

Para conciliar os recebimentos, liste os Pix recebidos em um intervalo de tempo com GET /pix. Os parâmetros inicio e fim são obrigatórios e seguem o formato RFC 3339:

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' \
  -H '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 (string, opcional): filtra pelo documento do pagador; não podem ser enviados juntos
• paginacao.paginaAtual (inteiro, opcional): página solicitada
• paginacao.itensPorPagina (inteiro, opcional): itens por página

Escopo exigido: pix.read.

Resposta esperada (200 OK):

{
  "parametros": {
    "inicio": "2026-06-01T00:00:00Z",
    "fim": "2026-06-01T23:59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 1
    }
  },
  "pix": [
    {
      "endToEndId": "E12345678202606241520abcdef12345",
      "txid": "SEU_TXID",
      "valor": "100.00",
      "horario": "2026-06-01T15:25:59.411Z"
    }
  ]
}

7. Tratamento de erros

A API Pix segue o padrão de erros do Bacen (RFC 7807, application/problem+json). O corpo de erro traz os campos type, title, status, detail e, quando aplicável, violacoes com o detalhamento por campo.

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, e escolha o motivo de contato. 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