Começando
Aqui você irá encontrar toda a documentação relacionada a API Ecompag v2. Abaixo segue algumas orientações gerais sobre a utilização dos nossos serviços.
https://api.fynoxpay.com/v2/
Autenticação
Em todas as requisições é necessário passar um token de acesso no header da request. Veja nessa documentação como gerar as credenciais e esse token de acesso.
Geração das credenciais de produção
Para gerar o token de acesso é necessário ter em mãos suas credenciais ( client_id / client_secret ). Para obter as credenciais de produção, acesse o menu API→Credenciais em https://fynoxpay.com/keys
Obtendo suas credenciais de acesso ao sandbox
Para obter suas credenciais, basta solicitá-las ao nosso time de suporte através do seu gerente.
Exemplo de Integração
Veja abaixo exemplos de como realizar uma requisição para gerar um QR Code PIX:
$ch = curl_init('https://api.fynoxpay.com/v2/pix/qrcode.php');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'client_id' => getenv('ECOMPAG_CLIENT_ID'),
'client_secret' => getenv('ECOMPAG_CLIENT_SECRET'),
'nome' => 'João Silva',
'cpf' => '12345678901',
'valor' => 100.00,
'descricao' => 'Pagamento de serviço',
'urlnoty' => 'https://seusite.com/webhook.php'
])
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);
if ($httpCode === 200 && isset($data['qrcode'])) {
echo "QR Code gerado com sucesso!";
echo "QR Code: " . $data['qrcode'];
} else {
echo "Erro: " . ($data['message'] ?? 'Desconhecido');
}
import os
import requests
url = 'https://api.fynoxpay.com/v2/pix/qrcode.php'
payload = {
'client_id': os.getenv('ECOMPAG_CLIENT_ID'),
'client_secret': os.getenv('ECOMPAG_CLIENT_SECRET'),
'nome': 'João Silva',
'cpf': '12345678901',
'valor': 100.00,
'descricao': 'Pagamento de serviço',
'urlnoty': 'https://seusite.com/webhook.py'
}
response = requests.post(url, data=payload)
data = response.json()
if response.status_code == 200 and 'qrcode' in data:
print("QR Code gerado com sucesso!")
print(f"QR Code: {data['qrcode']}")
else:
print(f"Erro: {data.get('message', 'Desconhecido')}")
require 'net/http'
require 'json'
uri = URI('https://api.fynoxpay.com/v2/pix/qrcode.php')
params = {
client_id: ENV['ECOMPAG_CLIENT_ID'],
client_secret: ENV['ECOMPAG_CLIENT_SECRET'],
nome: 'João Silva',
cpf: '12345678901',
valor: 100.00,
descricao: 'Pagamento de serviço',
urlnoty: 'https://seusite.com/webhook.rb'
}
response = Net::HTTP.post_form(uri, params)
data = JSON.parse(response.body)
if response.code == '200' && data['qrcode']
puts "QR Code gerado com sucesso!"
puts "QR Code: #{data['qrcode']}"
else
puts "Erro: #{data['message'] || 'Desconhecido'}"
end
const axios = require('axios');
const payload = {
client_id: process.env.ECOMPAG_CLIENT_ID,
client_secret: process.env.ECOMPAG_CLIENT_SECRET,
nome: 'João Silva',
cpf: '12345678901',
valor: 100.00,
descricao: 'Pagamento de serviço',
urlnoty: 'https://seusite.com/webhook.js'
};
axios.post('https://api.fynoxpay.com/v2/pix/qrcode.php', payload)
.then(response => {
console.log("QR Code gerado com sucesso!");
console.log(`QR Code: ${response.data.qrcode}`);
})
.catch(error => {
console.error(`Erro: ${error.response?.data?.message || 'Desconhecido'}`);
});
Próximos Passos
Agora que você já sabe como começar, explore os endpoints disponíveis:
- Gerar QRCode PIX - Crie QR Codes para recebimento
- Fazer um pagamento - Realize transferências PIX
- Consultar Status - Verifique o status de transações
- Webhooks - Configure notificações automáticas
Respostas HTTP
A API utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição.
Códigos de Sucesso
| Código | Descrição |
|---|---|
200 |
OK - A requisição foi processada com sucesso |
201 |
Created - O recurso foi criado com sucesso |
Códigos de Erro
| Código | Descrição |
|---|---|
400 |
Bad Request - Parâmetros inválidos ou ausentes |
401 |
Unauthorized - Credenciais de autenticação inválidas |
403 |
Forbidden - IP não autorizado ou acesso negado |
404 |
Not Found - Recurso não encontrado |
500 |
Internal Server Error - Erro interno do servidor |
Exemplo de Resposta de Erro
{
"statusCode": 400,
"message": "CPF inválido ou parâmetros obrigatórios ausentes",
"errors": [
"O campo 'valor' é obrigatório",
"CPF deve conter apenas números"
]
}
Criar Token de Acesso
Gerencie suas credenciais de acesso à API Ecompag.
Nunca exponha seu client_secret em código client-side (JavaScript do navegador, aplicativos mobile, etc). Use apenas em requisições server-side.
Obtendo Credenciais
- Acesse o painel de gerenciamento em https://fynoxpay.com/keys
- Copie seu
client_ideclient_secret - Armazene as credenciais de forma segura em variáveis de ambiente
- Use as credenciais em todas as requisições à API
Parâmetros de Autenticação
| Parâmetro | Tipo | Descrição |
|---|---|---|
client_id |
string | Identificador único do cliente na API |
client_secret |
string | Chave secreta para autenticação (mantenha privada) |
Gerar QRCode
Cria um QR Code PIX para recebimento de pagamentos.
Parâmetros da Requisição
| Parâmetro | Tipo | Descrição |
|---|---|---|
client_id |
string | Seu client ID (obrigatório) |
client_secret |
string | Sua chave secreta (obrigatório) |
nome |
string | Nome completo do pagador (obrigatório) |
cpf |
string | CPF do pagador - apenas números (obrigatório) |
valor |
float | Valor em reais - formato decimal (obrigatório) |
descricao |
string | Descrição do pagamento (obrigatório) |
urlnoty |
string | URL para receber notificações webhook (opcional) |
Exemplo de Requisição
$ch = curl_init('https://api.fynoxpay.com/v2/pix/qrcode.php');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'client_id' => getenv('ECOMPAG_CLIENT_ID'),
'client_secret' => getenv('ECOMPAG_CLIENT_SECRET'),
'nome' => 'João Silva Santos',
'cpf' => '12345678901',
'valor' => 150.99,
'descricao' => 'Pagamento de serviço premium',
'urlnoty' => 'https://seusite.com/webhook/ecompag'
])
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);
if ($httpCode === 200 && isset($data['qrcode'])) {
echo "QR Code: " . $data['qrcode'] . PHP_EOL;
echo "Transaction ID: " . $data['transactionId'] . PHP_EOL;
} else {
echo "Erro: " . ($data['message'] ?? 'Erro desconhecido');
}
import os
import requests
url = 'https://api.fynoxpay.com/v2/pix/qrcode.php'
payload = {
'client_id': os.getenv('ECOMPAG_CLIENT_ID'),
'client_secret': os.getenv('ECOMPAG_CLIENT_SECRET'),
'nome': 'João Silva Santos',
'cpf': '12345678901',
'valor': 150.99,
'descricao': 'Pagamento de serviço premium',
'urlnoty': 'https://seusite.com/webhook/ecompag'
}
response = requests.post(url, data=payload)
data = response.json()
if response.status_code == 200 and 'qrcode' in data:
print(f"QR Code: {data['qrcode']}")
print(f"Transaction ID: {data['transactionId']}")
else:
print(f"Erro: {data.get('message', 'Erro desconhecido')}")
curl -X POST https://api.fynoxpay.com/v2/pix/qrcode.php \ -d "client_id=SEU_CLIENT_ID" \ -d "client_secret=SEU_CLIENT_SECRET" \ -d "nome=João Silva Santos" \ -d "cpf=12345678901" \ -d "valor=150.99" \ -d "descricao=Pagamento de serviço premium" \ -d "urlnoty=https://seusite.com/webhook/ecompag"
Resposta de Sucesso
{
"statusCode": 200,
"message": "QR Code gerado com sucesso via Ecompag",
"qrcode": "00020126850014br.gov.bcb.pix...",
"transactionId": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
"amount": 150.99,
"reference_code": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
"gateway": "ecompag"
}
Use o transactionId retornado para consultar o status do pagamento através do endpoint Consultar Status.
Fazer um pagamento
Realiza transferências PIX para chaves PIX de terceiros.
Para realizar transferências PIX via API, é OBRIGATÓRIO fazer a liberação do endereço IP do servidor de onde serão feitas as requisições. Sem a liberação do IP, todas as requisições de transferência serão bloqueadas automaticamente.
Descubra o IP do seu servidor em: https://fynoxpay.com/meuip
Adicione o IP na whitelist em: https://fynoxpay.com/keys
Parâmetros da Requisição
| Parâmetro | Tipo | Descrição |
|---|---|---|
client_id |
string | Seu client ID (obrigatório) |
client_secret |
string | Sua chave secreta (obrigatório) |
nome |
string | Nome do beneficiário (obrigatório) |
cpf |
string | CPF do beneficiário - apenas números (obrigatório) |
valor |
float | Valor da transferência em reais (obrigatório) |
chave_pix |
string | Chave PIX do destinatário (obrigatório) |
descricao |
string | Descrição da transferência (opcional) |
urlnoty |
string | URL para notificações webhook (opcional) |
Exemplo de Requisição
$ch = curl_init('https://api.fynoxpay.com/v2/pix/payment.php');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'client_id' => getenv('ECOMPAG_CLIENT_ID'),
'client_secret' => getenv('ECOMPAG_CLIENT_SECRET'),
'nome' => 'Maria Silva',
'cpf' => '98765432100',
'valor' => 250.75,
'chave_pix' => '11970142332',
'descricao' => 'Pagamento de fornecedor',
'urlnoty' => 'https://seusite.com/webhook/ecompag'
])
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);
if ($httpCode === 200) {
echo "Status: " . $data['status'] . PHP_EOL;
echo "Transaction ID: " . $data['transactionId'];
} else {
echo "Erro: " . ($data['message'] ?? 'Erro desconhecido');
}
import os
import requests
url = 'https://api.fynoxpay.com/v2/pix/payment.php'
payload = {
'client_id': os.getenv('ECOMPAG_CLIENT_ID'),
'client_secret': os.getenv('ECOMPAG_CLIENT_SECRET'),
'nome': 'Maria Silva',
'cpf': '98765432100',
'valor': 250.75,
'chave_pix': '11970142332',
'descricao': 'Pagamento de fornecedor',
'urlnoty': 'https://seusite.com/webhook/ecompag'
}
response = requests.post(url, data=payload)
data = response.json()
if response.status_code == 200:
print(f"Status: {data['status']}")
print(f"Transaction ID: {data['transactionId']}")
else:
print(f"Erro: {data.get('message', 'Erro desconhecido')}")
curl -X POST https://api.fynoxpay.com/v2/pix/payment.php \ -d "client_id=SEU_CLIENT_ID" \ -d "client_secret=SEU_CLIENT_SECRET" \ -d "nome=Maria Silva" \ -d "cpf=98765432100" \ -d "valor=250.75" \ -d "chave_pix=11970142332" \ -d "descricao=Pagamento de fornecedor" \ -d "urlnoty=https://seusite.com/webhook/ecompag"
Resposta de Sucesso
{
"statusCode": 200,
"message": "Pagamento processado com sucesso",
"transactionId": "e7f8a9b3c4d5e6f7g8h9i0j1k2l3m4n5",
"external_id": "e7f8a9b3c4d5e6f7g8h9i0j1k2l3m4n5",
"status": "PAID",
"gateway": "ecompag"
}
Alguns pagamentos podem retornar com status: "PENDING", indicando que estão em processamento. Use o endpoint Consultar Status para verificar a confirmação.
Consultar Status
Verifica o status atual de uma transação PIX (depósito ou saque).
Use este endpoint para verificar se um QR Code foi pago ou se uma transferência foi confirmada. Ideal para polling ou validação manual de transações.
Parâmetros da Requisição
| Parâmetro | Tipo | Descrição |
|---|---|---|
client_id |
string | Seu client ID (obrigatório) |
client_secret |
string | Sua chave secreta (obrigatório) |
transaction_id |
string | ID da transação retornado ao gerar QRCode/Pagamento (obrigatório*) |
reference_code |
string | Código de referência alternativo (obrigatório*) |
* Informe pelo menos um dos dois: transaction_id ou reference_code
Exemplo de Requisição
$transactionId = '0eaf56ba401c9bfa5d61mkm3ch551oyt';
$url = 'https://api.fynoxpay.com/v2/pix/status.php?' . http_build_query([
'client_id' => getenv('ECOMPAG_CLIENT_ID'),
'client_secret' => getenv('ECOMPAG_CLIENT_SECRET'),
'transaction_id' => $transactionId
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);
if ($httpCode === 200) {
echo "Status: " . $data['transaction']['status'] . PHP_EOL;
echo "Tipo: " . $data['transaction']['type'] . PHP_EOL;
echo "Valor: R$ " . $data['transaction']['amount'];
if ($data['transaction']['status'] === 'PAID') {
echo PHP_EOL . "Pago em: " . $data['transaction']['paid_at'];
}
} else {
echo "Erro: " . ($data['message'] ?? 'Erro desconhecido');
}
import os
import requests
transaction_id = '0eaf56ba401c9bfa5d61mkm3ch551oyt'
url = 'https://api.fynoxpay.com/v2/pix/status.php'
params = {
'client_id': os.getenv('ECOMPAG_CLIENT_ID'),
'client_secret': os.getenv('ECOMPAG_CLIENT_SECRET'),
'transaction_id': transaction_id
}
response = requests.get(url, params=params)
data = response.json()
if response.status_code == 200:
print(f"Status: {data['transaction']['status']}")
print(f"Tipo: {data['transaction']['type']}")
print(f"Valor: R$ {data['transaction']['amount']}")
if data['transaction']['status'] == 'PAID':
print(f"Pago em: {data['transaction']['paid_at']}")
else:
print(f"Erro: {data.get('message', 'Erro desconhecido')}")
curl -X GET "https://api.fynoxpay.com/v2/pix/status.php?client_id=SEU_CLIENT_ID&client_secret=SEU_CLIENT_SECRET&transaction_id=0eaf56ba401c9bfa5d61mkm3ch551oyt"
Resposta - Transação PAGA
{
"statusCode": 200,
"message": "Transação confirmada com sucesso",
"transaction": {
"transactionId": "e7f8a9b3c4d5",
"external_id": "0eaf56ba401c9bfa5d61mkm3ch551oyt",
"status": "PAID",
"type": "DEPOSIT",
"amount": 10.00,
"tax": 0.50,
"total": 10.50,
"nome": "João Silva",
"document": "12345678909",
"descricao": "Teste de depósito",
"created_at": "2026-01-20 01:25:36",
"updated_at": "2026-01-20 01:26:15",
"paid_at": "2026-01-20 01:26:15"
},
"gateway": "ecompag"
}
Resposta - Transação PENDENTE
{
"statusCode": 200,
"message": "Transação aguardando confirmação",
"transaction": {
"transactionId": "e7f8a9b3c4d5",
"external_id": "0eaf56ba401c9bfa5d61mkm3ch551oyt",
"status": "PENDING",
"type": "DEPOSIT",
"amount": 10.00,
"tax": 0.50,
"total": 10.50,
"nome": "João Silva",
"document": "12345678909",
"created_at": "2026-01-20 01:25:36",
"updated_at": "2026-01-20 01:25:36"
},
"gateway": "ecompag"
}
Status Possíveis
| Status | Descrição |
|---|---|
PENDING |
Aguardando confirmação do pagamento |
PAID |
Pagamento confirmado e processado |
FAILED |
Transação falhou no processamento |
CANCELLED |
Transação foi cancelada |
Tipos de Transação
| Tipo | Descrição |
|---|---|
DEPOSIT |
Depósito via QR Code PIX |
WITHDRAW |
Saque/Transferência PIX |
Se você estiver fazendo polling (consultas periódicas), recomendamos um intervalo de 5 a 10 segundos entre cada consulta para evitar sobrecarga.
Consultar Saldo
Consulte o saldo disponível e bloqueado da sua conta via API.
/api/v2/account/balance.php
Parâmetros da Requisição
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
client_id |
string | Sim | ID do cliente (fornecido pela Ecompag) |
client_secret |
string | Sim | Chave secreta do cliente |
Exemplo de Requisição
<?php
$client_id = 'seu_client_id';
$client_secret = 'seu_client_secret';
$url = 'https://fynoxpay.com/api/v2/account/balance.php?' . http_build_query([
'client_id' => $client_id,
'client_secret' => $client_secret
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);
echo "Saldo disponível: R$ " . $data['balance']['available'];
?>
import requests
client_id = 'seu_client_id'
client_secret = 'seu_client_secret'
url = 'https://fynoxpay.com/api/v2/account/balance.php'
params = {
'client_id': client_id,
'client_secret': client_secret
}
response = requests.get(url, params=params)
data = response.json()
print(f"Saldo disponível: R$ {data['balance']['available']}")
curl -X GET "https://fynoxpay.com/api/v2/account/balance.php?client_id=seu_client_id&client_secret=seu_client_secret"
const axios = require('axios');
const client_id = 'seu_client_id';
const client_secret = 'seu_client_secret';
const url = 'https://fynoxpay.com/api/v2/account/balance.php';
axios.get(url, {
params: {
client_id: client_id,
client_secret: client_secret
}
})
.then(response => {
console.log(`Saldo disponível: R$ ${response.data.balance.available}`);
})
.catch(error => {
console.error('Erro:', error.response.data);
});
Resposta de Sucesso (200)
{
"statusCode": 200,
"message": "Saldo consultado com sucesso",
"balance": {
"available": 1250.50,
"blocked": 0.00,
"total": 1250.50
},
"user": {
"username": "exemplo_usuario",
"name": "João Silva"
}
}
Campos da Resposta
| Campo | Tipo | Descrição |
|---|---|---|
balance.available |
number | Saldo disponível para saque/uso |
balance.blocked |
number | Saldo bloqueado (em análise ou cautelar) |
balance.total |
number | Saldo total (disponível + bloqueado) |
user.username |
string | Nome de usuário da conta |
user.name |
string | Nome completo do titular |
Use este endpoint para exibir o saldo em tempo real no seu sistema, permitindo que seus usuários acompanhem suas transações e disponibilidade de recursos.
Mantenha o client_secret seguro e nunca o exponha em código front-end (JavaScript do navegador). Sempre faça requisições através do back-end da sua aplicação.
Evento de Pagamento
Webhook enviado automaticamente quando um pagamento PIX é recebido e confirmado.
Seu endpoint de webhook deve retornar HTTP 200 para confirmar o recebimento da notificação. Qualquer outro código HTTP fará a API reenviar a notificação.
Payload do Webhook
{
"transactionType": "RECEIVEPIX",
"transactionId": "a502e53d7e7d7c8afd0fmenrr80g57h0",
"amount": 150.99,
"paymentType": "PIX",
"status": "PAID",
"dateApproval": "2025-08-23 04:38:39",
"creditParty": {
"name": "João Silva Santos",
"email": "[email protected]",
"taxId": "12345678901"
},
"debitParty": {
"bank": "Ecompag Pagamentos LTDA",
"taxId": "59.667.922/0001-08"
}
}
Processamento do Webhook
<?php
// Receber dados do webhook
$input = file_get_contents('php://input');
$data = json_decode($input, true);
if (!$data) {
http_response_code(400);
die('Invalid JSON');
}
// Log para auditoria
file_put_contents('webhook.log',
date('Y-m-d H:i:s') . " - " . $input . PHP_EOL,
FILE_APPEND
);
// Processar pagamento recebido
if ($data['transactionType'] === 'RECEIVEPIX' && $data['status'] === 'PAID') {
$transactionId = $data['transactionId'];
$amount = $data['amount'];
// Sua lógica de negócio aqui
// Exemplo: liberar produto/serviço ao cliente
liberarProduto($transactionId, $amount);
// Confirmar recebimento
http_response_code(200);
echo "OK";
} else {
// Recebeu mas não processou
http_response_code(200);
echo "Received";
}
?>
from flask import Flask, request
import json
from datetime import datetime
app = Flask(__name__)
@app.route('/webhook/ecompag', methods=['POST'])
def webhook():
data = request.get_json()
if not data:
return 'Invalid JSON', 400
# Log para auditoria
with open('webhook.log', 'a') as f:
f.write(f"{datetime.now()} - {json.dumps(data)}\n")
# Processar pagamento recebido
if data.get('transactionType') == 'RECEIVEPIX' and data.get('status') == 'PAID':
transaction_id = data['transactionId']
amount = data['amount']
# Sua lógica de negócio aqui
liberar_produto(transaction_id, amount)
return 'OK', 200
return 'Received', 200
if __name__ == '__main__':
app.run()
const express = require('express');
const fs = require('fs');
const app = express();
app.use(express.json());
app.post('/webhook/ecompag', (req, res) => {
const data = req.body;
if (!data) {
return res.status(400).send('Invalid JSON');
}
// Log para auditoria
fs.appendFileSync('webhook.log',
`${new Date().toISOString()} - ${JSON.stringify(data)}\n`
);
// Processar pagamento recebido
if (data.transactionType === 'RECEIVEPIX' && data.status === 'PAID') {
const { transactionId, amount } = data;
// Sua lógica de negócio aqui
liberarProduto(transactionId, amount);
return res.status(200).send('OK');
}
res.status(200).send('Received');
});
app.listen(3000);
Use o transactionId retornado no webhook para rastrear e validar pagamentos. Este é o mesmo ID retornado na criação do QR Code.
Evento de Transferência
Webhook enviado automaticamente quando uma transferência PIX é concluída.
Payload do Webhook
{
"transactionType": "PAYMENT",
"transactionId": "798176179",
"amount": 250.75,
"paymentType": "PIX",
"dateApproval": "2025-08-23 15:45:22",
"statusCode": {
"statusId": 1,
"description": "Transferência concluída com sucesso"
}
}
Status Codes Possíveis
| Status ID | Descrição |
|---|---|
1 |
Transferência concluída com sucesso |
2 |
Transferência em processamento |
3 |
Transferência falhou |