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.

URL Base da API

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:

exemplo_integracao
$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:

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

400 Bad Request
{
  "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.

Segurança Importante

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

  1. Acesse o painel de gerenciamento em https://fynoxpay.com/keys
  2. Copie seu client_id e client_secret
  3. Armazene as credenciais de forma segura em variáveis de ambiente
  4. 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.

POST https://api.fynoxpay.com/v2/pix/qrcode.php

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

gerar_qrcode
$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

200 OK
{
  "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"
}
✅ Próximo Passo

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.

Liberação de IP Obrigatória

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

POST https://api.fynoxpay.com/v2/pix/payment.php

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

fazer_pagamento
$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

200 OK
{
  "statusCode": 200,
  "message": "Pagamento processado com sucesso",
  "transactionId": "e7f8a9b3c4d5e6f7g8h9i0j1k2l3m4n5",
  "external_id": "e7f8a9b3c4d5e6f7g8h9i0j1k2l3m4n5",
  "status": "PAID",
  "gateway": "ecompag"
}
Status PENDING

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).

GET https://api.fynoxpay.com/v2/pix/status.php
Quando usar este endpoint?

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

consultar_status
$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

200 OK - Status PAID
{
  "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

200 OK - Status PENDING
{
  "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
Recomendação de Polling

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.

GET /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

balance_request
<?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)

response.json
{
  "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
💡 Dica:

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.

⚠️ Segurança:

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.

Importante

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

application/json
{
  "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

webhook_processor
<?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);
Nota sobre transactionId

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

application/json
{
  "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