PHPackages                             fluvpay/fluvpay - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. fluvpay/fluvpay

ActiveLibrary[Payment Processing](/categories/payments)

fluvpay/fluvpay
===============

SDK oficial da FluvPay para PHP. Pagamentos PIX, saques, transferências internas e verificação de webhooks.

v1.0.0(yesterday)00MITPHPPHP >=8.1

Since Jun 8Pushed yesterdayCompare

[ Source](https://github.com/fluvpay/fluvpay-php)[ Packagist](https://packagist.org/packages/fluvpay/fluvpay)[ Docs](https://fluvpay.com)[ RSS](/packages/fluvpay-fluvpay/feed)WikiDiscussions main Synced yesterday

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

FluvPay SDK para PHP
====================

[](#fluvpay-sdk-para-php)

SDK oficial da FluvPay para PHP. Cria cobranças PIX, processa saques e transferências internas e verifica assinaturas de webhook. A interface é fortemente tipada e não possui dependências de runtime, utilizando apenas a extensão cURL nativa do PHP. A documentação serve tanto a integrações conduzidas por desenvolvedores quanto a agentes de IA que consomem a referência para integrar.

Requisitos
----------

[](#requisitos)

PHP 8.1 ou superior, com as extensões `curl` e `json` habilitadas.

Instalação
----------

[](#instalação)

O pacote está publicado no Packagist sob o nome `fluvpay/fluvpay`. Instale com Composer:

```
composer require fluvpay/fluvpay
```

Para fixar uma faixa de versão semântica:

```
composer require fluvpay/fluvpay:^1.0
```

Inicio rápido
-------------

[](#inicio-rápido)

```
use FluvPay\FluvPay;

$fluvpay = new FluvPay([
    'api_key' => getenv('FLUVPAY_API_KEY'),
]);

$charge = $fluvpay->charges->create([
    'amount_cents' => 2500,
    'description'  => 'Pedido #1042',
    'customer'     => ['name' => 'Cliente Exemplo', 'email' => 'cliente@exemplo.com'],
]);

echo $charge->pixCopyPaste;
```

Configuração
------------

[](#configuração)

O construtor aceita um array de opções. Apenas `api_key` é obrigatório; os demais campos têm valores padrão.

OpçãoPadrãoDescrição`api_key`(obrigatório)Chave de autenticação da API.`base_url``https://api.fluvpay.com/api/v1`URL base da API.`timeout``30.0`Tempo limite de cada requisição, em segundos.`max_retries``2`Número de retentativas automáticas. `0` desliga as retentativas.```
use FluvPay\FluvPay;

$fluvpay = new FluvPay([
    'api_key'     => getenv('FLUVPAY_API_KEY'),
    'base_url'    => 'https://api.fluvpay.com/api/v1',
    'timeout'     => 30.0,
    'max_retries' => 2,
]);
```

Autenticação
------------

[](#autenticação)

A autenticação usa a API Key. O ambiente de operação é determinado pelo prefixo da chave: `fluv_live_` opera em produção e `fluv_test_` opera no sandbox. O método `isTestKey()` informa o ambiente da chave em uso.

```
var_dump($fluvpay->isTestKey()); // true quando a chave é fluv_test_
```

Cobranças PIX
-------------

[](#cobranças-pix)

### Criar uma cobrança

[](#criar-uma-cobrança)

A criação de cobrança aceita apenas os campos do contrato. Os campos `currency` e `method` não devem ser enviados: a moeda e o método (PIX) são implícitos, e a API rejeita campos extras com erro de validação.

CampoDescrição`amount_cents`Valor em centavos. Mínimo 100, máximo 100000.`description`Descrição da cobrança.`customer`Objeto com `name` e `email`.`pass_fee_to_payer`Repassa a taxa ao pagador quando `true`.`metadata`Pares chave-valor arbitrários.```
$charge = $fluvpay->charges->create([
    'amount_cents'      => 2500, // R$ 25,00
    'description'       => 'Pedido #1042',
    'customer'          => ['name' => 'Cliente Exemplo', 'email' => 'cliente@exemplo.com'],
    'pass_fee_to_payer' => true,
    'metadata'          => ['pedido_id' => '1042'],
]);

echo $charge->id;
echo $charge->status;        // pending | paid | expired | cancelled | refunded
echo $charge->pixCopyPaste;  // código copia-e-cola
echo $charge->pixQrCode;     // imagem do QR em base64
```

### Idempotência

[](#idempotência)

O SDK gera uma `Idempotency-Key` (UUIDv4) automaticamente quando nenhuma é informada. A chave efetivamente utilizada fica disponível após a chamada.

```
echo $fluvpay->charges->lastIdempotencyKey;
```

Uma chave explícita pode ser fornecida pelo segundo argumento, permitindo o controle direto da idempotência.

```
$charge = $fluvpay->charges->create(
    ['amount_cents' => 2500],
    'minha-chave-unica-por-operacao',
);
```

### Recuperar e listar cobranças

[](#recuperar-e-listar-cobranças)

A listagem usa paginação por `page`/`per_page` e retorna um objeto iterável com metadados de página.

```
$charge = $fluvpay->charges->retrieve('chg_...');

$page = $fluvpay->charges->list([
    'page'     => 1,
    'per_page' => 20,
    'status'   => 'paid',
    'sort'     => '-created_at',
]);

echo $page->total;
echo $page->hasNext ? 'tem próxima' : 'última página';

foreach ($page as $item) {
    echo $item->id . ' ' . $item->amountCents . PHP_EOL;
}
```

Transações
----------

[](#transações)

O extrato consolidado usa paginação por `page`/`per_page`.

```
$tx = $fluvpay->transactions->list(['page' => 1, 'per_page' => 50]);
$lancamento = $fluvpay->transactions->retrieve('txn_...');
```

Saques
------

[](#saques)

O saque PIX usa paginação por `limit`/`offset`. A operação é exclusiva de produção e responde 403 quando chamada com chave de teste.

CampoDescrição`amount_cents`Valor em centavos.`pix_key`Chave PIX de destino.`pix_key_type`Tipo da chave: `cpf`, `cnpj`, `email`, `phone` ou `evp`.`description`Descrição do saque.```
$saque = $fluvpay->withdrawals->create([
    'amount_cents' => 5000,
    'pix_key'      => 'chave@exemplo.com',
    'pix_key_type' => 'email',
    'description'  => 'Repasse semanal',
]);

$saques = $fluvpay->withdrawals->list(['limit' => 20, 'offset' => 0, 'status' => 'completed']);
```

Transferências internas
-----------------------

[](#transferências-internas)

A transferência interna entre contas FluvPay usa paginação por `limit`/`offset`. A operação é exclusiva de produção e responde 403 quando chamada com chave de teste. O destinatário é identificado por `recipient_email` ou por `recipient_merchant_id` (ULID de 26 caracteres).

```
$transfer = $fluvpay->internalTransfers->create([
    'amount_cents'    => 3000,
    'recipient_email' => 'destino@exemplo.com',
]);

$transfers = $fluvpay->internalTransfers->list(['direction' => 'sent', 'limit' => 20]);
```

Sandbox
-------

[](#sandbox)

Os recursos de sandbox estão disponíveis apenas com chave de teste (`fluv_test_`).

```
$reset = $fluvpay->sandbox->reset();
echo $reset->deletedCharges;

$scenarios = $fluvpay->sandbox->scenarios();
echo $scenarios->info;
```

Webhooks
--------

[](#webhooks)

A FluvPay assina cada entrega de webhook. A verificação deve ocorrer sobre o corpo cru da requisição. Re-serializar o JSON altera os bytes e invalida a assinatura.

```
use FluvPay\Webhooks;
use FluvPay\Exceptions\FluvPaySignatureVerificationError;

$payload   = file_get_contents('php://input'); // corpo cru, em bytes
$signature = $_SERVER['HTTP_X_FLUVPAY_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_FLUVPAY_TIMESTAMP'] ?? '';
$secret    = getenv('FLUVPAY_WEBHOOK_SECRET'); // whsec_...

try {
    $event = Webhooks::verifySignature(
        $payload,
        $signature,
        $timestamp,
        $secret,
        toleranceSeconds: 300, // rejeita entregas fora da janela de tolerância
    );

    echo $event['type'];
} catch (FluvPaySignatureVerificationError $e) {
    http_response_code(400);
    echo 'Assinatura inválida';
}
```

A assinatura é calculada como `HMAC_SHA256(secret, "{timestamp}." + corpo)`, codificada em hexadecimal no formato `v1=`, e comparada em tempo constante.

Eventos emitidos: `charge.created`, `charge.paid`, `charge.expired`, `charge.cancelled`, `charge.refunded`, `payout.created`, `payout.completed` e `payout.failed`.

Erros
-----

[](#erros)

Toda exceção herda de `FluvPay\Exceptions\FluvPayError` e expõe `code`, `message`, `details`, `traceId` e `statusCode`.

```
use FluvPay\Exceptions\FluvPayError;
use FluvPay\Exceptions\FluvPayValidationError;
use FluvPay\Exceptions\FluvPayRateLimitError;

try {
    $charge = $fluvpay->charges->create(['amount_cents' => 1]);
} catch (FluvPayValidationError $e) {
    echo $e->errorCode;    // VALIDATION_ERROR
    foreach ($e->details as $detail) {
        echo $detail->field . ': ' . $detail->message . PHP_EOL;
    }
} catch (FluvPayRateLimitError $e) {
    echo 'Tente de novo em ' . $e->retryAfter . 's';
} catch (FluvPayError $e) {
    echo $e->getMessage() . ' (trace: ' . $e->traceId . ')';
}
```

Mapeamento de status HTTP para exceção:

StatusExceção400 / 422`FluvPayValidationError`401`FluvPayAuthenticationError`403`FluvPayPermissionError`404`FluvPayNotFoundError`409`FluvPayConflictError` (inclui `IDEMPOTENCY_CONFLICT`)429`FluvPayRateLimitError` (lê o header `Retry-After`)5xx`FluvPayServerError`rede / timeout`FluvPayConnectionError`Retentativas
------------

[](#retentativas)

O SDK reenvia automaticamente apenas requisições idempotentes: GET e POSTs que carregam uma `Idempotency-Key`. As retentativas usam backoff exponencial com jitter, com o padrão de 2 tentativas. Os gatilhos são respostas 429, respostas 5xx e falhas de conexão. O header `Retry-After` é respeitado em respostas 429. As retentativas são desativadas com `'max_retries' => 0`.

Desenvolvimento
---------------

[](#desenvolvimento)

```
composer install
vendor/bin/phpunit
```

Os testes unitários não acessam a rede, pois o transporte HTTP é mockado. O smoke test contra o sandbox executa apenas quando a variável de ambiente `FLUVPAY_TEST_KEY` (chave `fluv_test_`) está definida; caso contrário, é pulado.

Licença
-------

[](#licença)

[MIT](LICENSE)

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

1d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/291656315?v=4)[FluvPay](/maintainers/fluvpay)[@fluvpay](https://github.com/fluvpay)

---

Top Contributors

[![fluvpay](https://avatars.githubusercontent.com/u/291656315?v=4)](https://github.com/fluvpay "fluvpay (2 commits)")

---

Tags

brazilfluvpaypayment-gatewaypaymentsphppixsdksdkwebhookspaymentsgatewaypagamentospixfluvpay

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/fluvpay-fluvpay/health.svg)

```
[![Health](https://phpackages.com/badges/fluvpay-fluvpay/health.svg)](https://phpackages.com/packages/fluvpay-fluvpay)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)