API Reference – Vinti4Net PHP SDK¶

Consulte aqui as assinaturas, retornos e parâmetros públicos do SDK para integração com Vinti4/SISP.

Classe `Vinti4Net`¶

É a fachada principal do SDK. Ela prepara pagamentos e reembolsos, gera o formulário e processa o callback.

use Erilshk\Sisp\Vinti4Net;

$vinti4 = new Vinti4Net($posID, $posAuthCode, $endpoint);

Construtor¶

new Vinti4Net(
    string $posID,
    string $posAuthCode,
    ?string $endpoint = null,
)

Parâmetro	Descrição
`posID`	Identificador POS fornecido pela SISP
`posAuthCode`	Código secreto de autenticação
`endpoint`	Endpoint alternativo; opcional

Métodos principais¶

Método	Retorno	Descrição
`setRequestParams(array $params)`	`self`	Configura parâmetros permitidos
`setMerchant(string $reference, ?string $session = null)`	`self`	Define referência e sessão
`generateMerchantRef(bool $random = false)` (estático)	`string`	Gera uma referência de exatamente 15 caracteres
`preparePurchase(float\|string $amount, array\|Billing $billing, string $currency = 'CVE')`	`static`	Prepara compra; passe `[]` para não enviar billing
`prepareServicePayment(float\|string $amount, int $entity, string $number)`	`static`	Prepara pagamento de serviço
`prepareRecharge(float\|string $amount, int $entity, string $number)`	`static`	Prepara recarga
`prepareRefund(float\|string $amount, string $transactionID, string $clearingPeriod)`	`static`	Prepara reembolso
`createPaymentForm(string $responseUrl, string $lang = 'pt')`	`string`	Gera o formulário auto-submit
`processResponse(array $postData)`	`Vinti4Response`	Processa o retorno da SISP; `10` indica estorno bem-sucedido
`getRequest()`	`array`	Retorna a requisição preparada

Gerar uma referência¶

// R + ymdHis + dois caracteres aleatórios
$reference = Vinti4Net::generateMerchantRef();

// R + 14 caracteres hexadecimais aleatórios
$reference = Vinti4Net::generateMerchantRef(random: true);

O formato padrão preserva uma parte cronológica e adiciona um sufixo aleatório. O modo totalmente aleatório não expõe a data da criação.

Exemplo de compra¶

// R + ymdHis + dois caracteres aleatórios
$reference = Vinti4Net::generateMerchantRef();


$billing = \Erilshk\Sisp\Billing::from([
    'email' => 'cliente@exemplo.cv',
    'country' => '132',
    'city' => 'Praia',
    'address' => 'Avenida Cidade da Praia, 45',
    'postalCode' => '7600',
]);

echo $vinti4
    ->setMerchant($reference)
    ->preparePurchase(1500, $billing)
    ->createPaymentForm('https://meusite.cv/retorno');

Sem billing, use preparePurchase(1500, []). O segundo argumento é obrigatório. setRequestParams() aceita somente merchantRef, merchantSession, languageMessages e timeStamp; os restantes dados são passados ao método da operação.

Classe `Billing`¶

Representa e normaliza dados de faturação, endereço, contactos e conta do cliente para compras 3DS.

use Erilshk\Sisp\Billing;

$billing = Billing::make()
    ->email('cliente@exemplo.cv')
    ->country('132')
    ->city('Praia')
    ->address('Avenida Cidade da Praia, 45')
    ->postalCode('7600')
    ->mobilePhone('238', '9912345')
    ->accountId('12345');

O país de faturação usa 132 por padrão. Se enviar billing, forneça email, cidade, morada e código postal; se não quiser enviar billing, passe [] a preparePurchase().

Criação e conversão¶

Método	Descrição
`make()`	Cria um builder vazio
`from(array $data)`	Cria o Billing a partir de um array
`fill(array $data)`	Preenche o objeto existente
`toArray()`	Retorna somente os campos preenchidos

Dados de faturação¶

