Visão Geral

A API do FrostPay permite integrar pagamentos via PIX, boleto e saques em sua plataforma de forma simples e segura.


🌐 Base URL: https://www.payfrost.com.br

📦 Formato: JSON

🔤 Charset: UTF-8

⏱️ Timeout: 30 segundos

🏦 Múltiplas Adquirentes: Suporte com fallback automático

⚠️ Ambiente Único

Atualmente a API opera apenas em ambiente de produção. Todas as transações são reais e geram cobranças efetivas.

🔑 Chaves de Teste: Não há ambiente de homologação. Utilize valores baixos (ex: R$ 1,00) para testes.

Fluxo Básico

1. Gerar credenciais no painel → Chaves API 2. Autenticar com Client-ID + Client-Secret 3. Criar transação PIX ou boleto 4. Cliente paga 5. Webhook notifica confirmação com status 6. Consultar status quando necessário

Autenticação

Inclua suas credenciais nos headers HTTP de todas as requisições:

X-Frost-Client-ID: seu_client_id X-Frost-Client-Secret: seu_client_secret

Onde obter: Painel → Chaves API

Segurança: Nunca compartilhe seu Client Secret. Mantenha-o em variáveis de ambiente.

Testar Autenticação

curl -X GET https://www.payfrost.com.br/api/v1/autenticar \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret"

✅ Resposta de Sucesso

{ "success": true, "user": { "id": 123, "name": "João Silva", "email": "joao@email.com", "documents_checked": 1 }, "key": { "id": 1, "name": "API do Site", "domain": "https://meusite.com", "expires_at": null, "last_used_at": "2024-01-15 10:30:00" }, "message": "Autenticado com sucesso" }

❌ Resposta de Erro

{ "success": false, "error": "Credenciais inválidas", "code": "INVALID_CREDENTIALS" }

Gerar QR Code PIX

POST
/api/v1/pix/criar

📋 Parâmetros

CampoTipoDescrição
amountfloatValor da transação (mínimo R$ 1,00) obrigatório
customer[name]stringNome do cliente (máx 100 caracteres) obrigatório
customer[email]stringE-mail do cliente obrigatório
customer[document]stringCPF ou CNPJ (apenas números) opcional
customer[phone]stringTelefone com DDD (apenas números) opcional
webhook_urlstringURL para notificação de pagamento opcional
curl -X POST https://www.payfrost.com.br/api/v1/pix/criar \ -H "Content-Type: application/json" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret" \ -d '{ "amount": 100.00, "customer": { "name": "João Silva", "email": "joao@email.com", "document": "12345678909", "phone": "11999999999" }, "webhook_url": "https://seudominio.com/webhook" }'

✅ Resposta de Sucesso

{ "success": true, "transaction_id": "PIX_1734567890_abc123", "payment_id": "tx_123456789", "amount": 100.00, "tax": 6.00, "net_amount": 94.00, "qr_code": "00020126580014br.gov.bcb.pix...", "qr_code_base64": "iVBORw0KGgo...", "expires_at": "2024-01-15 12:00:00", "acquirente": "PAYCORP", "status": "PENDING", "status_text": "Pendente", "message": "Pagamento PIX gerado com sucesso" }

❌ Resposta de Erro

{ "success": false, "error": "O valor da transação deve resultar em pelo menos R$ 0,10 após as taxas.", "code": "MINIMUM_NET_AMOUNT" }
O campo qr_code_base64 pode ser usado para exibir a imagem do QR Code diretamente no frontend.

Consultar PIX

GET
/api/v1/pix/status?id={transaction_id}

📋 Parâmetros

CampoTipoDescrição
idstringID da transação retornado na criação obrigatório
curl -X GET "https://www.payfrost.com.br/api/v1/pix/status?id=PIX_1734567890_abc123" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret"

✅ Resposta de Sucesso

