README

SDK oficial da NXGATE para integração com a API PIX em PHP.

Requisitos

• PHP 8.1 ou superior
• Extensões: curl, json, hash

Instalação

composer require nxgate/sdk

Configuração

use NXGate\NXGate;

// Sem HMAC
$nx = new NXGate(
    clientId: 'nxgate_xxx',
    clientSecret: 'seu_secret',
);

// Com HMAC (recomendado para produção)
$nx = new NXGate(
    clientId: 'nxgate_xxx',
    clientSecret: 'seu_secret',
    hmacSecret: 'seu_hmac_secret',
);

O SDK gerencia automaticamente a autenticação OAuth2. O token é obtido na primeira chamada e renovado automaticamente antes de expirar.

Quando o hmacSecret é fornecido, todas as requisições são assinadas automaticamente com HMAC-SHA256.

Uso

Gerar cobrança PIX (Cash-in)

use NXGate\Dto\PixGenerateRequest;
use NXGate\Dto\SplitUser;

$charge = $nx->pixGenerate(new PixGenerateRequest(
    valor: 100.00,
    nomePagador: 'João da Silva',
    documentoPagador: '12345678901',
    webhook: 'https://meusite.com/webhook',
    descricao: 'Pagamento do pedido #123',
));

echo $charge->status;           // "success"
echo $charge->paymentCode;      // código PIX copia e cola
echo $charge->idTransaction;    // ID da transação
echo $charge->paymentCodeBase64; // QR Code em base64

Com split de pagamento

$charge = $nx->pixGenerate(new PixGenerateRequest(
    valor: 100.00,
    nomePagador: 'João da Silva',
    documentoPagador: '12345678901',
    splitUsers: [
        new SplitUser(username: 'parceiro1', percentage: 70.0),
        new SplitUser(username: 'parceiro2', percentage: 30.0),
    ],
));

Saque PIX (Cash-out)

use NXGate\Dto\PixWithdrawRequest;
use NXGate\PixKeyType;

$withdrawal = $nx->pixWithdraw(new PixWithdrawRequest(
    valor: 50.00,
    chavePix: 'joao@email.com',
    tipoChave: PixKeyType::EMAIL,
    webhook: 'https://meusite.com/webhook',
));

echo $withdrawal->status;            // "success"
echo $withdrawal->message;           // mensagem da API
echo $withdrawal->internalReference; // referência interna

Tipos de chave PIX

use NXGate\PixKeyType;

PixKeyType::CPF;    // CPF
PixKeyType::CNPJ;   // CNPJ
PixKeyType::PHONE;  // Telefone
PixKeyType::EMAIL;  // E-mail
PixKeyType::RANDOM; // Chave aleatória

Consultar saldo

$balance = $nx->getBalance();

echo $balance->balance;   // saldo total
echo $balance->blocked;   // saldo bloqueado
echo $balance->available; // saldo disponível

Consultar transação

$transaction = $nx->getTransaction(type: 'cash-in', txId: 'TX_ABC123');

echo $transaction->idTransaction; // ID da transação
echo $transaction->status;        // status
echo $transaction->amount;        // valor
echo $transaction->paidAt;        // data do pagamento
echo $transaction->endToEnd;      // identificador end-to-end

Receber webhooks

use NXGate\NXGateWebhook;

// Receber o payload do webhook (string JSON ou array)
$payload = file_get_contents('php://input');
$event = NXGateWebhook::parse($payload);

// Verificar o tipo do evento
if ($event->isCashIn()) {
    $cashIn = $event->asCashIn();
    echo "Pagamento recebido: R$ {$cashIn->amount}";
    echo "Pagador: {$cashIn->debtorName}";
    echo "Documento: {$cashIn->debtorDocument}";
    echo "TX ID: {$cashIn->txId}";

    if ($cashIn->isPaid()) {
        // Pagamento confirmado
    } elseif ($cashIn->isRefunded()) {
        // Pagamento estornado
    }
}

if ($event->isCashOut()) {
    $cashOut = $event->asCashOut();
    echo "Saque: R$ {$cashOut->amount}";

    if ($cashOut->isSuccess()) {
        // Saque realizado com sucesso
    } elseif ($cashOut->isError()) {
        echo "Erro: {$cashOut->error}";
    } elseif ($cashOut->isRefunded()) {
        // Saque estornado
    }
}

Tipos de eventos

Cash-in:

• QR_CODE_COPY_AND_PASTE_PAID - Pagamento via QR Code confirmado
• QR_CODE_COPY_AND_PASTE_REFUNDED - Pagamento via QR Code estornado

Cash-out:

• PIX_CASHOUT_SUCCESS - Saque realizado com sucesso
• PIX_CASHOUT_ERROR - Erro no saque
• PIX_CASHOUT_REFUNDED - Saque estornado

Tratamento de erros

use NXGate\NXGateException;

try {
    $charge = $nx->pixGenerate(new PixGenerateRequest(
        valor: 100.00,
        nomePagador: 'João',
        documentoPagador: '12345678901',
    ));
} catch (NXGateException $e) {
    echo $e->title;       // título do erro
    echo $e->description; // descrição detalhada
    echo $e->httpStatus;  // código HTTP (0 para erros de rede)
    echo $e->getCode();   // código do erro da API
    echo $e->getMessage(); // mensagem formatada completa
}

O SDK trata automaticamente os seguintes cenários:

• Autenticação: Token renovado automaticamente antes de expirar
• Retry: Requisições que retornam HTTP 503 são reenviadas automaticamente com backoff exponencial (máximo 2 tentativas)
• HMAC: Assinatura automática quando hmacSecret é configurado
• Erros de rede: Encapsulados em NXGateException com detalhes do cURL

Testes

composer install
vendor/bin/phpunit

Licença

MIT - consulte o arquivo LICENSE para detalhes.