README

SDK PHP para integração com o sistema de pagamentos Vinti4Net (SISP Cabo Verde, Serviço MOP021).

📦 Instalação

composer require erilshk/vinti4net

🚀 Começo Rápido

1. Configuração Básica

<?php

require_once 'vendor/autoload.php';

use Erilshk\Vinti4Net\Vinti4Net;

// Configuração
$vinti4 = new Vinti4Net(
    posID: 'SEU_POS_ID',           // Fornecido pelo SISP
    posAuthCode: 'SEU_AUTH_CODE',  // Fornecido pelo SISP
    endpoint: null                 // Opcional: URL customizada para testes
);

2. Criar Pagamento

// Pagamento com 3DS (Compra)
$vinti4->preparePurchasePayment(
    amount: 1500.00,
    billing: [
        'email' => 'cliente@email.com',
        'billAddrCountry' => '132', // Código do país (132 = Cabo Verde)
        'billAddrCity' => 'Praia',
        'billAddrLine1' => 'Rua Exemplo, 123',
        'billAddrPostCode' => '7600'
    ],
    currency: 'CVE' // opcional
);

// Ou pagamento de serviço (Água, Luz, etc.)
$vinti4->prepareServicePayment(
    amount: 2500.00,
    entity: 10001,        // Código da entidade (ex: ELECTRA)
    number: '123456789'   // Referência do cliente
);

// Ou recarga de telemóvel
$vinti4->prepareRechargePayment(
    amount: 500.00,
    entity: 10021,        // Código da operadora (ex: CVMóvel)
    number: '9912345'     // Número de telefone
);

3. Gerar Formulário de Pagamento

$htmlForm = $vinti4->createPaymentForm(
    responseUrl: 'https://seusite.com/pagamento/callback',
    merchantRef: 'PEDIDO_12345' // Opcional: referência interna
);

echo $htmlForm; // Formulário auto-submissível

4. Processar Resposta (Callback)

// No seu endpoint de callback (ex: /pagamento/callback)
$response = $vinti4->processResponse($_POST);

if ($response->isSuccess()) {
    // Pagamento aprovado
    $transactionId = $response->getTransactionId();
    $amount = $response->getAmount();
    
    // Atualizar banco de dados
    // Liberar produto/serviço
    
} elseif ($response->isCancelled()) {
    // Usuário cancelou
    echo "Pagamento cancelado pelo usuário";
    
} elseif ($response->hasInvalidFingerprint()) {
    // Erro de segurança
    error_log("Fingerprint inválido: " . json_encode($response->debug));
    
} else {
    // Erro no pagamento
    echo "Erro: " . $response->message;
    echo "Detalhe: " . $response->detail;
}

📋 Tipos de Transação

Tipo	Método	Descrição
💳 Compra 3DS	`preparePurchasePayment()`	Compras com autenticação 3D Secure
🧾 Serviço	`prepareServicePayment()`	Pagamento de entidades (água, luz, etc.)
📱 Recarga	`prepareRechargePayment()`	Recarga de telemóvel
💰 Reembolso	`prepareRefundPayment()`	Estorno de transação

🧾 Gerar Recibo

$response = $vinti4->processResponse($_POST);

// Gerar recibo HTML
$receiptHtml = $response->generateReceiptHtml(
    companyName: 'Sua Empresa Lda',
);

echo $receiptHtml;

🔧 Configuração Avançada

Parâmetros Customizados

$vinti4->setRequestParams([
    'merchantRef' => 'REF_CUSTOM',
    'merchantSession' => 'SESS_CUSTOM',
    'languageMessages' => 'pt', // ou 'en'
    'timeStamp' => '2024-01-01 12:00:00'
]);

Reembolso

$vinti4->prepareRefundPayment(
    amount: 1500.00,
    merchantRef: 'PEDIDO_ORIGINAL',
    merchantSession: 'SESSAO_ORIGINAL',
    transactionID: 'TXN78901',
    clearingPeriod: '2411'
);

🛡️ Tratamento de Erros

try {
    $vinti4->preparePurchasePayment(1500, $billing);
    $form = $vinti4->createPaymentForm('https://callback.com');
    echo $form;
    
} catch (InvalidArgumentException $e) {
    echo "Erro de validação: " . $e->getMessage();
    
} catch (Exception $e) {
    echo "Erro geral: " . $e->getMessage();
}

🧪 Testes

# Executar testes
composer test

# Testes com cobertura
composer test-coverage

📁 Estrutura do Projeto

src/
├── Core/
│   ├── Sisp.php          # Classe base abstrata
│   ├── Payment.php       # Operações de pagamento
│   └── Refund.php        # Operações de reembolso
├── Traits/
│   └── ReceiptRenderer.php # Geração de recibos
├── Vinti4Net.php         # Classe principal
├── Billing.php           # Classe para montar Billing
└── Vinti4Response.php    # Resposta processada

🔗 Links Úteis

📄 Licença

MIT License - veja LICENSE para detalhes.

🤝 Contribuições

Contribuições são bem-vindas! Por favor, leia CONTRIBUTING.md antes de enviar Pull Requests.

Desenvolvido com ❤️ para Cabo Verde

erilshk / vinti4net

Maintainers

Details