Registre-se
REST API Confira PIX

Versão: 1.0.0

REST API Confira PIX

Documentação para geração de cobrança e conferencia de transações via PIX.

Todas as solicitações na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://suaempresa.confirapix.com.br. O prefixo /v1/ indica que atualmente nós estamos utilizando a versão 1.0 da API e “suaempresa” será de acordo com o cadastro realizado e disponibilizado para você.

URL HTTP Verb Função
api/v1/transactions GET Listar transações cadastradas
api/v1/transactions POST Criar novas transações
api/v1/transactions/txid/{txid} GET Consultar transações pelo TXID

Todas as respostas são no formato objeto JSON.

Uma requisição bem-sucedida é indicada através do status HTTP. O status 2xx indica sucesso, enquanto os status 4xx indicam falhas. Quando uma requisição falha, o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error. Por exemplo, caso sua autenticação não seja bem-sucedida, será retornada a seguinte mensagem:

				
					{
  "error": "Token inválido, contate o suporte."
}

Autenticação

A credencial de acesso está disponível no cadastro da empresa, contate o suporte para receber o acesso ao painel de controle.

Para as requisições, o corpo da requisição [body] deve ser enviado no formato JSON com o header Content-Type definido para application/json.

A autenticação é realizada através do cabeçalho HTTP (HTTP headers). É necessário o envio do token em Autentication.

Mantenha as credenciais de acesso em segurança. Nunca publique as credenciais de acesso no código fonte do site, aplicativo ou software onde o usuário possa ter fácil acesso.

Notificações

Para que a sua plataforma se mantenha sempre atualizada a Confira PIX disponibiliza as notificações automáticas.

Cada cobrança possui um número único de identificação chamado de UUID, este número deve ser utilizado para recepcionar e identificar a transação para atualizar as informações no seu banco de dados. A chave da cobrança pode sofrer alterações quando emitida em ambiente de contingência.

No momento que realizado a emissão da Cobrança, caso tenha informado o parâmetro url_notification, será enviado o retorno no formato POST para a URL especificada contendo no corpo os parâmetros uuid, status, message, log e data.

Parâmetro Tipo Descrição
uuid string Número único de identificação da cobrança.
status string Status da cobrança: waiting, paid , canceled, refound, expired
motivo string Motivo do status Ex.: Pagamento autorizado pela instituição financeira.
log array Log de retorno da instituição financeira.
data array Informações enviadas para geração da cobrança.
A requisição via POST é realizada no formato x-www-form-urlencoded: 
				
					-X POST \
-header "Content-type: x-www-form-urlencoded" \

Segue exemplo do retorno via POST:

				
					["uuid"] = "43eace5c-8008-4f6c-b830-b6d52d7ff90c",
["status"] = "paid",
["motivo"] = "Pagamento autorizado pela instituição financeira",
["log"] = "[...]"
["data"] = "[...]"

Gerar Cobrança

Para emitir uma Cobrança, envie a requisição no método POST para a URL api/v1/transactions contendo no corpo da requisição os objetos no formato JSON.

				
					curl -X POST \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "42123-1",
    "attendant": "78def425-00c3-4884-9cfd-6bf2607f3445",
    "txid":"E60701190202507051637AY54B41LCQL",
    "amount": 256.45,
  }' \
  https://suaempresa.confirapix.com.br/api/v1/transactions

