Passa al contenuto principale

Notifiche S2S

Introduzione​

Fabrick offre la possibilità di inviare notifiche server-to-server alle TPP/FPP affinché possa ricevere aggiornamenti, in modo asincrono, sugli eventi a cui si è registrato.

La registrazione agli eventi da parte avviene durante la fase di setup, nella quale la TPP/FPP comunicherà a Fabrick i messaggi e le informazioni che desidera ricevere.

Configurazione dell'FPP​

La TPP/FPP deve esporre sul proprio server un endpoint su cui ricevere le notifiche.

L'endpoint deve essere unico indipendentemente dall'ambiente (test o produzione)

L'endpoint può essere scelto liberamente purché rispetti le seguenti condizioni:

  • Metodo POST
  • Protocollo HTTPS
  • Porta 443

Al momento, la TPP/FPP dovrà comunicare l'endpoint a Fabrick tramite email.

La TPP/FPP ha la possibilità di esporre due endpoint: uno per l'ambiente di pre-produzione e uno per quello di produzione. In questo modo sarà possibile effettuare la fase di test.

IP range​

Questi saranno gli IP range da cui verranno inviate le notifiche S2S:

  • 213.218.32.0/21
  • 213.218.40.0/21
  • 213.218.48.0/21

Modello dei messaggi​

Non è necessario specificare alcun header, mentre nel corpo della richiesta verrà inviato solo il parametro jwt, che sarà valorizzato con un jwt.

Se il messaggio viene ricevuto correttamente, verrà restituito il codice di stato HTTP 200. Se Fabrick riceve un codice di errore, verrà applicata una logica di retry fino a quando il messaggio non sarà stato consegnato correttamente.

Di seguito è riportato un esempio di richiesta che Fabrick invierà alla TPP/FPP:

POST /api/fabrick/consumers/v1.0/webhook/notifications
{
    "jwt":"[JWT]"
}

e la risposta attesa in caso di successo

HTTP 200

Il JWT rispetterà sempre il seguente formato:

{
    "iat": 1665579767,
    "exp": 1665579467,
    "eventId": "1",
    "eventType": "PAYMENT_STATUS",
    "eventMetaData":{
        [dettagli evento]
    }
}

dove:

  • iat: indica la data di creazione del token (e quindi della notifica) in UTC. Unix Epoch Time in secondi
  • exp: indica la data di scadenza del token in UTC. Unix Epoch Time in secondi
  • eventId: indica l'identificativo univoco dell'evento. Utile in caso di debug
  • eventType: è di tipo stringa e indica il tipo di evento ricevuto. In base a questa costante, il formato dell'oggetto eventMetaData conterrà parametri e informazioni differenti
  • eventMetaData: oggetto contenente le informazioni di interesse per la TPP/FPP. L'oggetto avrà proprietà diverse in base all'eventType.

Caso speciale PRE / PRO​

Esiste la possibilità che la stessa notifica venga inviata sia nell'ambiente di PRE-produzione che in quello di produzione.

Ciò accade per i pagamenti che rimangono in stato pendente durante una fase di Business Copy di Fabrick (ad esempio nel fine settimana). In questo caso, non appena lo stato pendente cambia (ad es. in EXECUTED_DEBTOR), la stessa notifica verrà inviata sia nell'ambiente di PRE-produzione che in quello di produzione:

PRO

{
  "eventMetaData": {
    "paymentRequestId": "54687d4c-ff88-4ce7-8c3b-91042e952f38",
    "status": "EXECUTED_DEBTOR"
  },
  "eventType": "PAYMENT_STATUS",
  "exp": 1722223720,
  "iat": 1722223420
}

PRE

{
  "eventMetaData": {
    "paymentRequestId": "54687d4c-ff88-4ce7-8c3b-91042e952f38",
    "status": "EXECUTED_DEBTOR"
  },
  "eventType": "PAYMENT_STATUS",
  "exp": 1722223727,
  "iat": 1722223427
}

Politiche di retry​

Come indicato in precedenza, nel caso in cui l'endpoint non sia raggiungibile o restituisca un codice di errore HTTP, verrà attivata la politica di retry basata sul metodo Exponential Backoff con i seguenti parametri:

  • Intervallo (sec): 60 secondi
  • Numero massimo di tentativi: 13
  • Esponenziale: 2
  • La tabella seguente mostra l'intervallo di tempo dei diversi tentativi e un esempio di timestamp:
TentativoSecondiEsempio di timestamp
00.00014/10/2022, 13:28:54:972 UTC
160.00014/10/2022, 13:29:54:972 UTC
2180.00014/10/2022, 13:31:54:972 UTC
3420.00014/10/2022, 13:35:54:972 UTC
4900.00014/10/2022, 13:43:54:972 UTC
51860.00014/10/2022, 13:59:54:972 UTC
63780.00014/10/2022, 14:31:54:972 UTC
77620.00014/10/2022, 15:35:54:972 UTC
815300.00014/10/2022, 17:43:54:972 UTC
930660.00014/10/2022, 21:59:54:972 UTC
1061380.00015/10/2022, 06:31:54:972 UTC
11122820.00015/10/2022, 23:35:54:972 UTC
12245700.00017/10/2022, 09:43:54:972 UTC

