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\Sisp\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->preparePurchase(
    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->prepareRecharge(
    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',
    lang: 'pt' // Opcional: languageMessages
);

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 DB
    // 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	`preparePurchase()`	Compras com autenticação 3D Secure
🧾 Serviço	`prepareServicePayment()`	Pagamento de entidades (água, luz, etc.)
📱 Recarga	`prepareRecharge()`	Recarga de telemóvel
💰 Reembolso	`prepareRefund()`	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->prepareRefund(
    amount: 1500.00,
    merchantRef: 'E_REFERENCE',
    transactionID: 'TXN78901',
    clearingPeriod: '2411'
);

🛡️ Tratamento de Erros

try {
    $vinti4->preparePurchase(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

🔗 Links Úteis

📄 Licença

MIT License - veja LICENSE para detalhes.

🤝 Contribuições

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

Desenvolvido com ❤️ para Cabo Verde

erilshk / vinti4net

Maintainers

Details