README

SDK oficial da FlowinPay — gateway de pagamentos PIX brasileiro com split automático, saque na hora, checkout e webhooks assinados.

• ⚡ Cobranças PIX instantâneas (QR Code + copia-e-cola) em uma chamada
• 🔀 Split de pagamento (porcentagem ou valor fixo) entre até 3 recebedores
• 💸 Saques via PIX (cash out)
• 🔒 Verificação de assinatura de webhook (HMAC-SHA256)
• 📦 Zero dependências (usa cURL nativo) — funciona até em hospedagem compartilhada

Requisitos

PHP 8.1+ com as extensões curl e json.

Instalação

composer require flowinpay/flowinpay-php

Início rápido

require 'vendor/autoload.php';

use FlowinPay\FlowinPay;

$fp = new FlowinPay('fpk_sua_chave_aqui');

// Cria uma cobrança PIX de R$ 100 com split
$res = $fp->charges->create([
    'value' => 100,
    'description' => 'Pedido #123',
    'callbackUrl' => 'https://seusite.com/webhooks/flowinpay',
    'split' => [
        ['type' => 'percentage', 'value' => 10, 'recipient' => 'PUBLIC_ID_DO_COPRODUTOR'],
    ],
]);

$charge = $res['charge'];
echo $charge['br_code'];          // PIX copia-e-cola (exiba para o pagador)
echo $charge['payment_link_url']; // link de pagamento pronto
echo $charge['qr_code_image'];    // URL do QR Code

A App ID (fpk_...) você gera no painel em Integrações → API Keys, com os escopos desejados.

Cobranças

$res = $fp->charges->create(['value' => 50, 'description' => 'Curso']);
$one = $fp->charges->get($res['charge']['id']);
$all = $fp->charges->list();
$fp->charges->cancel($res['charge']['id']);

Saldo e saques

$saldo = $fp->balance->get();
echo $saldo['balance']['available'];

$fp->withdrawals->create([
    'value' => 100,
    'pix_key' => 'voce@email.com',
    'pix_key_type' => 'email', // 'cpf' | 'cnpj' | 'email' | 'phone' | 'random'
]);

Webhooks

Registrar

$res = $fp->webhooks->create([
    'url' => 'https://seusite.com/webhooks/flowinpay',
    'events' => ['charge.completed', 'charge.expired'],
]);
// ⚠️ Guarde o secret — só aparece nesta resposta:
echo $res['webhook']['secret']; // whsec_...

Verificar a assinatura

A FlowinPay assina cada webhook com X-FlowinPay-Signature = HMAC-SHA256(corpo_bruto, secret). Use sempre o corpo bruto (php://input).

use FlowinPay\Webhook;
use FlowinPay\FlowinPayException;

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_FLOWINPAY_SIGNATURE'] ?? null;

try {
    $evento = Webhook::parse($raw, $sig, 'whsec_seu_secret');
} catch (FlowinPayException $e) {
    http_response_code(401);
    exit('assinatura inválida');
}

http_response_code(200); // responda rápido (timeout de 5s)

if ($evento['event'] === 'charge.completed') {
    // libere o produto...
    error_log('Pago: ' . $evento['charge']['correlation_id']);
}

Eventos: charge.created, charge.completed, charge.expired, charge.cancelled, charge.refunded, withdrawal.completed, withdrawal.failed, dispute.opened, dispute.accepted, dispute.rejected, dispute.cancelled.

Tratamento de erros

use FlowinPay\FlowinPayException;

try {
    $fp->charges->create(['value' => 1]); // abaixo do mínimo
} catch (FlowinPayException $e) {
    echo $e->status;   // 422
    echo $e->getMessage();
    print_r($e->errors); // erros de validação por campo
}

Documentação

• Docs completos: https://app.flowinpay.com.br/docs
• Versão legível por IA: https://app.flowinpay.com.br/llms.txt

Licença

MIT © FlowinPay