Processar a resposta

O callback deve criar o cliente com as mesmas credenciais e entregar o POST original à biblioteca.

$vinti4 = new Vinti4Net($posID, $authCode);
$response = $vinti4->processResponse($_POST);

Um array vazio lança Vinti4Exception.

Retorno bloqueado ou sessão ausente

O endereço de resposta deve aceitar o POST externo sem depender da sessão de login. Se houver bloqueios de origem/CORS, CSRF ou autenticação, ou se o cliente aparecer sem sessão, consulte Retorno e sessão no FAQ.

Ordem recomendada

if ($response->hasInvalidFingerprint()) {
    http_response_code(400);
    exit('Resposta inválida.');
}

if ($response->isCancelled()) {
    exit('Pagamento cancelado.');
}

if ($response->hasFailed()) {
    http_response_code(422);
    exit($response->message);
}

if ($response->isSuccess()) {
    // Validar contra o pedido salvo e confirmar uma única vez.
}

Estados

Estado	Método	Significado
SUCCESS	isSuccess()	Tipo de sucesso e fingerprint válido
CANCELLED	isCancelled()	Utilizador cancelou
ERROR	hasFailed()	Recusa ou erro devolvido pela SISP
INVALID_FINGERPRINT	hasInvalidFingerprint()	Resposta assinada com fingerprint ausente ou inválido

hasFailed() só é verdadeiro para ERROR. Verifique hasInvalidFingerprint() separadamente e antes de qualquer lógica de confirmação.

Mensagens de erro

A mensagem apresentada usa, quando disponível, o primeiro destes campos:

1. merchantRespAdditionalErrorMessage;
2. merchantRespErrorDetail;
3. merchantRespErrorDescription;
4. mensagem genérica.

echo $response->message;
echo $response->detail ?? '';

Dados principais

$transactionId = $response->getTransactionId();
$clearingPeriod = $response->getClearingPeriod();
$reference = $response->getMerchantRef();
$amount = $response->getAmount();
$dccCurrency = $response->dcc['currency'] ?? null; // Moeda DCC; não é a moeda do pedido.

Todos podem retornar null quando o campo não existir naquele tipo de resposta.

Em compras aprovadas, o SDK exige a confirmação merchantResp=C e um fingerprint válido. Em estornos aprovados, o tipo de resposta é 10; o campo merchantResp não precisa de ser C. Um erro de resposta não identifica necessariamente a operação: operation fica null. Consulte a compra ou o estorno pendente pela referência guardada. Se o fingerprint de uma resposta de sucesso for inválido, hasInvalidFingerprint() tem prioridade sobre um sinal de cancelamento.

Array e JSON seguros

$array = $response->toArray();
$json = $response->toJson();

Esses métodos mascaram merchantRespPan. A propriedade $response->data mantém o payload original e deve ser tratada como sensível.

Para dúvidas sobre erros e cancelamentos, consulte Perguntas frequentes.

O cancelamento retorna merchantRef, merchantSession e UserCancelled, sem messageType nem fingerprint. Esse callback resulta em CANCELLED; a flag não substitui o estado de uma resposta de sucesso ou erro que tenha messageType. O tipo 6 é autenticado com sua fórmula própria: erros adulterados ou sem fingerprint resultam em INVALID_FINGERPRINT.

getCurrency() está depreciado desde a v2.4.0: a resposta documentada não retorna a moeda do pedido. Use a moeda guardada no pedido original. Para a moeda DCC, use $response->dcc['currency'] ?? null.