Método	Campo SISP
`email()`	`email`
`country()`	`billAddrCountry`
`city()`	`billAddrCity`
`address()`	`billAddrLine1`
`address2()`	`billAddrLine2`
`address3()`	`billAddrLine3`
`postalCode()`	`billAddrPostCode`
`state()`	`billAddrState`

Entrega, contacto e conta¶

Método	Descrição
`shipCountry()`	País de entrega
`shipCity()`	Cidade de entrega
`shipAddress()`	Endereço de entrega
`shipPostalCode()`	Código postal de entrega
`shipState()`	Estado/região de entrega
`addressMatchesShipping()`	Define `addrMatch` como `Y` ou `N`
`mobilePhone()`	Telefone móvel com país e número
`workPhone()`	Telefone de trabalho
`accountId()`	ID da conta do cliente
`accountInfo()`	Informações 3DS da conta
`suspicious()`	Marca ou desmarca atividade suspeita

Classe `Vinti4Response`¶

Normaliza o resultado da SISP e expõe estado, mensagem, dados, DCC, debug e detalhe.

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

if ($response->isSuccess()) {
    echo 'Aprovada: ' . $response->getAmount();
} elseif ($response->hasInvalidFingerprint()) {
    echo 'Resposta inválida.';
} elseif ($response->isCancelled()) {
    echo 'Cancelada pelo utilizador.';
} else {
    echo $response->message;
}

Propriedades¶

Propriedade	Tipo	Descrição
`status`	`string`	`SUCCESS`, `ERROR`, `CANCELLED` ou `INVALID_FINGERPRINT`
`message`	`string`	Mensagem amigável ou erro devolvido
`success`	`bool`	Verdadeiro somente em sucesso validado
`data`	`array`	Payload original da SISP
`dcc`	`array`	Dados DCC normalizados
`debug`	`array`	Dados de diagnóstico do fingerprint
`detail`	`?string`	Detalhe do erro, quando disponível
`operation`	`?string`	`refund` para `10`; `payment` para `8`, `P` e `M`; `null` para erro `6` ou cancelamento sem operação identificável

Métodos de estado¶

Método	Descrição
`isSuccess()`	Confirma sucesso validado
`isCancelled()`	Confirma cancelamento
`hasInvalidFingerprint()`	Detecta fingerprint inválido
`hasFailed()`	Detecta apenas estado `ERROR`, sem incluir fingerprint inválido

Métodos de dados¶

Método	Retorno	Campo SISP
`getTransactionId()`	`?string`	`merchantRespTid`
`getClearingPeriod()`	`?string`	`merchantRespCP`
`getMerchantRef()`	`?string`	`merchantRespMerchantRef`
`getAmount()`	`?float`	`merchantRespPurchaseAmount`
`getCurrency()`	`?string`	`merchantRespCurrency`
`getAdditionalErrorMessage()`	`string`	`merchantRespAdditionalErrorMessage`
`getMaskedPan()`	`?string`	Exibe apenas os últimos quatro dígitos
`toArray()`	`array`	Resposta normalizada com PAN mascarado
`toJson()`	`string`	JSON formatado com PAN mascarado

Recibos¶

Método	Descrição
`renderReceipt()`	Recibo padrão ou template personalizado
`renderRefundReceipt(int\|string $amount, ?string $originalTransactionId = null, array $data = [])`	Recibo de estorno aprovado; valor e ID original são fornecidos pela aplicação
`renderDccReceipt()`	Recibo DCC com dados retornados pela SISP
`generateReceiptHtml()`	Compatibilidade da API v2
`generateReceiptText()`	Recibo em texto simples

DCC¶

[
    'enabled' => true,
    'amount' => '10.58',
    'currency' => 'USD',
    'markup' => '0.31',
    'rate' => '92.65882',
]

markup é um montante, não uma percentagem.

Exceção `Vinti4Exception`¶

use Erilshk\Sisp\Exceptions\Vinti4Exception;

try {
    echo $vinti4->createPaymentForm($callbackUrl);
} catch (Vinti4Exception $exception) {
    echo $exception->getMessage();
}

As falhas da biblioteca usam essa exceção pública.