Segue abaixo exemplo de como gerar uma cobrança:

				
					{
    "account": "42123-1",
    "attendant": "78def425-00c3-4884-9cfd-6bf2607f3445",
    "txid":"E60701190202507051637AY54B41LCQL",
    "amount": 256.45
}
A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos message, transaction. 
				
					{
    "message": "Cobrança PIX gerada com sucesso!",
    "transaction": {
        "uuid":"4567258d-d287-47f2-a46c-a39b81838fc9",
        "txid":"E60701190202507051637AY54B41LCQL",
        "amount":22.04,
        "expires_at":"2025-07-06T00:48:24.000000Z",
        "qrcode":"data:image/png;base64,J21lc3NhZ2UnID0+ICdDb2Jy..."
        "code":"00020126300014BR.GOV.BCB.PIX0114+55119999988885204000053039865405100.005925Nome do Recebedor6009SAO PAULO6207050512345"
}

No momento que realizado a emissão da Cobrança, caso tenha informado o parâmetro url_notification, será enviado o retorno no formato POST para a URL especificada. Saiba mais

Gerar Cobrança

Informações da Cobrança

As Informações de Cobrança possuem todos os campos necessários para a geração de uma Cobrança juntamente com a instituição financeira.

Preencha os campos conforme finalidade da sua cobrança, alguns parâmetros possuem informações adicionais.

Parâmetro Tipo Tamanho Obrigatório Descrição
account string 25 Não Número da conta bancaria, vinculada ao PIX.
Obrigatório apenas quando possuir mais de uma conta bancária.
attendant string 36 Não UUID do atendante cadastrado.
Obrigatório apenas quando possuir mais de um atendente.
txid string 35-35 Não Códido da transação.
O sistema gera automaticamente quando não enviado.
amount decimal 10.2 Sim Valor da cobrança.
url_notification string 250 Não URL de notificação para todas as atualizações da cobrança.

Visualizar Cobrança

Para visualizar uma Cobrança, envie a requisição no método GET para a URL api/v1/transactions/txid/{txid}. 
				
					curl -X POST \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json" \
  https://suaempresa.confirapix.com.br/api/v1/transactions/txid/E60701190202507051637AY54B41LCQL

A resposta do corpo da mensagem será no formato objeto JSON, contendo os seguintes campos: success,message e data.

Parâmetro Tipo Tamanho Descrição
uuid string 36 Identificador único da transação (UUID v4).
Utilizado para correlacionar notificações de retorno.
txid string 35 Identificador da transação no sistema Pix.
Pode ser usado para consultas diretas no PSP.
location_id string/null - URL de localização no provedor do Pix (se houver).
e2eid string 36 Identificador End-to-End definido pelo Bacen.
Usado para rastreamento do pagamento.
status string - Status da transação (ex: paid, waiting, expired,cancelled,refund).
payer_document string/null 11-14 CPF ou CNPJ do pagador (quando informado).
payer_name string/null 255 Nome do pagador (quando informado).
amount decimal 10,2 Valor da transação em reais (R$).
expires_at datetime (ISO 8601) - Data/hora de expiração do QR Code.
paid_at datetime (ISO 8601) - Data/hora em que o pagamento foi confirmado.
payload object - Dados originais da transação conforme enviado ao PSP.
qrcode string (Base64) - Imagem do QR Code em formato Base64 (PNG).
code string - Código EMV do QR Code Pix (linha digitável).
note string/null - Observação associada à transação.
created_at datetime (ISO 8601) - Data/hora de criação do registro.
updated_at datetime (ISO 8601) - Data/hora da última atualização do registro.
attendant object - Informações sobre o atendente vinculado (quando aplicável).
account object - Informações sobre a conta recebedora.
tenant object - Informações do locatário/sistema associado.

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos status, message e data.

				
					{
  "success": true,
  "message": "Transação encontrada.",
  "data": {
    "uuid": "4567258d-d287-47f2-a46c-a39b81838fc9",
    "txid": "E60701190202507051637AY54B41LCQL",
    "location_id": null,
    "e2eid": "E60701190202507051637AY54B41LCQL",
    "status": "paid",
    "payer_document": null,
    "payer_name": null,
    "amount": 22.04,
    "expires_at": "2025-07-06T13:48:24.000000Z",
    "paid_at": "2025-07-06T13:19:42.000000Z",
    "payload": {...},
    "qrcode": "data:image/png;base64,J21lc3NhZ2UnID0+...",
    "code": "00020126300014BR.GOV.BCB.PIX0114+55119999988885204000053039865405100.005925Nome do Recebedor6009SAO PAULO6207050512345",
    "note": null,
    "created_at": "2025-07-06T13:18:24.000000Z",
    "updated_at": "2025-07-06T13:19:45.000000Z",
    "attendant": {...},
    "account": {...},
    "tenant": {...}
  }
}

Infraestrutura

O servidores da Confira PIX estão localizados na região South America (Brazil) com ponto de presença em em North America (USA, MA). Manter a sua estrutura perto de algumas das duas localidades, garante um menor tempo de resposta nas requisições na API.

Utilizamos uma infraestrutura na Amazon AWS de alta disponibilidade e Cloudflare e para alguns serviços como redundância Hostinger Cloud, o que significa que ao se comunicar com API da Confira PIX a requisição será redirecionada para o servidor mais próximo da sua localidade.

O retorno via POST na url_notification é enviado diretamente dos servidores da Confira PIX. 

Todos os arquivos sensíveis são armazenados na Amazon S3 que garante 99,999999999% de durabilidade dos arquivos e criptografia de ponta a ponta, seguindo critérios rígidos de segurança e controle interno.

Limite de requisições

API da Confira PIX é protegida por um firewall que identifica de forma automática os acessos indevidos, suspeitos, credenciais incorretas e a localização da requisição, onde também pode limitar solicitações por segundo e o total de requisições para evitar o mal uso da API e a sobrecarga dos servidores. O uso indevido da API pode gerar mensagens de erro 503 ou 403 no retorno do cabeçalho da requisição. Segue abaixo especificações para uma correta integração:

  • Localização do servidor: O firewall bloqueia por padrão o IP de servidores suspeitos ou de baixa reputação. Caso a sua comunicação via GET e retorne 403 Erro Forbidden por engano, por favor, entre em contato para liberarmos o IP do seu servidor.
  • Limite de requisições:
    – GET: 2.500 requisições a cada 5 minutos (15/reqs/s).
    – POST/PUT/DELETE: 10.000 requisições a cada 5 minutos (30/reqs/s).
    Precisa de um volume maior de requisições? Por favor, entre em contato para liberação.
  • Credenciais de acesso: Os endpoints exigem as credenciais de acesso válida e correta na HEADER da requisição, o envio incorreto é atribuído como uso indevido da API.
  • URL de notificação: Realize a integração para obter todos os retornos da API via URL de notificação, dessa forma todos os processos podem ser realizados ao receber o retorno, como atualizar o banco de dados.

 

ATENÇÃO: Os valores acimas são aproximados, podendo variar para mais ou para menos, em caso de dúvidas ou problemas, contatar o suporte.