{ "success": true, "transaction_id": "PIX_1734567890_abc123", "amount": 100.00, "tax": 6.00, "net_amount": 94.00, "payment_method": "PIX", "status": "PAID", "status_text": "Pago", "confirmed_at": "2024-01-15 12:05:00", "created_at": "2024-01-15 10:30:00" }
Status possíveis: PENDING (pendente), PAID (pago), CANCELLED (cancelado), REVERSED (estornado), FAILED (falhou)

Gerar boleto

POST
/api/v1/boleto/criar

Emite um boleto e devolve a linha digitável. O valor vai em reais. A confirmação do pagamento usa o mesmo webhook da cobrança PIX, com payment_method igual a BOLETO.

📋 Parâmetros

CampoTipoDescrição
amountfloatValor em reais. Mínimo R$ 1,00 obrigatório
customer[name]stringNome do pagador obrigatório
customer[email]stringE-mail do pagador obrigatório
customer[document]stringCPF ou CNPJ válido, com ou sem máscara obrigatório
customer[phone]stringTelefone com DDD opcional
descriptionstringDescrição do boleto, até 200 caracteres opcional
webhook_urlstringURL da sua loja para receber a confirmação opcional
curl -X POST https://www.payfrost.com.br/api/v1/boleto/criar \ -H "Content-Type: application/json" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret" \ -d '{ "amount": 150.00, "description": "Pedido 4471", "customer": { "name": "Maria Silva", "email": "maria@email.com", "document": "12345678909" }, "webhook_url": "https://seudominio.com/webhook" }'

✅ Resposta de sucesso

{ "success": true, "transaction_id": "BOL_1734567890_abc123", "payment_id": "ord_123", "amount": 150.00, "tax": 9.00, "tax_percent": 6, "net_amount": 141.00, "barcode": "34191.79001 01043.510047 91020.150008 9 96660000019790", "due_date": "2026-09-03 00:00:00", "acquirente": "Nuvra", "payment_method": "BOLETO", "status": "PENDING", "status_text": "Pendente" }
O boleto é emitido pela adquirente que suporta esse método. A liquidação na adquirente ocorre em D+2 úteis depois do pagamento. A FrostPay marca a cobrança como PAID quando a adquirente confirma.

Consultar boleto

GET
/api/v1/boleto/status?id={transaction_id}

Use o transaction_id devolvido na criação. A resposta traz o status e, enquanto o boleto existir, a linha digitável em barcode.

curl -X GET "https://www.payfrost.com.br/api/v1/boleto/status?id=BOL_1734567890_abc123" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret"

Status da Transação

📊 Status Disponíveis

PENDING
⏳ Aguardando pagamento
PAID
✅ Pagamento confirmado
CANCELLED
❌ Cancelado
REVERSED
🔄 Estornado / Reembolsado
FAILED
⚠️ Falhou
PROCESSING
⚙️ Processando

🔄 Fluxo de Status

PENDING → PAID (pagamento confirmado) PENDING → CANCELLED (cancelado pelo cliente) PAID → REVERSED (estorno solicitado) PENDING → FAILED (falha no pagamento)

Solicitar Saque

POST
/api/v1/saque/criar

📋 Parâmetros

CampoTipoDescrição
amountfloatValor do saque (mínimo R$ 1,00) obrigatório
pix_keystringChave PIX para recebimento obrigatório
pix_typestringTipo da chave: cpf, cnpj, email, phone, random opcional (padrão: cpf)
descriptionstringDescrição do saque opcional
curl -X POST https://www.payfrost.com.br/api/v1/saque/criar \ -H "Content-Type: application/json" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret" \ -d '{ "amount": 50.00, "pix_key": "12345678909", "pix_type": "cpf", "description": "Saque da loja" }'

✅ Resposta de Sucesso

{ "success": true, "transaction_id": "SAQ_1734567890_abc123", "payment_id": "wd_123456789", "amount": 50.00, "tax": 2.50, "net_amount": 47.50, "total": 52.50, "new_balance": 947.50, "acquirente": "PAYCORP", "status": "PENDING", "status_text": "Pendente", "message": "Saque solicitado com sucesso" }

