REST API Confira PIX

Versão: 1.0.0

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.