Passa al contenuto principale

Autenticazione e configurazioni

L’integrazione con la piattaforma Numia richiede una corretta configurazione tecnica e la gestione dei meccanismi di autenticazione previsti dal gateway.
In questa sezione vengono descritti:

  • i parametri necessari per l’inizializzazione delle transazioni;
  • il calcolo della signature;
  • la configurazione degli URL di ritorno;
  • le logiche di autenticazione e verifica delle richieste.

Una configurazione coerente e sicura garantisce:

  • integrità dei dati trasmessi;
  • protezione contro manomissioni delle richieste;
  • corretta associazione tra transazione e ordine merchant.

Questa sezione rappresenta il riferimento tecnico per assicurare un’integrazione corretta e conforme alle specifiche del gateway.

1. Introduzione​

In questa sezione viene descritto come firmare le richieste API per le chiamate REST ai web service Numia, nell’ambito dell’integrazione con i servizi di pagamento eCommerce. La corretta implementazione del meccanismo di firma è un requisito essenziale per garantire autenticazione, integrità e protezione delle comunicazioni tra merchant e gateway.

2. Passi da seguire​

Questi sono i passi necessari per la firma di una richiesta:

  1. Creare un messaggio di richiesta HTTP.
  2. Creare una stringa in base alle parti del messaggio di richiesta.
  3. Calcolare la firma, sulla stringa creata al punto precedente, usando l’algoritmo HMAC‑SHA256.
  4. Aggiungere la firma generata e altre informazioni obbligatorie nell’intestazione Authorization.

Per informazioni dettagliate su come eseguire i passi 2–4, fare riferimento alla specifica https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-10, che descrive come formare la stringa da firmare, come calcolare la firma e come inserirla nel messaggio di richiesta HTTP.

3. Implementazione​

Intestazioni obbligatorie​

Sono le intestazioni che devono essere incluse nella stringa da firmare.

Per i messaggi di richiesta GET e DELETE (quando il body è assente), la stringa deve includere almeno:

  • host (es. host:port in caso di porta diversa da 80 o 443)
  • date (in formato RFC 1123)
  • (request-target) (come descritto nella specifica HTTP Signatures)

Per i messaggi di richiesta PUT e POST (con body presente), la stringa deve includere almeno:

  • host
  • date
  • (request-target)
  • digest nel formato: SHA-256=<hash base64 del contenuto del body>

Esempio di valore digest:

SHA-256=6iJfkOF3ra8+t09DtcpwjR6Kxt6lnv+aF5GtzZm6ue0=

Per i messaggi di tipo multipart/form-data, la stringa deve includere almeno:

  • host
  • date
  • (request-target)

URL encoding del path e query string​

Durante la costruzione della stringa da firmare, applicare l’URL encoding a tutti i parametri presenti nel path e nella query string (ma non alle intestazioni), come specificato nella RFC 3986.

Key Identifier​

Nell’intestazione Authorization si deve impostare il parametro keyId con lo stesso valore del merId presente nel messaggio di richiesta, ad esempio:

keyId="1234567890"

Algoritmo della firma​

L’algoritmo della firma deve essere HMAC‑SHA256. Nell’intestazione Authorization va indicato come:

algorithm="hmac-sha256"

prestando attenzione all’uso corretto delle virgolette.

4. Esempi​

Esempio di intestazione Authorization​

Di seguito un esempio della sintassi generale di un’intestazione Authorization per una richiesta con body:

Authorization: Signature keyId="${merId}",algorithm="hmac-sha256",headers="host date (request-target) digest",signature="${Base64(HMAC-SHA256(signing_string))}"

Per le specifiche complete sulla formazione della stringa da firmare, consultare: https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-10

Esempi di codice​

Di seguito alcuni esempi di librerie e riferimenti per firmare le richieste API in diversi linguaggi:

5. Endpoint​

Di seguito gli endpoint base da utilizzare per le chiamate ai web service Numia, in base all'ambiente di destinazione.

AmbienteURL base
Testhttps://testecommerce.numiapos.com/SINE_CG_SERVICES
Produzionehttps://ecommerce.numiapos.com/IGFS_CG_SERVICES

Negli esempi di questa documentazione il placeholder {{endpoint}} va sostituito con l'URL base corrispondente all'ambiente in uso (Test o Produzione).