❌ Resposta de Erro

{ "success": false, "error": "Saldo insuficiente para cobrir taxas", "code": "INSUFFICIENT_BALANCE_FOR_TAX", "details": { "required": 52.50, "available": 30.00 } }

Consultar Saque

GET
/api/v1/saque/status?id={transaction_id}

📋 Parâmetros

CampoTipoDescrição
idstringID da transação de saque obrigatório
curl -X GET "https://www.payfrost.com.br/api/v1/saque/status?id=SAQ_1734567890_abc123" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret"

✅ Resposta de Sucesso

{ "success": true, "transaction_id": "SAQ_1734567890_abc123", "amount": 50.00, "tax": 2.50, "net_amount": 47.50, "pix_key": "12345678909", "status": "PAID", "status_text": "Pago", "confirmed_at": "2024-01-15 14:00:00", "created_at": "2024-01-15 13:30:00" }

Consultar Saldo

GET
/api/v1/saque/balance
curl -X GET https://www.payfrost.com.br/api/v1/saque/balance \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret"

✅ Resposta

{ "success": true, "balance": 1250.00, "balance_blocked": 50.00, "balance_pending": 0.00, "pending_withdrawals": 0.00, "cash_out_active": true, "currency": "BRL" }

Listar Transações

GET
/api/v1/transacoes/listar?limit=10&offset=0

📋 Parâmetros

CampoTipoDescrição
limitintQuantidade de registros (máx 100) opcional (padrão: 50)
offsetintPáginação opcional (padrão: 0)
statusstringFiltrar por status opcional
typestringFiltrar por tipo (DEPOSIT, WITHDRAW) opcional
date_fromdateData inicial (YYYY-MM-DD) opcional
date_todateData final (YYYY-MM-DD) opcional
curl -X GET "https://www.payfrost.com.br/api/v1/transacoes/listar?limit=10&offset=0&status=PAID" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret"

✅ Resposta

{ "success": true, "transactions": [ { "id": "PIX_1734567890_abc123", "amount": 100.00, "tax": 6.00, "net_amount": 94.00, "type": "DEPOSIT", "status": "PAID", "status_text": "Pago", "payment_method": "PIX", "description": "Pagamento via PIX - João Silva", "customer_name": "João Silva", "customer_email": "joao@email.com", "created_at": "2024-01-15 10:30:00", "confirmed_at": "2024-01-15 12:05:00" } ], "pagination": { "total": 150, "limit": 10, "offset": 0, "returned": 10 } }

Webhook de Pagamento

O FrostPay utiliza uma URL única para todas as adquirentes. O sistema identifica automaticamente qual adquirente está enviando o webhook baseado nos headers e no payload.

URL do Webhook (unificada): https://www.payfrost.com.br/api/v1/pix/webhook.php

🔌 Detecção Automática por Adquirente

AdquirenteHeaders de IdentificaçãoPayload
Pluggou X-Webhook-Code
User-Agent: Pluggou-Webhook/1.0
event_type: "transaction"
BlueVision Authorization: Basic
X-Wishpag-Signature
eventType (transação/saque)
Benefício: Configure uma única URL no seu sistema e em todas as adquirentes. O roteamento é automático!

Payload do Webhook

📦 Payload Enviado

{ "event": "transaction.paid", "transaction_id": "PIX_1734567890_abc123", "amount": 100.00, "net_amount": 94.00, "tax": 6.00, "status": "PAID", "status_text": "Pago", "customer_name": "João Silva", "customer_email": "joao@email.com", "customer_document": "12345678909", "customer_phone": "11999999999", "payment_method": "PIX", "payment_provider": "PAYCORP", "confirmed_at": "2024-01-15 12:05:00", "created_at": "2024-01-15 10:30:00", "updated_at": "2024-01-15 12:05:00", "old_status": "PENDING", "old_status_text": "Pendente" }