Caso d'uso​

Il sistema di notifiche S2S è attualmente utilizzato esclusivamente per il mondo dei pagementi, in particolare per due casi distinti:

  • Notifica pispStatus
  • Notifica di accredito (solo per il prodotto Pass Pay by Bank e account Fabrick)

Notifica pispStatus​

In questo caso Fabrick invierà una notifica alla TPP/FPP ad ogni cambio di stato di tutti i pagamenti effettuati. Il vantaggio per la TPP/FPP è evidentemente quello di evitare la fase di polling continuo per ogni pagamento tramite i metodi GET GetPaymentDetails o POST SearchPayments.

Si raccomanda di implementare questa soluzione ed evitare così il polling tramite API. Soprattutto se si utilizza il pay-by-link.

Di seguito è riportato un esempio completo di messaggio decodificato ricevuto:

{
    "eventId": "1001",
    "eventMetaData": {
        "paymentRequestId": "9f92374a-xxxx-xxxx-xxxx-458da1f41234",
        "status": "EXECUTED_DEBTOR"
    },
    "eventType": "PAYMENT_STATUS",
    "exp": 1666096578,
    "iat": 1666096278
}

dove:

  • paymentRequestId: indica il riferimento del pagamento effettuato con Fabrick Pass
  • status: indica lo stato del pagamento, in base al parametro pispStatus (si veda il documento Pisp Details). Gli stati da inviare saranno concordati durante la fase di setup. In generale si raccomandano tutti gli stati finali ed eventualmente gli stati ONGOING e INITIALIZED. Non è possibile notificare lo stato CREATED.

Come si può vedere dall'esempio precedente, in questo caso non sono presenti informazioni sensibili, pertanto i messaggi non saranno cifrati. Saranno invece firmati con una chiave Fabrick in modo che l'FPP possa verificare l'autenticità del messaggio ricevuto tramite la chiave pubblica. L'algoritmo utilizzato è RS256.

Esempio​

Fabrick invierà un messaggio come nel seguente esempio:

{
"jwt":"eyJhbGciOiJSUzI1NiJ9.eyJldmVudElkIjoiMTEwMTUiLCJldmVudE1ldGFEYXRhIjp7InBheW1lbnRSZXF1ZXN0SWQiOiJhZmEyODk0Ni1iNDgwLTRjZmYtOGNjZi03YWQ5ZDljZWY5OTgiLCJzdGF0dXMiOiJJTklUSUFMSVpFRCJ9LCJldmVudFR5cGUiOiJQQVlNRU5UX1NUQVRVUyIsImV4cCI6MTY4ODYzMzI0NiwiaWF0IjoxNjg4NjMyOTQ2fQ.f6dFGcmYblGZvSNN6CwOe-mikT5ec3scOA1AFWb4IhUH2MgBubFz7KvSoxU8qrRLBP7SzymitWRcBd8DeDnZ8OvTAyNYUd7VZnrw5487JW0w82dBXCwzTesjnDsjJIrsjEsTxM3DI3kOk3XIi7VrYbzv_Jk5Hb4gpFudd-VGVD2DQGEMWjzNmhki5a1d7fnIwjZ1pkkYkhrclYVxiNMDn7Vq7c2nhKqpQxArFQRkmAvj-nRvA23GE2sV0dOTKeeAelqlLv3Nw02ZiQVy3NNWCCM-aI-LWLgnSq08N7Ejj9HZ-e4XbEjun7Jz9L0-6Wq8iGPgpIWJfjHpZmZnyxibXg"
}

Per un primo test è possibile utilizzare un servizio online (ad es. https:///jwt.io/) per verificare il JSON restituito e, se necessario, l'autenticità. In questo esempio il messaggio non è cifrato, quindi è sufficiente inserirlo nella sezione "Encoded" e, opzionalmente, inserire la chiave pubblica nell'apposita sezione per verificare la firma:

sampleJwtIo

Notifica di accredito​

Questa soluzione consente all'FPP di ricevere una notifica non appena il pagamento è stato correttamente accreditato.

La soluzione può essere implementata se e solo se sono verificate le seguenti condizioni:

  • il prodotto è Pass Pay by Bank
  • il conto di accredito è un conto Fabrick (o appartiene a una banca del gateway Fabrick, ad esempio Banca Sella)

In questo caso, anche se l'FPP non ha sottoscritto la parte Pass AIS (accesso ai dati), Fabrick sarà comunque in grado di verificare l'accredito sul conto, ovviamente con la preventiva autorizzazione dell'FPP stesso.

L'FPP riceverà quindi lo stato SETTLED in aggiunta agli altri stati pispStatus.

In caso di incongruenza degli stati — ad esempio, la GET getStatusPayment restituisce RECEIVED oppure EXECUTED_DETBTOR o EXECUTED_CREDITOR ma il parametro isSettled è true — si consiglia di fare affidamento su quest'ultimo, in quanto costituisce una verifica sul conto del beneficiario, mentre lo stato del pagamento è un'informazione restituita dalla banca del debitore. Eventualmente potrebbe essere una buona prassi impostare un allarme ed effettuare una verifica manuale.