Visão geral

API REST para autenticação, depósito PIX, saque, transferência interna, cripto, MEDs e webhooks — contrato alinhado ao fluxo da adquirente.

https://fyrenpay.com/api

Unidades

Status de transação

PENDENTE · COMPLETO · FALHA · CANCELADO

Autenticação

HTTP Basic Auth com as chaves do lojista:

Authorization: Basic BASE64(client_id:client_secret)
Content-Type: application/json

curl -u 'SEU_CLIENT_ID:SEU_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  'https://fyrenpay.com/api/users/balance'

Whitelist de IP (só saque)

• Aplica-se apenas a saque PIX e saque crypto — não a depósito, saldo, listagem nem check.
• Cadastre IPs em Credenciais → IPs.
• Se houver IPs cadastrados, só esses IPs podem sacar.
• Se a lista estiver vazia e API_REQUIRE_IP_WHITELIST=true, o saque é bloqueado (403). Cadastre ao menos um IP.

Erros HTTP

Gerar transação

Cria cobrança PIX (cash-in). Retorna QR e copia-e-cola.

curl -X POST 'https://fyrenpay.com/api/transactions/create' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 25.90,
  "payerName": "Cliente Exemplo",
  "payerDocument": "12345678909",
  "transactionId": "pedido_1001",
  "description": "Pedido #1001",
  "projectWebhook": "https://seusite.com/webhooks/fyrenpay",
  "returnUrl": "https://seusite.com/obrigado"
}'

Resposta 200

{
  "message": "Transação criada com sucesso",
  "data": {
    "transactionId": "31484480",
    "clientTransactionId": "pedido_1001",
    "transactionFee": 152,
    "transactionType": "DEPOSITO",
    "transactionMethod": "PIX",
    "transactionAmount": 2590,
    "transactionState": "PENDENTE",
    "qrCodeBase64": "...",
    "copyPaste": "00020126...BR.GOV.BCB.PIX...",
    "checkoutUrl": "https://fyrenpay.com/pay/Xb3k9QaP2mLr7TzW1vYc8NdE",
    "expiresAt": "2026-11-08T21:30:00-03:00"
  }
}

Checkout hospedado

Toda cobrança criada pela API vem com um checkoutUrl: uma página de pagamento pronta, responsiva e com a marca FyrenPay. Você não precisa montar tela de QR Code.

• Celular: botão grande de Copiar código Pix (o cliente cola no app do banco); QR Code sob demanda.
• Computador: QR Code em destaque para ler com o celular.
• Atualiza sozinha: quando o Pix é confirmado, mostra a tela de pagamento aprovado e, se você enviou returnUrl, leva o cliente de volta ao seu site.
• Validade: o código vale 30 minutos (veja expiresAt); depois a página mostra que expirou.

Veja um exemplo: /pay/demo (demonstração, sem cobrança real).

Links de pagamento (sem código)

No painel, em Links de pagamento, você cria um link com produto e valor (fixo ou livre) e envia por WhatsApp, Instagram ou e-mail. O cliente informa nome e CPF e cai no mesmo checkout. As vendas aparecem no extrato e disparam os mesmos webhooks. Exemplo: /l/demo.

Gerar transação interna

Transfere saldo entre contas FyrenPay (sem PIX externo).

curl -X POST 'https://fyrenpay.com/api/transactions/withdraw/internal' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"email":"destino@email.com","amount":10,"description":"repasse"}'

Consultar saldo

curl -u 'CLIENT_ID:CLIENT_SECRET' 'https://fyrenpay.com/api/users/balance'

{
  "message": "Saldo do usuário obtido com sucesso",
  "data": { "balance": 150.75 }
}

Consultar dados do usuário

curl -u 'CLIENT_ID:CLIENT_SECRET' 'https://fyrenpay.com/api/users/info'

{
  "message": "Dados do usuário encontrados com sucesso",
  "data": {
    "name": "Loja Exemplo",
    "email": "loja@email.com",
    "document": "12345678000199",
    "phone": "11999999999",
    "accountVerified": true,
    "documentVerified": true,
    "withdrawBlocked": false,
    "availableBalance": 150.75,
    "blockedBalance": 0
  }
}

Solicitar saque

Cash-out PIX. Debita saldo + taxa na criação; estorna se falhar.

curl -X POST 'https://fyrenpay.com/api/transactions/withdraw' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: saque-pedido-1001' \
  -d '{
  "amount": 50,
  "pixKey": "12345678909",
  "pixKeyType": "CPF",
  "description": "Saque pedido 1001",
  "projectWebhook": "https://seusite.com/webhooks/fyrenpay"
}'

Resposta 200

{
  "message": "Saque adicionado à fila de processamento",
  "data": {
    "jobId": "withdraw-...",
    "transactionId": "...",
    "status": "QUEUED",
    "message": "Seu saque será processado em breve"
  }
}

Solicitar saque crypto

Saque USDT BEP20. Mín. R$ 20 / máx. R$ 3.000. Debita saldo + taxa (cash-out do gateway, mínimo 3%).

