Integre PIX e Cartão sem depender do painel do cliente.
Esta documentação descreve as rotas públicas da PagPix sob a ótica de quem vai implementar uma integração do zero. O foco aqui é: autenticação, payload, resposta, polling de status, webhooks e exemplos de requisição. Não há orientação comercial nem textos de onboarding de usuário final.
Base URL: https://fastpix.site
As rotas públicas usam credenciais do cliente PagPix, sempre com os campos client_id e client_secret. Não há bearer token próprio da API pública.
- Para POST, envie application/json ou application/x-www-form-urlencoded.
- Para GET, envie os parâmetros na query string.
- Se as credenciais estiverem incorretas, a resposta será 401.
Todas as rotas retornam JSON. Em sucesso, a propriedade success vem como true. Em erro, a propriedade message descreve a falha.
POST https://fastpix.site/v3/pix/qrcode.php
Cria uma transação de entrada e tenta gerar um PIX no gateway configurado para o cliente. O retorno pode vir com copy_paste, com qrcode, ou com ambos. Se vier só copy_paste, considere a cobrança válida.
| Campo | Obrigatório | Descrição |
|---|---|---|
| client_id | Sim | Identificador da integração do cliente. |
| client_secret | Sim | Segredo da integração do cliente. |
| valor | Sim | Valor da cobrança em reais. Aceita decimal. |
| descricao | Não | Descrição exibida/associada à transação. Padrão: Pagamento PIX. |
| nome | Recomendado | Nome do pagador. |
| cpf | Recomendado | CPF/CNPJ do pagador. Também pode ser enviado como documento. |
| Não | Email do pagador. | |
| telefone | Não | Telefone do pagador. |
| webhook_url | Não | URL do seu postback. Alias aceitos: callback_url e postbackUrl. |
| profile_id | Não | Seleciona um profile de integração do cliente, quando a conta usa múltiplos perfis. |
POST https://fastpix.site/v3/pix/payment.php
Cria uma transação de saída usando o saldo da conta do cliente. A resposta já informa fee, debit_total e net_amount. A liquidação final depende do webhook do gateway ou da consulta posterior de status.
| Campo | Obrigatório | Descrição |
|---|---|---|
| client_id | Sim | Identificador da integração. |
| client_secret | Sim | Segredo da integração. |
| valor | Sim | Valor que o recebedor deve receber. |
| chave_pix | Sim* | Chave PIX de destino. Alias aceitos: pix_key e chave. |
| tipo_chave | Sim* | Tipos aceitos: cpf, cnpj, email, telefone, aleatoria. Alias aceito: pix_key_type. |
| documento | Recomendado | Documento do favorecido/solicitante, quando exigido pelo gateway. |
| descricao | Não | Descrição interna do saque. |
| webhook_url | Não | Seu postback para atualização da retirada. |
| profile_id | Não | Profile de integração do cliente. |
GET / POST https://fastpix.site/v3/transactions/status.php
Use esta rota para polling quando você ainda não recebeu o webhook ou quer confirmar o estado consolidado de uma transação local da PagPix.
| Campo | Obrigatório | Descrição |
|---|---|---|
| client_id | Sim | Credencial do cliente. |
| client_secret | Sim | Segredo do cliente. |
| transaction_id | Sim* | ID interno da transação na PagPix. |
| external_id | Sim* | ID externo retornado pelo gateway. Informe este campo quando não tiver o transaction_id. |
GET / POST https://fastpix.site/v3/card/public-key.php
Hoje essa rota só retorna chave quando o adquirente de cartão ativo for PagBank. A resposta deve ser consumida no frontend para criptografar o cartão antes do envio da cobrança.
POST https://fastpix.site/v3/card/charge.php
A rota cria a transação local e repassa a operação ao PagBank. O campo encrypted_card deve ser gerado no navegador do cliente usando a public key obtida na rota anterior.
| Campo | Obrigatório | Descrição |
|---|---|---|
| client_id | Sim | Credencial da integração. |
| client_secret | Sim | Segredo da integração. |
| valor | Sim | Valor da cobrança em reais. Alias aceito: amount. |
| encrypted_card | Sim | Cartão criptografado no frontend. |
| holder_name | Sim | Nome do portador exatamente como no cartão. |
| holder_tax_id | Sim | CPF do portador. |
| parcelas | Não | Número de parcelas de 1 a 12. Alias aceito: installments. |
| nome | Recomendado | Nome do comprador. |
| Recomendado | Email do comprador. | |
| cpf | Recomendado | Documento do comprador. |
| telefone | Não | Telefone do comprador. |
| descricao | Não | Descrição da cobrança. |
Quando você envia webhook_url, callback_url ou postbackUrl na criação de uma transação, a PagPix envia um POST JSON para a sua URL sempre que houver atualização relevante. O payload é padronizado pelo tipo da transação.
Eventos de entrada / cartão
- transaction.pending
- transaction.paid
- transaction.cancelled
Eventos de saída
- withdrawal.pending
- withdrawal.completed
- withdrawal.failed
| HTTP | Quando ocorre |
|---|---|
| 400 | Parâmetros obrigatórios ausentes, como client_id, client_secret ou identificadores da transação. |
| 401 | Credenciais inválidas. |
| 403 | Produto do cliente bloqueado, IP não autorizado ou modo de operação desabilitado. |
| 404 | Usuário ou transação não encontrados. |
| 405 | Método HTTP incompatível com a rota. |
| 422 | Payload inválido, gateway de cartão não suportado na rota, ou falha operacional do adquirente. |
| 502 / 503 | Nenhum gateway compatível disponível ou falha de infraestrutura/configuração. |
- Guarde sempre o transaction_id da PagPix. Ele é a referência primária para polling de status e troubleshooting.
- No PIX, trate copy_paste como suficiente para pagamento. Nem todo gateway retorna uma imagem/base64 do QR.
- No cartão, gere o encrypted_card apenas no frontend. Não envie PAN bruto para o seu backend.
- Use webhook + polling. Webhook resolve o fluxo principal; polling cobre perda de callback ou atraso do gateway.