PHPackages                             nkpay/pix-sdk - 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. nkpay/pix-sdk

ActiveLibrary[Payment Processing](/categories/payments)

nkpay/pix-sdk
=============

SDK PHP para a API Pix (BCB, OpenAPI v2.9.0) - cobranças, recebimentos, devoluções e webhooks. Compatível com PSPs que seguem o padrão (ex.: Banrisul).

v1.0.0(today)03↑2900%MITPHPPHP >=8.1

Since Jun 13Pushed todayCompare

[ Source](https://github.com/omgmistersatan/nkpay-pix-sdk)[ Packagist](https://packagist.org/packages/nkpay/pix-sdk)[ RSS](/packages/nkpay-pix-sdk/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (1)Versions (2)Used By (0)

nkpay/pix-sdk
=============

[](#nkpaypix-sdk)

SDK PHP não-oficial para a **API Pix** (especificação OpenAPI 3.0 do Banco Central — `bacen/pix-api`, v2.9.0). Cobre o fluxo de **recebimento** via Pix: cobranças imediatas (`cob`), cobranças com vencimento (`cobv`), consulta de Pix recebidos, devoluções, webhooks e locations.

> A spec do BCB define apenas a API exposta pelo **PSP recebedor**. Cada banco/instituição (Banrisul, Asaas, etc.) implementa essa API com pequenas variações próprias — confira sempre a documentação do seu PSP para confirmar URLs, escopos e formato exato dos campos.

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

[](#instalação)

```
composer require nkpay/pix-sdk
```

(Se for usar localmente sem publicar no Packagist, copie a pasta `src/` para o seu projeto e ajuste o autoload no `composer.json`.)

Dependência: `guzzlehttp/guzzle ^7.8`, PHP `>= 8.1`, extensão `ext-openssl`(necessária para o suporte a certificado `.pfx`/`.p12` — veja abaixo).

Pré-requisitos (junto ao seu PSP)
---------------------------------

[](#pré-requisitos-junto-ao-seu-psp)

Para autenticar você vai precisar, normalmente:

1. **Certificado mTLS** cadastrado no PSP, em um dos formatos abaixo:
    - **PEM + KEY** (`.pem`/`.crt` + `.key`); ou
    - **PFX/P12** (`.pfx`/`.p12`) — formato em que o Banrisul e outros bancos costumam entregar o certificado ICP-Brasil (e-CNPJ/e-CPF). O SDK converte o `.pfx` para PEM automaticamente em tempo de execução, não é necessário rodar `openssl` manualmente.
2. **client\_id** / **client\_secret** para o fluxo OAuth2 `client_credentials`.
3. URL base da API Pix do PSP (ex.: sandbox/produção do Banrisul) e URL do endpoint de token.

> Dica: antes de configurar o cliente, use `php examples/verificar_certificado.php caminho/certificado.pfx "senha"`para confirmar o titular (CNPJ), validade e cadeia do certificado — sem expor a chave privada.

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

[](#configuração)

Escolha **uma** das duas formas de certificado mTLS:

### Opção A — PFX/P12 (formato comum do Banrisul)

[](#opção-a--pfxp12-formato-comum-do-banrisul)

```
use NkPay\Pix\PixClient;
use NkPay\Pix\PixConfig;

$client = new PixClient(new PixConfig(
    baseUri: 'https://api.sandbox.banrisul.com.br/pix/v2',
    tokenUrl: 'https://api.sandbox.banrisul.com.br/oauth/token',
    clientId: getenv('PIX_CLIENT_ID'),
    clientSecret: getenv('PIX_CLIENT_SECRET'),
    pfxPath: __DIR__ . '/certs/certificado.pfx',
    pfxPassphrase: getenv('PIX_PFX_PASSPHRASE'), // '' se o .pfx não tiver senha
));
```

Internamente o SDK lê o `.pfx`, separa certificado e chave privada e grava arquivos `.pem` temporários (permissão `0600`) que o cURL exige — eles são apagados automaticamente ao final da requisição/script. Em hospedagem compartilhada, considere passar `pfxTempDir` apontando para um diretório privado fora do `webroot`.

### Opção B — PEM + KEY

[](#opção-b--pem--key)

```
use NkPay\Pix\PixClient;
use NkPay\Pix\PixConfig;

$client = new PixClient(new PixConfig(
    baseUri: 'https://api.sandbox.banrisul.com.br/pix/v2',
    tokenUrl: 'https://api.sandbox.banrisul.com.br/oauth/token',
    clientId: getenv('PIX_CLIENT_ID'),
    clientSecret: getenv('PIX_CLIENT_SECRET'),
    certPath: __DIR__ . '/certs/certificado.pem',
    certKeyPath: __DIR__ . '/certs/chave.key',
    // certPassphrase: 'opcional, se a chave for protegida por senha',
));
```

Em ambas as opções, `caBundlePath` é opcional e serve apenas para validar o certificado TLS do **servidor** do PSP com uma CA customizada (ICP-Brasil), caso o bundle padrão do sistema não seja suficiente — não tem relação com o certificado mTLS do cliente configurado acima.

Uso
---

[](#uso)

### Criar uma cobrança imediata (gerar QR Code para recebimento)

[](#criar-uma-cobrança-imediata-gerar-qr-code-para-recebimento)

```
use NkPay\Pix\Util\TxidGenerator;

$txid = TxidGenerator::generateWithPrefix('pedido1234');

$cobranca = $client->cobrancaImediata()->criar($txid, [
    'calendario' => ['expiracao' => 3600],
    'devedor' => ['cpf' => '12345678909', 'nome' => 'Fulano de Tal'],
    'valor' => ['original' => '49.90'],
    'chave' => 'pix@nkpay.com.br',
    'solicitacaoPagador' => 'Pagamento NkPay - pedido #1234',
]);

echo $cobranca['pixCopiaECola']; // string BR Code -> renderize como QR Code
```

### Consultar se um Pix foi recebido

[](#consultar-se-um-pix-foi-recebido)

```
$resultado = $client->pix()->recebidos([
    'inicio' => '2026-06-01T00:00:00Z',
    'fim'    => '2026-06-13T23:59:59Z',
    'txid'   => $txid,
]);

foreach ($resultado['pix'] ?? [] as $pix) {
    // $pix['endToEndId'], $pix['valor'], $pix['horario'], ...
}
```

### Configurar webhook (notificação automática de recebimento)

[](#configurar-webhook-notificação-automática-de-recebimento)

```
$client->webhook()->configurar('pix@nkpay.com.br', 'https://nkpay.com.br/webhooks/pix');
```

No endpoint `https://nkpay.com.br/webhooks/pix`, processe o payload recebido e use `$client->pix()->consultar($e2eid)` para confirmar os detalhes — veja `examples/webhook_listener.php`.

### Solicitar devolução (reembolso)

[](#solicitar-devolução-reembolso)

```
$client->pix()->solicitarDevolucao($e2eid, 'devolucao-001', [
    'valor' => '10.00',
    'natureza' => 'ORIGINAL',
    'descricao' => 'Reembolso parcial - pedido #1234',
]);
```

### Cobrança com vencimento (boleto-Pix)

[](#cobrança-com-vencimento-boleto-pix)

```
$client->cobrancaVencimento()->criar($txid, [
    'calendario' => [
        'dataDeVencimento' => '2026-07-10',
        'validadeAposVencimento' => 30,
    ],
    'devedor' => ['cpf' => '12345678909', 'nome' => 'Fulano de Tal'],
    'valor' => ['original' => '199.90'],
    'chave' => 'pix@nkpay.com.br',
]);
```

Tratamento de erros
-------------------

[](#tratamento-de-erros)

Todos os métodos lançam `NkPay\Pix\Exception\PixException` em caso de erro HTTP ou de comunicação. O código de status fica em `$e->statusCode`, o corpo decodificado em `$e->responseBody`, e eventuais violações de validação (HTTP 400) em `$e->violacoes()`.

```
use NkPay\Pix\Exception\PixException;

try {
    $client->cobrancaImediata()->criar($txid, $payload);
} catch (PixException $e) {
    foreach ($e->violacoes() as $v) {
        // $v['razao'], $v['propriedade']
    }
}
```

Exemplos
--------

[](#exemplos)

Veja a pasta `examples/`:

- `criar_cobranca.php` — cria uma cobrança imediata e obtém o "Pix Copia e Cola".
- `consultar_recebidos.php` — verifica se uma cobrança foi paga.
- `configurar_webhook.php` — registra a URL de notificação no PSP.
- `webhook_listener.php` — endpoint que recebe as notificações do PSP.
- `verificar_certificado.php` — inspeciona um `.pfx`/`.p12` (titular, validade, cadeia) sem expor a chave privada; útil para diagnosticar problemas de certificado antes de configurar o `PixConfig`.

Estrutura
---------

[](#estrutura)

```
src/
├── PixClient.php          # cliente HTTP (OAuth2 + mTLS)
├── PixConfig.php           # configuração de conexão (PEM ou PFX/P12)
├── Exception/PixException.php
├── Resource/
│   ├── CobrancaImediata.php   # /cob
│   ├── CobrancaVencimento.php # /cobv
│   ├── Pix.php                # /pix, /pix/{e2eid}/devolucao/{id}
│   ├── Webhook.php             # /webhook
│   └── Location.php             # /loc
└── Util/
    ├── TxidGenerator.php
    └── PfxCertificateLoader.php   # converte .pfx/.p12 -> PEM em runtime

```

O que NÃO está coberto (v1)
---------------------------

[](#o-que-não-está-coberto-v1)

A spec completa também define recursos de **Pix Automático / recorrência**(`/rec`, `/solicrec`, `/cobr`, `/lotecobv`). Não foram incluídos nesta primeira versão por não serem usados no fluxo atual do NkPay — avise se precisar que eu adicione.

Esta SDK também **não cobre envio de Pix** (Pix saída/pagamento) — isso não faz parte da spec `bacen/pix-api`, que cobre apenas o lado do PSP recebedor. Para envio, continue usando AbacatePay/Asaas como já está fazendo no NkPay.

Licença
-------

[](#licença)

MIT.

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance100

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

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

0d ago

### Community

Maintainers

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

### Embed Badge

![Health badge](/badges/nkpay-pix-sdk/health.svg)

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

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.2k532.1M2.5k](/packages/aws-aws-sdk-php)[neuron-core/neuron-ai

The PHP Agentic Framework.

1.9k496.1k33](/packages/neuron-core-neuron-ai)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.2M45](/packages/tencentcloud-tencentcloud-sdk-php)[chargebee/chargebee-php

ChargeBee API client implementation for PHP

768.3M9](/packages/chargebee-chargebee-php)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[imdhemy/google-play-billing

Google Play Billing

491.4M5](/packages/imdhemy-google-play-billing)

PHPackages © 2026

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