curl -X POST 'https://fyrenpay.com/api/crypto/withdraw-api' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 100,
  "wallet": "0x1234567890123456789012345678901234567890"
}'

Consultar taxas de cripto

curl -u 'CLIENT_ID:CLIENT_SECRET' 'https://fyrenpay.com/api/crypto/fees'

Proxy das taxas atuais da adquirente (rede + percentual).

Verificar transação

curl -X POST 'https://fyrenpay.com/api/transactions/check' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"transactionId":"31484480"}'

Resposta 200

{
  "message": "Transação encontrada com sucesso!",
  "transaction": {
    "transactionId": "31484480",
    "clientTransactionId": "e...",
    "value": 2590,
    "fee": 152,
    "transactionState": "COMPLETO",
    "transactionType": "DEPOSITO",
    "transactionMethod": "PIX",
    "createdAt": "2026-09-11 22:00:00",
    "updatedAt": "2026-09-11 22:00:00"
  }
}

Listar transações

Página começa em 1. Query opcional: ?status=COMPLETO (também PENDENTE, FALHA, CANCELADO).

Tipos: DEPOSITO, RETIRADA, TRANSFERENCIA_INTERNA, TRANSFERENCIA_INTERNA_RECEBIDA.

curl -u 'CLIENT_ID:CLIENT_SECRET' \
  'https://fyrenpay.com/api/users/transactions/list/1?status=COMPLETO'

Listar infrações

Lista MEDs / infrações vinculadas à operação (proxy adquirente).

Query: ?page=1&perPage=20

curl -u 'CLIENT_ID:CLIENT_SECRET' \
  'https://fyrenpay.com/api/meds/infractions/list?page=1&perPage=20'

Responder infração

curl -X POST 'https://fyrenpay.com/api/meds/infractions/42/defense' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "analise": "ACEITO",
  "justificativa": "Cliente reconheceu a compra",
  "proofs": ["https://seusite.com/comprovante.pdf"]
}'

Webhook de Depósito

Informe projectWebhook em POST /transactions/create. Após liquidar o PIX, a FyrenPay envia POST JSON e só considera entregue se sua URL responder HTTP 2xx.

Confirmação e retries

• Responda 200–299 rápido (ideal < 5s) com body vazio ou JSON.
• Qualquer outro status / timeout → reenvio automático (até 8 tentativas: 1 min, 5 min, 30 min, 2 h…).
• Cron no servidor: php scripts/process_merchant_webhooks.php a cada minuto.

Assinatura HMAC

Headers enviados:

X-FyrenPay-Event: DEPOSIT
X-FyrenPay-Delivery: 123
X-FyrenPay-Timestamp: 1726100000
X-FyrenPay-Signature: sha256=HEX

Calcule HMAC_SHA256(timestamp + "." + rawBody, webhook_secret) e compare com o hex do header (após sha256=). O webhook_secret está em API → Credenciais (whsec_...).

// Node.js
const crypto = require('crypto');
const ts = req.headers['x-fyrenpay-timestamp'];
const sig = String(req.headers['x-fyrenpay-signature'] || '').replace(/^sha256=/, '');
const expected = crypto.createHmac('sha256', webhookSecret)
  .update(ts + '.' + rawBody).digest('hex');
if (sig !== expected) return res.status(401).end();
return res.status(200).json({ ok: true });

{
  "event": "DEPOSIT",
  "webhookVersion": 1,
  "transactionId": "31484480",
  "clientTransactionId": "e...",
  "transactionType": "DEPOSITO",
  "transactionMethod": "PIX",
  "status": "COMPLETO",
  "transactionState": "COMPLETO",
  "value": 2590,
  "fee": 152,
  "e2e": "E..."
}

value / fee em centavos. Status: COMPLETO ou FALHA.

Webhook de Saque

Informe projectWebhook em POST /transactions/withdraw (ou crypto). Mesma confirmação 2xx, HMAC e retries. Payload com event": "WITHDRAW" e transactionType": "RETIRADA".

{
  "event": "WITHDRAW",
  "webhookVersion": 1,
  "transactionId": "...",
  "clientTransactionId": "e...",
  "transactionType": "RETIRADA",
  "transactionMethod": "PIX",
  "status": "COMPLETO",
  "transactionState": "COMPLETO",
  "value": 5000,
  "fee": 150,
  "e2e": "E..."
}

Em FALHA, o valor + taxa debitados na criação são estornados automaticamente no saldo.

Webhook de MED

Quando uma infração MED chega, se a TX tiver projectWebhook, enviamos com o mesmo sistema de confirmação/assinatura (event": "INFRACTION"):

{
  "event": "INFRACTION",
  "webhookVersion": 1,
  "infractionId": 42,
  "transactionId": "31484480",
  "clientTransactionId": "e...",
  "status": "OPEN",
  "transactionState": "OPEN",
  "value": 2590
}

Use a API de MEDs para listar e responder a defesa. O gateway também retém saldo e bloqueia saque conforme a política interna.

Documentação alinhada à API real da FyrenPay · 2026