README

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

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)

Para autenticar você vai precisar, normalmente:

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.
client_id / client_secret para o fluxo OAuth2 client_credentials.
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

Escolha uma das duas formas de certificado mTLS:

Opção A — PFX/P12 (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

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

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

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

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

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

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

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

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

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)

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

MIT.

nkpay / pix-sdk

Maintainers

Package info

Statistics

Security