Salta ai contenuti
SanPay Docs

Sicurezza e Antifrode

Sicurezza e Antifrode

SanPay è costruito con la sicurezza al centro. Dai webhook firmati HMAC alla validazione dell'origine, proteggiamo ogni transazione e punto di integrazione.

Sicurezza Chiavi API

Le tue chiavi API sono il gateway al tuo account. Segui queste best practice:

Separa le Chiavi per Ambiente

Usa `pk_test_*` e `sk_test_*` per sviluppo, `pk_live_*` e `sk_live_*` per produzione.

Non Esporre Mai le Chiavi Segrete

Le chiavi segrete (sk_*) devono rimanere sul tuo server. Non includerle mai nel codice client o app mobile.

Ruota le Chiavi Regolarmente

Genera nuove chiavi API periodicamente e revoca quelle vecchie dalla dashboard.

Usa Variabili d'Ambiente

Conserva le chiavi in variabili d'ambiente, non nei repository di codice.

Tipi di Chiave

Tipo ChiavePrefissoUtilizzo
Chiave Pubblica pk_live_* / pk_test_* Inizializzazione SDK lato client
Chiave Segreta sk_live_* / sk_test_* Chiamate API server-to-server
Segreto Webhook whsec_* Verifica firme webhook in entrata

Verifica Firma Webhook

Ogni webhook include una firma HMAC-SHA256 per verificare l'autenticità e prevenire manomissioni.

Formato Firma

L'header `X-Webhook-Signature` contiene:

t=1704556800000,v1=a1b2c3d4e5f6...

Algoritmo di Verifica

  1. Estrai timestamp (t) e firma (v1) dall'header
  2. Verifica che il timestamp sia entro la finestra accettabile (5 minuti)
  3. Calcola atteso: HMAC-SHA256(secret, "{timestamp}.{body}")
  4. Usa confronto timing-safe per verificare la firma
Signature Verification
// PHP Signature Verification
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';


// Parse signature
preg_match('/^t=(\d+),v1=([a-f0-9]+)$/', $signature, $matches);
$timestamp = (int) $matches[1];
$receivedHash = $matches[2];


// Check timestamp (5 minute tolerance)
$now = (int) (microtime(true) * 1000);
if (abs($now - $timestamp) > 300000) {
    throw new Exception('Signature expired');
}


// Verify signature
$signedPayload = "{$timestamp}.{$payload}";
$expectedHash = hash_hmac('sha256', $signedPayload, $webhookSecret);


if (!hash_equals($expectedHash, $receivedHash)) {
    throw new Exception('Invalid signature');
}

Perché Confronto Timing-Safe?

Il confronto standard di stringhe può rivelare informazioni attraverso i tempi di risposta. Gli attaccanti potrebbero dedurre la firma carattere per carattere. Il confronto timing-safe impiega tempo costante indipendentemente dalla posizione del match.

Validazione Origine

L'SDK valida che le richieste provengano da domini autorizzati:

  • Configura le origini consentite nella tua dashboard SanPay
  • Includi protocollo, dominio e porta: https://example.com:443
  • Usa i wildcard con attenzione: https://*.example.com

Protezione Replay Attack

I webhook includono timestamp per prevenire attacchi replay:

  • Rifiuta firme più vecchie di 5 minuti
  • Memorizza gli eventId elaborati per rilevare duplicati
  • Tutte le comunicazioni via HTTPS prevengono intercettazioni

Rate Limiting

Gli endpoint API sono rate-limited per prevenire abusi:

EndpointLimiteFinestra
Creazione pagamento 100 req al minuto
Controllo stato 300 req al minuto
Lista asset 60 req al minuto

Best Practice di Sicurezza

Verifica Sempre i Webhook

Non elaborare mai un webhook senza verificarne la firma. Gli attaccanti potrebbero inviare false conferme di pagamento.

Usa Idempotenza

Traccia gli eventId per evitare di elaborare lo stesso evento due volte, specialmente per l'evasione ordini.

Valida gli Importi

Confronta sempre l'importo ricevuto con quello atteso. Gestisci esplicitamente sottopagamenti e sovrapagamenti.

Solo HTTPS

Consegniamo webhook solo a endpoint HTTPS. Assicurati che il tuo server abbia un certificato SSL valido.