Documentação da API de PIX

Visão geral

A API de PIX cadastra carteiras bancárias do emitente e cria cobranças PIX (instantâneo ou com vencimento). O banco da cobrança vem da carteira informada em carteira_id.

GET/pix/bancosLista os bancos com integração PIX e os campos exigidos.

GET/pix/carteirasLista as carteiras PIX do emitente.

POST/pix/carteirasCadastra uma carteira PIX.

GET/pix/carteiras/{id}Consulta uma carteira pelo id.

POST/pix/carteiras/{id}Atualiza nome, banco ou autenticação.

POST/pix/carteiras/{id}/ativarAtiva a carteira.

POST/pix/carteiras/{id}/inativarInativa a carteira.

POST/pix/carteiras/{id}/excluirExclui a carteira.

GET/pix/cobrancasLista as cobranças PIX do emitente.

POST/pix/cobrancasCria uma cobrança PIX instantânea ou com vencimento no banco da carteira.

GET/pix/cobrancas/{id}Consulta a cobrança pelo id ou pela identificação.

POST/pix/cobrancas/{id}/devolucaoSolicita devolução total ou parcial de um PIX pago.

GET/pix/cobrancas/{id}/devolucao/{devolucao_id}Consulta o status de uma devolução no banco.

POST/pix/carteiras/{id}/webhookCadastra a URL do seu sistema para ser avisado quando o PIX for pago.

GET/pix/carteiras/{id}/webhookConsulta sua URL de notificação e se o recebimento automático está ativo.

Emissão no banco implementada para Banco do Brasil e Sicredi (Pix Bacen v2): PUT /cob/{txid} e PUT /cobv/{txid}, com OAuth2 + mTLS.

Testar

Cole a chave do emitente e envie a requisição nesta página. A chave fica neste navegador e segue somente para a API, no header Authorization.

Chave do emitente

Requisição

Corpo JSON

GET

—

Autenticação

Use a chave do emitente, a que começa com apse_. A chave geral da conta não autoriza estas rotas.

Authorization: Bearer apse_sua_chave_do_emitente
Content-Type: application/json
Accept: application/json

Sem chave, ou com chave inválida, a resposta é HTTP 401. Conta inativa ou emitente sem PIX habilitado responde HTTP 403.

Habilitação