📋 Campos do Payload

CampoTipoDescrição
eventstringTipo do evento: transaction.paid, transaction.cancelled, transaction.refunded
transaction_idstringID da transação no FrostPay
amountfloatValor bruto da transação
net_amountfloatValor líquido (após taxas)
taxfloatValor da taxa cobrada
statusstringStatus atual: PENDING, PAID, CANCELLED, REVERSED, FAILED
status_textstringTexto amigável do status
old_statusstringStatus anterior da transação
old_status_textstringTexto amigável do status anterior
confirmed_atdatetimeData de confirmação do pagamento
created_atdatetimeData de criação da transação
updated_atdatetimeData da última atualização
customer_namestringNome do cliente
customer_emailstringE-mail do cliente
customer_documentstringCPF/CNPJ do cliente
customer_phonestringTelefone do cliente
payment_methodstringMétodo de pagamento (PIX)
payment_providerstringAdquirente que processou o pagamento
Sua URL deve responder com HTTP 200 para confirmar o recebimento.

Exemplo de Webhook em PHP

<?php // webhook.php - URL que você deve configurar no painel // O FrostPay enviará POST para esta URL quando houver mudanças no status // Recebe o payload do webhook $payload = json_decode(file_get_contents('php://input'), true); // Log para debug file_put_contents('webhook_' . date('Y-m-d') . '.log', date('Y-m-d H:i:s') . ' - ' . json_encode($payload, JSON_PRETTY_PRINT) . PHP_EOL, FILE_APPEND ); // Verifica se é um pagamento confirmado if ($payload['event'] === 'transaction.paid') { $transaction_id = $payload['transaction_id']; $amount = $payload['amount']; $customer_email = $payload['customer_email']; $customer_name = $payload['customer_name']; // Atualiza seu sistema // $db->updateOrderStatus($transaction_id, 'PAID'); // Envia e-mail para o cliente // mail($customer_email, 'Pagamento confirmado', // "Olá $customer_name, seu pagamento de R$ $amount foi aprovado!" // ); // Responde com HTTP 200 para confirmar recebimento http_response_code(200); echo json_encode(['status' => 'ok', 'message' => 'Webhook processado']); } else { // Outros eventos (cancelled, refunded, etc) http_response_code(200); echo json_encode(['status' => 'ignored', 'event' => $payload['event']]); } ?>

Configuração do Webhook

Para configurar seu webhook, defina a URL no campo webhook_url ao criar a transação.

📋 URLs por Adquirente

AdquirenteURL para ConfigurarAutenticação
Pluggou https://www.payfrost.com.br/api/v1/pix/webhook.php X-Webhook-Code (painel Pluggou)
BlueVision https://www.payfrost.com.br/api/v1/pix/webhook.php X-Wishpag-Signature + Basic Auth

🔐 Segurança

O FrostPay valida automaticamente a assinatura dos webhooks. Recomendamos:

1. Manter o Webhook Secret seguro (não compartilhar) 2. Validar o transaction_id no seu sistema 3. Usar idempotência para evitar processamento duplicado 4. Verificar o status_text para exibir mensagens amigáveis

🔄 Retry

Em caso de falha (timeout ou HTTP não 200), o sistema tenta reenviar:

1ª tentativa: imediata 2ª tentativa: após 30 segundos 3ª tentativa: após 1 minuto 4ª tentativa: após 5 minutos

Múltiplas Adquirentes

O FrostPay suporta múltiplas adquirentes simultaneamente com fallback automático.

🏦 Adquirentes Suportadas

AdquirenteSlugStatusTaxa PIX
SELECT GESTAO E MARKETINGfrostpayAtivo6.99%
TRUSTED PAYMENT NETWORKfrostpay2Ativo6.99%
NATIONAL CORPORATE PARTNERbluevisionAtivo6.00%
RAPDYNrapdynAtivo6.00%
RAPDYN 2rapdyn2Ativo6.00%
Fallback automático: Se uma adquirente falhar, o sistema tenta automaticamente a próxima da lista.

