Versão 1.0
Bem-vindo à documentação da API EXPFY Pay. Nossa API permite que você integre pagamentos PIX de forma simples e segura em sua aplicação. Todas as transações são processadas em tempo real e com alta disponibilidade.
Todas as requisições à API devem incluir suas chaves de autenticação nos headers. Suas chaves são únicas e identificam sua conta no sistema.
{
"X-Public-Key": "sua_public_key",
"X-Secret-Key": "sua_secret_key",
"Content-Type": "application/json"
}Nunca compartilhe sua Secret Key. Ela deve ser mantida em segurança e usada apenas em requisições do seu servidor para nossa API.
Para garantir a estabilidade e disponibilidade do serviço para todos os usuários, aplicamos os seguintes limites de requisições:
25.000
1MB
Caso exceda esses limites, você receberá um erro 429 Too Many Requests.
Recomendamos implementar uma lógica de retry com exponential backoff para lidar com esses casos.
Gera um QR Code PIX para recebimento de pagamento.
{
"amount": 100.00,
"description": "Pagamento do Pedido #123",
"customer": {
"name": "João Silva",
"document": "123.456.789-00",
"email": "joao@email.com" // opcional
},
"external_id": "seu_id_interno", // opcional
"callback_url": "https://seusite.com.br/webhook",
"split_email": "seu@email.com", // opcional
"split_percentage": "10" // opcional
}{
"success": true,
"data": {
"transaction_id": "285af09f32aa5f20b46f1ec288b25a8b",
"external_id": "seu_id_interno",
"qr_code": "00020126580014br.gov.bcb.pix...",
"qr_code_image": "data:image/svg+xml;base64,...",
"amount": 100.00,
"status": "pending"
}
}Agora é possível enviar parâmetros de rastreamento (UTM) junto à criação do pagamento. Isso permite análise de origem de vendas em plataformas integradas como a UTMIFY.
{
"amount": 100.00,
"description": "Compra de Curso Avançado",
"customer": {
"name": "João da Silva",
"document": "123.456.789-00",
"email": "joao@email.com"
},
"external_id": "pedido_456",
"callback_url": "https://seusite.com.br/webhook",
"split_email": "seu@email.com", // opcional
"split_percentage": "10", // opcional
"utm": {
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "black_friday",
"utm_term": "curso+programacao",
"utm_content": "banner_topo",
"src": "src_valor",
"sck": "sck_valor"
}
}
➔ Se não forem enviados dados UTM, a integração continuará funcionando normalmente.
➔ Recomendamos sempre preencher os campos para maximizar a análise de performance.
Solicita um saque via PIX para uma chave específica.
{
"amount": 1000.00,
"pix_key": "joao@email.com",
"pix_key_type": "EMAIL", // EMAIL, CPF, CNPJ, PHONE, EVP
"description": "Saque mensal",
"callback_url": "https://seusite.com.br/webhook"
}{
"success": true,
"data": {
"withdrawal_id": "1d50dcadf69d5378ff5fe93772b1cc5b",
"status": "processing",
"amount": 1000.00,
"expected_completion": "2024-01-16T16:30:00Z"
}
}Retorna o saldo disponível para saque da sua conta vinculada à chave da API.
{
"public_key": "sua_public_key",
"secret_key": "sua_secret_key"
}{
"balance": 1049.87
}Receba notificações em tempo real sobre o status das suas transações através de webhooks. Nosso sistema envia automaticamente atualizações para a URL de callback configurada sempre que ocorre uma mudança de status.
payment.received
Pagamento recebido e em processamento
payment.confirmed
Pagamento confirmado e concluído
withdrawl.processing
Saque em processamento
withdrawl.completed
Saque concluído com sucesso
{
"event": "payment.confirmed",
"transaction_id": "tx_123456",
"external_id": "seu_id_interno",
"status": "completed",
"amount": 100.00,
"paid_at": "2024-01-16T15:30:00Z",
"pix_data": {
"end2end_id": "E12345678202401161530abcdef12345",
"receipt_url": "https://expfypay.com/receipts/tx_123456.pdf"
}
}Dica de Segurança
Sempre verifique a autenticidade dos webhooks validando a assinatura no header X-Signature.
Para garantir a integridade e segurança dos dados recebidos, todos os webhooks enviados pela nossa API são assinados com HMAC-SHA256 utilizando sua secret_key.
X-Signature: <assinatura gerada com HMAC-SHA256 do corpo bruto>secret_key fornecida ao criar a integração.secret_key.X-Signature usando hash_equals() (em PHP) ou método equivalente seguro.$payload = file_get_contents('php://input');
$signatureRecebida = $_SERVER['HTTP_X_SIGNATURE'];
$secretKey = 'SUA_SECRET_KEY_AQUI';
$assinaturaEsperada = hash_hmac('sha256', $payload, $secretKey);
if (!hash_equals($assinaturaEsperada, $signatureRecebida)) {
http_response_code(401);
exit('Assinatura inválida');
}
// OK: continue processando o webhook
$data = json_decode($payload, true);
$event = $data['event'];
// Processe o evento conforme necessário
switch ($event) {
case 'payment.confirmed':
// Atualize o status do pedido para pago
break;
case 'withdrawl.completed':
// Atualize o status do saque
break;
}Sempre use hash_equals() ou equivalente para comparações seguras.
Nunca compartilhe ou exponha sua chave secreta em código cliente.
A assinatura é a única prova de origem válida para webhooks.
Armazene IDs de transação já processados para evitar duplicidade.
Nossa API utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição. Abaixo estão os principais códigos de erro que você pode encontrar:
| Código | Status | Descrição | Solução |
|---|---|---|---|
| 400 | Bad Request | Requisição inválida ou mal formatada | Verifique os parâmetros enviados |
| 401 | Unauthorized | Credenciais inválidas | Verifique suas chaves de API |
| 422 | Unprocessable Entity | Dados inválidos | Verifique o formato dos dados enviados |
| 429 | Too Many Requests | Limite de requisições excedido | Aguarde e tente novamente com backoff |
| 500 | Internal Server Error | Erro interno do servidor | Contate o suporte técnico |