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.

php

use Erilshk\Sisp\Vinti4Net;

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

Construtor

php

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`	URL completa alternativa para as operações, incluindo tokenização; 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 15 caracteres; a aplicação continua responsável pela unicidade
`preparePurchase(float	string $amount, array	Billing $billing, string $currency = Currency::CVE)`
`prepareServicePayment(float	string $amount, int $entity, string $number)`	`static`
`prepareRecharge(float	string $amount, int $entity, string $number)`	`static`
`prepareRefund(float	string $amount, string $transactionID, string $clearingPeriod)`	`static`
`prepareTokenRequest(float	string $minimumAmount)`	`static`
`prepareTokenPurchase(string $token, float	string $amount)`	`static`
`prepareTokenServicePayment(string $token, float	string $amount, int $entity, string $number)`	`static`
`prepareTokenRecharge(string $token, float	string $amount, int $entity, string $number)`	`static`
`prepareTokenCancellation(string $token)`	`static`	Prepara cancelamento com montante zero
`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
`processTokenResponse(array $postData, ?string $expectedCode = null)`	`Vinti4Response`	Valida callback tokenizado; prefira o código da operação persistida
`getRequest()`	`array`	Retorna a requisição preparada

Gerar uma referência

php

// 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

php

// 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.

php

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 e morada; código postal desconhecido usa 0000; 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 com chaves SISP
`account()`	ID, datas e indicadores da conta com parâmetros nomeados
`suspicious()`	Marca ou desmarca atividade suspeita

Classe `Vinti4Response`

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

php

$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`	Depreciado na v2.4.0; use a moeda guardada no pedido. Para DCC, use `dcc['currency']`
`getAdditionalErrorMessage()`	`string`	`merchantRespAdditionalErrorMessage`
`getMaskedPan()`	`?string`	Exibe apenas os últimos quatro dígitos
`getToken()`	`?string`	Token opaco retornado no enrollment; só usar após validar sucesso
`getTokenDescription()`	`?string`	Descrição devolvida no enrollment
`getTokenLimits()`	`array<string, string>`	Limites do token devolvidos no enrollment
`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 = [])`
`renderDccReceipt()`	Recibo DCC com dados retornados pela SISP
`generateReceiptHtml()`	Compatibilidade da API v2
`generateReceiptText()`	Recibo em texto simples

DCC

php

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

markup é um montante, não uma percentagem.

Exceção `Vinti4Exception`

php

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.

Tokenização (v2.5)

Método de Vinti4Net	Operação
`prepareTokenRequest($minimumAmount)`	Enrollment, código 5
`prepareTokenPurchase($token, $amount)`	Compra, código 6
`prepareTokenServicePayment($token, $amount, $entity, $number)`	Serviço, código 2
`prepareTokenRecharge($token, $amount, $entity, $number)`	Recarga, código 3
`prepareTokenCancellation($token)`	Cancelamento, código 7, montante zero
`processTokenResponse($postData, $expectedCode = null)`	Valida callback de token e contexto esperado

As preparações são fluentes e usam createPaymentForm() para gerar o HTML. O construtor mantém exatamente os três argumentos anteriores; os endpoints padrão de tokenização estão centralizados em Core\Token e podem ser personalizados pelo argumento endpoint já existente no construtor. Vinti4Response acrescenta getToken(), getTokenDescription() e getTokenLimits(). Veja Tokenização para configuração e contrato.

processTokenResponse() deve receber, como segundo argumento, o código esperado obtido do pedido guardado: 5 para adesão, 6 para compra, 2 para serviço, 3 para recarga e 7 para cancelamento. Os callbacks assinados usam A para adesão, B para pagamentos e C para cancelamento. Verifique isSuccess() e correlacione referência e sessão antes de guardar token ou limites. O token é uma string opaca; preserve zeros iniciais e o conteúdo recebido.

setMerchant($reference, $session = null) aceita uma referência não vazia, sem comprimento fixo. A sessão também deve ser não vazia, sem comprimento fixo. generateMerchantRef() permanece público e estático, com geração padrão e aleatória de 15 caracteres.

API Reference – Vinti4Net PHP SDK ​

Classe Vinti4Net ​

Construtor ​

Métodos principais ​

Gerar uma referência ​

Exemplo de compra ​

Classe Billing ​

Criação e conversão ​

Dados de faturação ​

Entrega, contacto e conta ​

Classe Vinti4Response ​

Propriedades ​

Métodos de estado ​

Métodos de dados ​

Recibos ​

DCC ​

Exceção Vinti4Exception ​

Tokenização (v2.5) ​