S2S Notifcations

Introduction

Fabrick provides the possibility to send notifications server-to-server to the TP/FPP so that it can receive updates, asynchronously, on the events to which it has been registered.

The registration to the events by the TPP/FPP takes place during the setup phase, in which the FPP will communicate to Fabrick the messages and information it wants to receive.

FPP configuration

The TPP/FPP has to expose on its server an endpoint on which to receive notifications.

The endpoint should be unique regardless of the environment (testing or production)

The endpoint can be freely chosen as long as it meets the following conditions:

• Method POST
• Protocol HTTPS
• Port 443

To date, TPP/FPP will have to communicate the endpoint to Fabrick via email.

The TPP/FPP has the possibility of exposing two endpoints: one for the pre-production environment and one for the production one. In this way it will be possible to carry out the testing phase.

IP range

These will be the IP ranges from which S2S notifications will be sent:

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

Messages model

It is not necessary to specify any headers, while in the request body only the jwt parameter will be sent, which will be enhanced with a jwt.

If the message is received correctly, the status code HTTP 200 will be returned. If Fabrick receives an error code, a retry logic will be applied until the message has been delivered correctly.

Here is an example of a request that Fabrick will send to the TPP/FPP:

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

and expected response in case of success

HTTP 200

JWT will always respect the following format:

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

where:

• iat: indicates the date of creation of the token (hence the notification) in UTC. Unix Epoch Time in seconds
• exp: indicates the expiration date of the token in UTC. Unix Epoch Time in seconds
• eventId: indicates the unique identifier of the event. Useful in case of debugging
• eventType: it is astring type and indicates the type of event received. Based on this constant the format of the object eventMetaData will contain different parameters and information
• eventMetaData: object containing information of interest to the TPP/FPP. The object will have different properties according to eventType.

Special case PRE / PRO

There is the possibility that the same notification will be sent in both PRE-production and production environments.

This happens for payments that remain in a pending state during a Fabrick Business Copy phase (i.e. the weekend). At this point, as soon as the pending status changes (i.e in EXECUTED_DEBTOR), the same notification will be sent in both PRE-production and production environments:

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
}

Policies of retry

As indicated above in case the endpoint is not reachable or returns an HTTP error code, the retry policy based on the Exponential Backoff method will be activated with the following parameters:

• Interval (sec): 60 seconds
• Max Retries: 13
• Exponential: 2
• The following table shows the time interval of the different attempts and a sample timestamp:

Run	Seconds	Timestamp sample
0	0.000	14/10/2022, 13:28:54:972 UTC
1	60,000	14/10/2022, 13:29:54:972 UTC
2	180.000	14/10/2022, 13:31:54:972 UTC
3	420.000	14/10/2022, 13:35:54:972 UTC
4	900.000	14/10/2022, 13:43:54:972 UTC
5	1860.000	14/10/2022, 13:59:54:972 UTC
6	3780.000	14/10/2022, 14:31:54:972 UTC
7	7620.000	14/10/2022, 15:35:54:972 UTC
8	15300.000	14/10/2022, 17:43:54:972 UTC
9	30660.000	14/10/2022, 21:59:54:972 UTC
10	61380.000	15/10/2022, 06:31:54:972 UTC
11	122820.000	15/10/2022, 23:35:54:972 UTC
12	245700.000	17/10/2022, 09:43:54:972 UTC

Use case

The S2S notification system is currently only used for the payments products, in particular for two different cases:

• pispStatus notification
• Notify of accreditation (only for Pass Pay by Bank product and Fabrick account)

Notify pispStatus

In this case Fabrick will send a notification to the TPP/FPP at each status change of all payments made. The advantage of the TPP/FPP side is obviously to avoid the continuous polling phase for each payment via the methods GET GetPaymentDetails or POST SearchPayments.

It is recommended to implement this solution and thus avoid polling via API. Especially if you use pay-by-link.

Here is a complete example of received decoded message:

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

where:

• paymentRequestId: indicates the payment reference made with Fabrick Pass
• status: indicates the status of the payment, according to the pispStatus parameter (see Pisp Details document). The states to be sent will be agreed upon during the setup. Generally all final states and possibly the ONGOING and INITIALIZED states are recommended. It is not possible notify the CREATED status.

As you can see from the example above, in this case, there is no sensitive information, for this reason the messages will not be encrypted. On the other hand, they will be signed with a Fabrick key so that the FPP can verify the authenticity of the message received via the public key. The algorithm is RS256

Example

Fabrick will send a message as in the following example

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

For a first test you can use an online service (e.g. https:///jwt.io/ ) to verify the returned json and possibly the authenticity. In this example the message is not encrypted, then just insert it in the section "Encoded" and optionally insert the public key in the appropriate section to verify the signature:

Notify of accreditation

This solution allows the FPP to receive a notification as soon as the payment has been properly credited.

The solution can be implemented if and only if the following conditions are verified:

• the product is Pass Pay by Bank
• the credit account is a Fabrick account (or belongs to a bank of the Fabrick gateway, for example Banca Sella)

In this case, even if the FPP does not subscribe to the part of Pass AIS (access to data), Fabrick will still be able to verify the credit on the account, obviously with the prior permission of the FPP itself.

The FPP will receive so the SETTLED status in addition to the others pispStatus ones.

In the event of inconsistency of states, for example the GET getStatusPayment returns RECEIVED or EXECUTED_DETBTOR or EXECUTED_CREDITOR but the isSettled parameter is true, it is advisable to rely on the latter as it is a check on the creditor account , while the payment status is information returned by the debitor bank. It could be good practice to set an alarm and carry out a manual check.