Sistema de Fallback

O SmartRouter gerencia o fallback entre adquirentes automaticamente:

🔄 Como Funciona

1. Tenta a primeira adquirente da lista (prioridade 1) 2. Se falhar (timeout, erro, saldo insuficiente), tenta a próxima 3. Continua até encontrar uma adquirente que funcione 4. Retorna erro se todas falharem

📋 Prioridades

PrioridadeAdquirenteSlug
1SELECT GESTAO E MARKETINGfrostpay
2TRUSTED PAYMENT NETWORKfrostpay2
3NATIONAL CORPORATE PARTNERbluevision
4RAPDYNrapdyn
5RAPDYN 2rapdyn2

Exemplo PHP

<?php $clientId = 'seu_client_id'; $clientSecret = 'seu_client_secret'; $ch = curl_init('https://www.payfrost.com.br/api/v1/pix/criar'); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'X-Frost-Client-ID: ' . $clientId, 'X-Frost-Client-Secret: ' . $clientSecret ]); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ 'amount' => 100.00, 'customer' => [ 'name' => 'João Silva', 'email' => 'joao@email.com', 'document' => '12345678909' ], 'webhook_url' => 'https://www.payfrost.com.br/api/v1/pix/webhook.php' ])); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); $data = json_decode($response, true); curl_close($ch); if ($httpCode == 200 && $data['success']) { echo "✅ QR Code: " . $data['qr_code'] . "\n"; echo "⏰ Expira em: " . $data['expires_at'] . "\n"; echo "📊 Status: " . $data['status_text'] . "\n"; } else { echo "❌ Erro: " . ($data['error'] ?? $data['message'] ?? 'Erro desconhecido') . "\n"; } ?>

Exemplo cURL

# 🔐 Autenticar curl -X GET https://www.payfrost.com.br/api/v1/autenticar \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret" # 💰 Gerar PIX curl -X POST https://www.payfrost.com.br/api/v1/pix/criar \ -H "Content-Type: application/json" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret" \ -d '{ "amount": 100.00, "customer": {"name": "João Silva", "email": "joao@email.com"}, "webhook_url": "https://www.payfrost.com.br/api/v1/pix/webhook.php" }' # 🔍 Consultar status curl -X GET "https://www.payfrost.com.br/api/v1/pix/status?id=PIX_1234567890_abc" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret" # 💸 Solicitar saque curl -X POST https://www.payfrost.com.br/api/v1/saque/criar \ -H "Content-Type: application/json" \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret" \ -d '{"amount": 50.00, "pix_key": "12345678909", "pix_type": "cpf"}' # 📊 Consultar saldo curl -X GET https://www.payfrost.com.br/api/v1/saque/balance \ -H "X-Frost-Client-ID: seu_client_id" \ -H "X-Frost-Client-Secret: seu_client_secret"

Exemplo JavaScript (Node.js)