No painel, o emitente precisa ter o PIX ligado. Sem isso, qualquer rota /pix/* responde pix_desabilitado.

As carteiras também podem ser cadastradas pelo painel em Carteiras, com upload de certificados quando o banco exigir.

Listar bancos

GEThttps://api.apisimples.com/v1/pix/bancos

Devolve o catálogo de bancos com integração PIX e a lista de campos de autenticacao de cada um.

curl https://api.apisimples.com/v1/pix/bancos \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Accept: application/json"

{
    "bancos": [
        {
            "codigo": "001",
            "nome": "Banco do Brasil",
            "campos": [
                "client_id",
                "client_secret",
                "id_aplicacao",
                "chave_pix",
                "ambiente",
                "certificado_chave_publica",
                "certificado_chave_privada"
            ],
            "opcionais": [],
            "rotulos": {
                "client_id": "Client ID",
                "client_secret": "Client secret",
                "id_aplicacao": "ID da aplicação",
                "chave_pix": "Chave PIX",
                "ambiente": "Ambiente",
                "certificado_chave_publica": "Certificado (.pem / .cer)",
                "certificado_chave_privada": "Chave privada (.key)"
            }
        },
        {
            "codigo": "033",
            "nome": "Santander",
            "campos": [
                "client_id",
                "client_secret",
                "certificado_chave_publica",
                "certificado_chave_privada"
            ],
            "opcionais": [],
            "rotulos": {
                "client_id": "Client ID",
                "client_secret": "Client secret",
                "certificado_chave_publica": "Certificado (.pem / .cer)",
                "certificado_chave_privada": "Chave privada (.key)"
            }
        },
        {
            "codigo": "077",
            "nome": "Inter",
            "campos": [
                "client_id",
                "client_secret",
                "certificado_chave_publica",
                "certificado_chave_privada"
            ],
            "opcionais": [],
            "rotulos": {
                "client_id": "Client ID",
                "client_secret": "Client secret",
                "certificado_chave_publica": "Certificado (.pem / .cer)",
                "certificado_chave_privada": "Chave privada (.key)"
            }
        },
        {
            "codigo": "341",
            "nome": "Itaú",
            "campos": [
                "client_id",
                "client_secret",
                "certificado_chave_publica",
                "certificado_chave_privada"
            ],
            "opcionais": [],
            "rotulos": {
                "client_id": "Client ID",
                "client_secret": "Client secret",
                "certificado_chave_publica": "Certificado (.pem / .cer)",
                "certificado_chave_privada": "Chave privada (.key)"
            }
        },
        {
            "codigo": "364",
            "nome": "Efí",
            "campos": [
                "client_id",
                "client_secret",
                "certificado"
            ],
            "opcionais": [],
            "rotulos": {
                "client_id": "Client ID",
                "client_secret": "Client secret",
                "certificado": "Certificado"
            }
        },
        {
            "codigo": "461",
            "nome": "Asaas",
            "campos": [
                "client_secret"
            ],
            "opcionais": [],
            "rotulos": {
                "client_secret": "Client secret"
            }
        },
        {
            "codigo": "748",
            "nome": "Sicredi",
            "campos": [
                "client_id",
                "client_secret",
                "chave_pix",
                "ambiente",
                "certificado_chave_publica",
                "certificado_chave_privada"
            ],
            "opcionais": [
                "certificado_senha",
                "oauth_url",
                "api_url"
            ],
            "rotulos": {
                "client_id": "Client ID",
                "client_secret": "Client secret",
                "chave_pix": "Chave PIX",
                "ambiente": "Ambiente",
                "certificado_chave_publica": "Certificado (.pem / .cer)",
                "certificado_chave_privada": "Chave privada (.key)",
                "certificado_senha": "Senha da chave privada",
                "oauth_url": "URL OAuth (homologação)",
                "api_url": "URL da API (homologação)"
            }
        },
        {
            "codigo": "756",
            "nome": "Sicoob",
            "campos": [
                "client_id",
                "certificado_chave_publica",
                "certificado_chave_privada"
            ],
            "opcionais": [],
            "rotulos": {
                "client_id": "Client ID",
                "certificado_chave_publica": "Certificado (.pem / .cer)",
                "certificado_chave_privada": "Chave privada (.key)"
            }
        }
    ]
}

Listar carteiras

GEThttps://api.apisimples.com/v1/pix/carteiras

Lista as carteiras PIX do emitente autenticado, da mais recente para a mais antiga.

curl https://api.apisimples.com/v1/pix/carteiras \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Accept: application/json"

{
    "carteiras": [
        {
            "id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
            "tipo": "pix",
            "codigo_banco": "461",
            "banco": "Asaas",
            "nome": "Conta principal",
            "status": "ativa",
            "campos": [
                "client_secret"
            ],
            "autenticacao": {
                "client_id": null,
                "client_secret": "***",
                "certificado_chave_publica": false,
                "certificado_chave_privada": false
            },
            "criado_em": "2026-10-17 13:00:00",
            "atualizado_em": "2026-10-17 13:00:00"
        }
    ]
}

Criar

POSThttps://api.apisimples.com/v1/pix/carteiras

HTTP 201 devolve a carteira criada. Certificados devem ir em base64. Segredos voltam mascarados; certificados voltam como booleano (cadastrado ou não).

A chave_pix do recebedor vai em autenticacao.chave_pix (BB e Sicredi). A API grava na coluna chave_pix da carteira e usa essa chave em toda cobrança e no webhook do banco. Não envie a chave de novo em POST /pix/cobrancas.

{
    "nome": "Conta principal",
    "codigo_banco": "461",
    "autenticacao": {
        "client_secret": "seu-client-secret"
    }
}

{
    "nome": "PIX Banco do Brasil",
    "codigo_banco": "001",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret",
        "id_aplicacao": "d27b477108ffabf2136be18d80050f56b9a1a5b6",
        "chave_pix": "12345678000199",
        "ambiente": "homologacao",
        "certificado_chave_publica": "base64-do-certificado-publico",
        "certificado_chave_privada": "base64-do-certificado-privado"
    }
}

{
    "nome": "PIX Sicredi",
    "codigo_banco": "748",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret",
        "chave_pix": "recebedor@empresa.com.br",
        "ambiente": "homologacao",
        "certificado_chave_publica": "base64-do-certificado-publico",
        "certificado_chave_privada": "base64-do-certificado-privado"
    }
}

curl -X POST https://api.apisimples.com/v1/pix/carteiras \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "nome": "Conta principal",
    "codigo_banco": "461",
    "autenticacao": {
        "client_secret": "seu-client-secret"
    }
}'

{
    "id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "tipo": "pix",
    "codigo_banco": "461",
    "banco": "Asaas",
    "nome": "Conta principal",
    "status": "ativa",
    "campos": [
        "client_secret"
    ],
    "autenticacao": {
        "client_id": null,
        "client_secret": "***",
        "certificado_chave_publica": false,
        "certificado_chave_privada": false
    },
    "criado_em": "2026-10-17 13:00:00",
    "atualizado_em": "2026-10-17 13:00:00"
}

Consultar

GEThttps://api.apisimples.com/v1/pix/carteiras/{id}

Consulta uma carteira pelo UUID. Se não for deste emitente, a resposta é HTTP 404.

Atualizar

POSThttps://api.apisimples.com/v1/pix/carteiras/{id}

Atualização parcial: envie só o que mudou. Em branco, os segredos e certificados atuais são mantidos. A carteira precisa continuar com todos os campos exigidos pelo banco.

{
    "nome": "Conta principal",
    "autenticacao": {
        "client_secret": "novo-client-secret"
    }
}

Ativar / inativar

POSThttps://api.apisimples.com/v1/pix/carteiras/{id}/ativar

POSThttps://api.apisimples.com/v1/pix/carteiras/{id}/inativar

Altera o status entre ativa e inativa. Não exige corpo.

Excluir carteira

POSThttps://api.apisimples.com/v1/pix/carteiras/{id}/excluir

Remove a carteira de forma permanente. HTTP 200 confirma com excluida: true.

Listar cobranças

GEThttps://api.apisimples.com/v1/pix/cobrancas

Lista as cobranças PIX do emitente. Opcionalmente filtre com ?tipo=pix_instantaneo ou ?tipo=pix_vencimento.

Criar cobrança

POSThttps://api.apisimples.com/v1/pix/cobrancas

Informe o carteira_id (não o código do banco). O tipo define as regras:

pix_instantaneo — pagador opcional; data_vencimento opcional.
pix_vencimento — exige data_vencimento e pagador com nome e CPF ou CNPJ.

HTTP 201 cria a cobrança no banco da carteira e grava a resposta. A cobrança volta com status ativa, txid, copia_cola (pixCopiaECola), location (quando o banco informar) e qr_code em base64 PNG gerado na hora — a imagem não é gravada no banco.

No PIX instantâneo, pagamento.expiracao é opcional (padrão 86400 segundos). No PIX com vencimento, pagamento.validade_apos_vencimento é opcional (padrão 30 dias).

{
    "carteira_id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "tipo": "pix_instantaneo",
    "identificacao": "ID-001",
    "pagamento": {
        "valor": "10.00"
    },
    "info_add": [
        {
            "nome": "Campo 1",
            "valor": "Informação Adicional1 do PSP-Recebedor"
        }
    ]
}

{
    "carteira_id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "tipo": "pix_vencimento",
    "identificacao": "ID-002",
    "pagamento": {
        "valor": "10.00",
        "data_vencimento": "2026-10-22"
    },
    "pagador": {
        "cpf": "39053344705",
        "nome": "Nome Exemplo"
    },
    "info_add": [
        {
            "nome": "Campo 1",
            "valor": "Informação Adicional1 do PSP-Recebedor"
        }
    ]
}

curl -X POST https://api.apisimples.com/v1/pix/cobrancas \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "carteira_id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "tipo": "pix_instantaneo",
    "identificacao": "ID-001",
    "pagamento": {
        "valor": "10.00"
    },
    "info_add": [
        {
            "nome": "Campo 1",
            "valor": "Informação Adicional1 do PSP-Recebedor"
        }
    ]
}'

{
    "id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
    "tipo": "pix_instantaneo",
    "identificacao": "ID-001",
    "status": "ativa",
    "carteira_id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "codigo_banco": "001",
    "banco": "Banco do Brasil",
    "pagamento": {
        "valor": "10.00",
        "data_vencimento": null
    },
    "pagador": null,
    "info_add": [
        {
            "nome": "Campo 1",
            "valor": "Informação Adicional1 do PSP-Recebedor"
        }
    ],
    "txid": "7978c0c97ea847e78e8849634473c1f1",
    "location": "pixqrcode.sicredi.com.br/qr/v2/5eeb79db9f2b4a939adaca8d2f8a4cc9",
    "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
    "copia_cola": "00020101021226860014br.gov.bcb.pix2564pixqrcode.sicredi.com.br/qr/v2/5eeb79db...",
    "end_to_end_id": null,
    "criado_em": "2026-10-17 14:00:00",
    "atualizado_em": "2026-10-17 14:00:00"
}

Consultar cobrança

GEThttps://api.apisimples.com/v1/pix/cobrancas/{id}

GEThttps://api.apisimples.com/v1/pix/cobrancas/{identificacao}

Consulta pelo UUID ou pela identificacao informada na criação.

Devolver PIX

Disponível para cobranças paga ou parcialmente_devolvida que já tenham end_to_end_id. A API chama o PSP com o padrão Bacen PUT /pix/{e2eid}/devolucao/{id} (BB e Sicredi).

POSThttps://api.apisimples.com/v1/pix/cobrancas/{id}/devolucao

GEThttps://api.apisimples.com/v1/pix/cobrancas/{id}/devolucao/{devolucao_id}

Sem valor, devolve o saldo restante. natureza padrão: ORIGINAL. O id da devolução é opcional (a API gera se omitido). Na consulta pelo console, use {cobranca_id}/{devolucao_id} no campo de id.

curl -X POST https://api.apisimples.com/v1/pix/cobrancas/{id}/devolucao \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Content-Type: application/json" \
  -d '{"valor":"10.00","natureza":"ORIGINAL","descricao":"Devolução solicitada pelo recebedor"}'

{
    "valor": "10.00",
    "natureza": "ORIGINAL",
    "descricao": "Devolução solicitada pelo recebedor",
    "id": "dev001"
}

Payload da cobrança

Corpo de POST /pix/cobrancas.

Campos do payload

CampoDescrição

carteira_id

stringobrigatório

UUID da carteira PIX ativa do emitente.

O banco e as credenciais vêm desta carteira.

tipo

stringobrigatório

Modalidade da cobrança.

pix_instantaneo
pix_vencimento

identificacao

stringobrigatório

Referência única no seu sistema.

Até 80 caracteres. Única por emitente e tipo.

pagamento

objectobrigatório

Dados do valor e, quando houver, do vencimento.

valor

stringobrigatório

Valor da cobrança.

Ex.: 10.00

data_vencimento

stringcondicional

Data no formato AAAA-MM-DD.

Obrigatória em pix_vencimento. Opcional em pix_instantaneo.

expiracao

integeropcional

Validade do PIX instantâneo em segundos.

Padrão 86400.

validade_apos_vencimento

integeropcional

Dias em que o PIX com vencimento ainda pode ser pago após a data.

Padrão 30.

solicitacao_pagador

stringopcional

Texto apresentado ao pagador.

Até 140 caracteres.

pagador

objectcondicional

Dados do pagador. Obrigatório em pix_vencimento. Opcional em pix_instantaneo.

Informe CPF ou CNPJ, não os dois.

nome

stringcondicional

Nome do pagador.

Obrigatório quando pagador é exigido.

cpf

stringcondicional

CPF com 11 dígitos.

Sem máscara ou com máscara.

cnpj

stringcondicional

CNPJ com 14 dígitos.

Sem máscara ou com máscara.

info_add

arrayopcional

Informações adicionais enviadas ao PSP.

Até 50 itens.

nome

stringobrigatório

Nome do campo adicional.

Até 50 caracteres.

valor

stringobrigatório

Valor do campo adicional.

Até 200 caracteres.

Webhook

O recebimento do pagamento no banco é configurado automaticamente pela API (por carteira). Você só informa, se quiser, a URL do seu sistema para ser avisado quando a cobrança ficar paga. A URL interna do banco não é exposta.

POSThttps://api.apisimples.com/v1/pix/carteiras/{id}/webhook

GEThttps://api.apisimples.com/v1/pix/carteiras/{id}/webhook

recebimento_ativo indica se o aviso automático do banco está ok. Envie {"url": null} para remover só a URL do seu sistema.

curl -X POST https://api.apisimples.com/v1/pix/carteiras/{id}/webhook \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://meusite.com/webhooks/pix"}'

curl https://api.apisimples.com/v1/pix/carteiras/{id}/webhook \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Accept: application/json"

{
    "carteira_id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "url": "https://meusite.com/webhooks/pix",
    "recebimento_ativo": true
}

{
    "evento": "cobranca.paga",
    "carteira_id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "cobranca": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "paga",
        "txid": "7978c0c97ea847e78e8849634473c1f1",
        "end_to_end_id": "E18236120202009091221s073512888"
    },
    "pix": {
        "endToEndId": "E18236120202009091221s073512888",
        "txid": "7978c0c97ea847e78e8849634473c1f1",
        "valor": "10.00",
        "horario": "2026-10-17T14:15:00.358Z"
    }
}

Payload da carteira

Corpo usado em POST /pix/carteiras e, em parte, em POST /pix/carteiras/{id}.

Campos do payload

CampoDescrição

nome

stringopcional

Apelido da carteira no seu sistema.

Até 80 caracteres.

codigo_banco

stringobrigatório

Código do banco da integração PIX.

Aceita com ou sem zeros à esquerda (001 ou 1).

001 — Banco do Brasil
033 — Santander
077 — Inter
341 — Itaú
364 — Efí
461 — Asaas
748 — Sicredi
756 — Sicoob

autenticacao

objectobrigatório

Credenciais exigidas pelo banco escolhido. Os campos mudam conforme codigo_banco.

Veja a seção Campos por banco. Em BB e Sicredi, autenticacao.chave_pix é obrigatória e fica gravada na carteira.

Campos por banco

autenticacao.chave_pix

stringcondicional

Chave PIX do recebedor (CPF, CNPJ, e-mail, telefone ou EVP). Obrigatória nos bancos que listam o campo.

Informada na carteira; a cobrança só envia carteira_id. Persistida na coluna chave_pix.

Criar carteira

Campos por banco

O objeto autenticacao muda conforme o banco. Use GET /pix/bancos para obter a lista atualizada pela API.

001 — Banco do Brasil

Campos do payload

CampoDescrição

client_id

stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

client_secret

stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

id_aplicacao

stringobrigatório

Identificador da aplicação no Banco do Brasil (developer application key / gw-dev-app-key).

chave_pix

stringobrigatório

Chave PIX do recebedor no DICT (CPF, CNPJ, e-mail, telefone ou EVP). Gravada na coluna chave_pix da carteira e usada em toda cobrança e webhook.

ambiente

stringobrigatório

homologacao ou producao. Em homologação Sicredi a URL pode ser a informada pela equipe do banco.

certificado_chave_publica

string (base64)obrigatório

Sicredi: Certificado Validado do Portal (.pem ou .cer). Não use certificado A1 nem .p12. O Client ID/Secret precisa ter sido gerado sobre este certificado.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

certificado_chave_privada

string (base64)obrigatório

Sicredi: Chave Privada Sem Senha do Portal (.key), da mesma CSR do certificado. Se o .key tiver senha, use certificado_senha.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

{
    "codigo_banco": "001",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret",
        "id_aplicacao": "d27b477108ffabf2136be18d80050f56b9a1a5b6",
        "chave_pix": "recebedor@empresa.com.br",
        "ambiente": "homologacao",
        "certificado_chave_publica": "conteudo-do-certificado-em-base64",
        "certificado_chave_privada": "conteudo-do-certificado-em-base64"
    }
}

033 — Santander

Campos do payload

CampoDescrição

client_id

stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

client_secret

stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

certificado_chave_publica

string (base64)obrigatório

Sicredi: Certificado Validado do Portal (.pem ou .cer). Não use certificado A1 nem .p12. O Client ID/Secret precisa ter sido gerado sobre este certificado.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

certificado_chave_privada

string (base64)obrigatório

Sicredi: Chave Privada Sem Senha do Portal (.key), da mesma CSR do certificado. Se o .key tiver senha, use certificado_senha.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

{
    "codigo_banco": "033",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret",
        "certificado_chave_publica": "conteudo-do-certificado-em-base64",
        "certificado_chave_privada": "conteudo-do-certificado-em-base64"
    }
}

077 — Inter

Campos do payload

CampoDescrição

client_id

stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

client_secret

stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

certificado_chave_publica

string (base64)obrigatório

Sicredi: Certificado Validado do Portal (.pem ou .cer). Não use certificado A1 nem .p12. O Client ID/Secret precisa ter sido gerado sobre este certificado.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

certificado_chave_privada

string (base64)obrigatório

Sicredi: Chave Privada Sem Senha do Portal (.key), da mesma CSR do certificado. Se o .key tiver senha, use certificado_senha.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

{
    "codigo_banco": "077",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret",
        "certificado_chave_publica": "conteudo-do-certificado-em-base64",
        "certificado_chave_privada": "conteudo-do-certificado-em-base64"
    }
}

341 — Itaú

Campos do payload

CampoDescrição

client_id

stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

client_secret

stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

certificado_chave_publica

string (base64)obrigatório

Sicredi: Certificado Validado do Portal (.pem ou .cer). Não use certificado A1 nem .p12. O Client ID/Secret precisa ter sido gerado sobre este certificado.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

certificado_chave_privada

string (base64)obrigatório

Sicredi: Chave Privada Sem Senha do Portal (.key), da mesma CSR do certificado. Se o .key tiver senha, use certificado_senha.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

{
    "codigo_banco": "341",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret",
        "certificado_chave_publica": "conteudo-do-certificado-em-base64",
        "certificado_chave_privada": "conteudo-do-certificado-em-base64"
    }
}

364 — Efí

Campos do payload

CampoDescrição

client_id

stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

client_secret

stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

certificado

string (base64)obrigatório

Certificado do banco em base64 (arquivo único, usado por Efí).

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

{
    "codigo_banco": "364",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret",
        "certificado": "conteudo-do-certificado-em-base64"
    }
}

461 — Asaas

Campos do payload

CampoDescrição

client_secret

stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

{
    "codigo_banco": "461",
    "autenticacao": {
        "client_secret": "seu-client-secret"
    }
}

748 — Sicredi

OAuth2 + mTLS. No Portal, baixe o Certificado Validado (.pem ou .cer) e a Chave Privada Sem Senha (.key) da mesma CSR; depois gere o Client ID/Secret sobre esse certificado. HTTP 401 costuma ser credencial de outro certificado ou ambiente trocado (sua chamada atual foi para produção). Não use certificado A1. Em homologação, use oauth_url e api_url da liberação.

Campos do payload

CampoDescrição

client_id

stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

client_secret

stringobrigatório

Segredo OAuth do aplicativo. Na resposta aparece mascarado.

chave_pix

stringobrigatório

Chave PIX do recebedor no DICT (CPF, CNPJ, e-mail, telefone ou EVP). Gravada na coluna chave_pix da carteira e usada em toda cobrança e webhook.

ambiente

stringobrigatório

homologacao ou producao. Em homologação Sicredi a URL pode ser a informada pela equipe do banco.

certificado_chave_publica

string (base64)obrigatório

Sicredi: Certificado Validado do Portal (.pem ou .cer). Não use certificado A1 nem .p12. O Client ID/Secret precisa ter sido gerado sobre este certificado.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

certificado_chave_privada

string (base64)obrigatório

Sicredi: Chave Privada Sem Senha do Portal (.key), da mesma CSR do certificado. Se o .key tiver senha, use certificado_senha.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

certificado_senha

stringopcional

Senha da chave .key, só se não for a versão “sem senha” do Portal.

oauth_url

stringopcional

Opcional. URL completa do POST /oauth/token informada pelo Sicredi na liberação de homologação.

api_url

stringopcional

Opcional. URL base da API (…/api/v2) informada pelo Sicredi na liberação de homologação.

{
    "codigo_banco": "748",
    "autenticacao": {
        "client_id": "seu-client-id",
        "client_secret": "seu-client-secret",
        "chave_pix": "recebedor@empresa.com.br",
        "ambiente": "homologacao",
        "certificado_chave_publica": "conteudo-do-certificado-em-base64",
        "certificado_chave_privada": "conteudo-do-certificado-em-base64"
    }
}

756 — Sicoob

Campos do payload

CampoDescrição

client_id

stringobrigatório

Identificador OAuth do aplicativo cadastrado no banco.

certificado_chave_publica

string (base64)obrigatório

Sicredi: Certificado Validado do Portal (.pem ou .cer). Não use certificado A1 nem .p12. O Client ID/Secret precisa ter sido gerado sobre este certificado.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

certificado_chave_privada

string (base64)obrigatório

Sicredi: Chave Privada Sem Senha do Portal (.key), da mesma CSR do certificado. Se o .key tiver senha, use certificado_senha.

Envie o conteúdo do arquivo em base64. No painel, use o upload de arquivo.

{
    "codigo_banco": "756",
    "autenticacao": {
        "client_id": "seu-client-id",
        "certificado_chave_publica": "conteudo-do-certificado-em-base64",
        "certificado_chave_privada": "conteudo-do-certificado-em-base64"
    }
}

Formato da resposta

Segredos voltam mascarados. Certificados voltam como true ou false, sem o conteúdo.

Campos do payload

CampoDescrição

id

stringobrigatório

UUID da carteira.

tipo

stringobrigatório

Sempre pix nesta API.

codigo_banco

stringobrigatório

Código do banco com 3 dígitos.

Ex.: 001, 033, 461.

banco

stringobrigatório

Nome do banco da integração.

nome

string|nullopcional

Apelido da carteira.

status

stringobrigatório

ativa ou inativa.

campos

arrayobrigatório

Lista dos campos de autenticação exigidos por este banco.

autenticacao

objectobrigatório

Credenciais mascaradas ou indicadores de certificado.

criado_em

stringobrigatório

Data e hora de criação.

atualizado_em

stringobrigatório

Data e hora da última alteração.

{
    "id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "tipo": "pix",
    "codigo_banco": "461",
    "banco": "Asaas",
    "nome": "Conta principal",
    "status": "ativa",
    "campos": [
        "client_secret"
    ],
    "autenticacao": {
        "client_id": null,
        "client_secret": "***",
        "certificado_chave_publica": false,
        "certificado_chave_privada": false
    },
    "criado_em": "2026-10-17 13:00:00",
    "atualizado_em": "2026-10-17 13:00:00"
}

Erros

Toda resposta de erro traz codigo e mensagem. Em validação, a lista erros aponta o campo.

HTTP	Código	Quando
400	json_invalido	O corpo não é um objeto JSON.
401	autenticacao_ausente	O header Authorization não veio.
401	autenticacao_invalida	A chave do emitente não existe.
403	conta_inativa	A conta está inativa.
403	pix_desabilitado	O emitente não tem PIX habilitado.
404	carteira_nao_encontrada	A carteira não é deste emitente.
404	cobranca_nao_encontrada	A cobrança não é deste emitente.
404	rota_nao_encontrada	A rota não existe.
409	cobranca_duplicada	Já existe cobrança com a mesma identificação neste tipo.
422	validacao	Um ou mais campos foram recusados.
422	banco_nao_suportado	O código do banco ainda não tem integração PIX.
422	banco_nao_implementado	A emissão ou o webhook deste banco ainda não foi implementado.
422	cobranca_nao_paga	Devolução só é permitida em cobrança paga ou parcialmente_devolvida.
422	end_to_end_ausente	A cobrança ainda não tem end_to_end_id do pagamento.
422	valor_indisponivel	O valor pedido excede o saldo ainda não devolvido.
422	banco_recusou	O banco recusou a cobrança ou o webhook.
422	carteira_incompleta	Faltam credenciais ou certificados na carteira.
422	campo_invalido	Status inválido, filtro inválido ou falta campo obrigatório.
502	banco_oauth	Erro na autenticação com o banco.
502	banco_indisponivel	O banco não respondeu à requisição.
500	gravacao	A carteira ou a cobrança não pôde ser gravada.

{
    "codigo": "validacao",
    "mensagem": "Confira os campos da carteira.",
    "erros": [
        {
            "campo": "autenticacao.client_secret",
            "mensagem": "Campo obrigatório."
        }
    ]
}