const clientId = 'seu_client_id'; const clientSecret = 'seu_client_secret'; const webhookUrl = 'https://www.payfrost.com.br/api/v1/pix/webhook.php'; async function criarPix(amount, customerName, customerEmail) { const response = await fetch('https://www.payfrost.com.br/api/v1/pix/criar', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Frost-Client-ID': clientId, 'X-Frost-Client-Secret': clientSecret }, body: JSON.stringify({ amount: amount, customer: { name: customerName, email: customerEmail }, webhook_url: webhookUrl }) }); const data = await response.json(); if (!response.ok) { throw new Error(data.error || 'Erro na requisição'); } return data; } async function consultarStatus(transactionId) { const response = await fetch( `https://www.payfrost.com.br/api/v1/pix/status?id=${transactionId}`, { headers: { 'X-Frost-Client-ID': clientId, 'X-Frost-Client-Secret': clientSecret } } ); return await response.json(); } // 🚀 Uso try { const pix = await criarPix(100.00, 'João Silva', 'joao@email.com'); console.log('✅ PIX criado:', pix.transaction_id); console.log('📊 Status:', pix.status_text); // Aguardar confirmação setTimeout(async () => { const status = await consultarStatus(pix.transaction_id); console.log('📊 Status atual:', status.status_text); }, 10000); } catch (error) { console.error('❌ Erro:', error.message); }

Exemplo Python

import requests import json import time client_id = 'seu_client_id' client_secret = 'seu_client_secret' base_url = 'https://www.payfrost.com.br' webhook_url = f'{base_url}/api/v1/pix/webhook.php' headers = { 'Content-Type': 'application/json', 'X-Frost-Client-ID': client_id, 'X-Frost-Client-Secret': client_secret } def criar_pix(amount, customer_name, customer_email): url = f'{base_url}/api/v1/pix/criar' payload = { 'amount': amount, 'customer': { 'name': customer_name, 'email': customer_email }, 'webhook_url': webhook_url } response = requests.post(url, headers=headers, json=payload) response.raise_for_status() return response.json() def consultar_status(transaction_id): url = f'{base_url}/api/v1/pix/status?id={transaction_id}' response = requests.get(url, headers=headers) response.raise_for_status() return response.json() try: # Criar PIX resultado = criar_pix(100.00, 'João Silva', 'joao@email.com') print(f"✅ PIX criado: {resultado['transaction_id']}") print(f"📊 Status: {resultado['status_text']}") # Aguardar e consultar status time.sleep(5) status = consultar_status(resultado['transaction_id']) print(f"📊 Status atual: {status['status_text']}") except requests.exceptions.RequestException as e: print(f"❌ Erro: {e}") if hasattr(e, 'response') and e.response: print(f"Detalhes: {e.response.text}")

Códigos de Erro

📊 Status HTTP

200
✅ Sucesso
400
❌ Parâmetros inválidos
401
🔒 Não autorizado
402
💰 Saldo insuficiente
403
🚫 Acesso negado (IP)
404
🔍 Não encontrado
405
⛔ Método não permitido
429
⏳ Rate limit excedido
500
💥 Erro interno do servidor
503
🔧 Serviço indisponível

📋 Códigos de Erro da API

CódigoDescrição
MISSING_CREDENTIALSCredenciais não fornecidas
INVALID_CREDENTIALSCredenciais inválidas
IP_NOT_ALLOWEDIP não autorizado na whitelist
INVALID_AMOUNTValor inválido (menor que R$ 1,00)
MINIMUM_NET_AMOUNTValor líquido abaixo do mínimo permitido
MISSING_CUSTOMER_DATANome ou e-mail do cliente não informado
INVALID_EMAILE-mail do cliente inválido
TRANSACTION_FAILEDFalha ao processar transação
QR_CODE_NOT_GENERATEDQR Code não gerado pela adquirente
NO_ACQUIRENTE_AVAILABLENenhuma adquirente disponível
INSUFFICIENT_BALANCESaldo insuficiente
WITHDRAWAL_FAILEDFalha ao processar saque

Soluções para Erros Comuns

❌ 401 - Não autorizado

Verifique se o Client-ID e Client-Secret estão corretos.

❌ 403 - IP não autorizado

Adicione seu IP à whitelist no painel → Chaves API.

❌ 402 - Saldo insuficiente

Verifique o saldo disponível via /api/v1/saque/balance

❌ 404 - Transação não encontrada

Confirme se o ID da transação está correto.

❌ 400 - "Valor líquido abaixo do mínimo"

O valor após as taxas deve ser pelo menos R$ 0,10. Aumente o valor da transação.

❌ Webhook não recebido

Verifique se a URL está correta e acessível externamente. Certifique-se de que seu servidor responde com HTTP 200.