White Label: PIS

Questa sezione descrive il flusso completo per effettuare pagamenti tramite canale PSD2 e grazie al prodotto Active Engine di Fabrick.

Flusso alto livello

In questa sezione viene mostrato il flusso ad alto livello per inizializzare un pagamento

Flusso API

Per ottenere un flusso minimo funzionale è sufficiente invocare nell'ordine le seguenti API:

• POST CreatePayment
• RIcezione notifica S2S con stato del pagamento
• GET GetPaymentDetails

Di seguito il diagramma che mostra l'intero flusso con i parametri essenziali:

Gestione pagamenti

La fase di inizializzazione di pagamento viene gestita completamente sulla pagina di Fabrick, questo permette di rendere traspatente tutta la complessità che si cela dovuta alle differenti varietà di flussi che dipendono dalle scelte dei vari gateway.

La TPP dovrà semplcimeneta avviare un workflow di pagamento senza preoccuparsi della modalità di interazione con la banca o del metodo di SCA adottato. Tutte scelte che dipendono dalla singola banca seguendo gli standard PSD2.

Inizializzazione di un pagamento

Come anticipato la TPP invocherà l'API POST CreatePayment per avviare il workflow di pagamento, di seguito un esempio:

POST {{domain}}/win/v4.0/wl-pisp/initiate/payment-request

{
  "completionRedirectUrls": {
    "onSuccess": "https://www.google.it/",
    "onFailure": "https://it.yahoo.com/?p=us"
  },
  "debtor": {
    "userCode": "User123"
  },
  "creditor": {
    "account": {
      "value": "IT96G0503456841900000000001",
      "valueType": "IBAN",
      "currency": "EUR"
    },
    "name": "Paolo Rossi"
  },
  "description": "Payment for invoice",
  "targetAmount": 10,
  "targetCurrency": "EUR",
  "paymentProduct": "instant_sepa_credit_transfers"
}

Questa richiesta include i campi minimi ed obbligatori, in risposta si otterrà:

{
  "status": "OK",
  "payload": {
    "paymentRequestId": "c739b314-d419-4a58-b9ca-6ac3391b67ca",
    "status": "CREATED_LINK",
    "createdDatetime": "2026-07-07T12:52:26.016+0000",
    "initiationRedirectUrl": "https://fabrick.com/.../c739b...ca?jwtToken=ey..."
  }
}

Il paymentRequestId indica l'id univoco del workfow di pagamento.

Come si può notare la URL indicata da initiationRedirectUrl punta ad una pagina Fabrick, in particolare alla UX di Fabrick che permettere al PSU di procedere con il processo di pagamento. La pagina è personalizzabile dalla TPP, per i dettagli si rimanda alla sezione apposita.

Nell'esempio precedente è stata mostrata la richiesta più semplice possibile, è possibile comunque aggiungere alcuni parametri opzionali per variare leggermente alcuni comportamenti o far fronte a diverse esigenze da parte della TPP.

Di seguito mostriamo un esempio completo:

POST {{domain}}/win/v4.0/wl-pisp/initiate/payment-request

{
  "completionRedirectUrls": {
    "onSuccess": "https://www.google.it/",
    "onFailure": "https://it.yahoo.com/?p=us"
  },
  "debtor": {
    "userId": 0,
    "userCode": "USER123",
    "bankId": 5,
    "account": {
      "value": "IT77O0848283352871412938123",
      "valueType": "IBAN",
      "currency": "EUR"
    }
  },
  "creditor": {
    "account": {
      "value": "IT96G0503456841900000000001",
      "valueType": "IBAN",
      "currency": "EUR"
    },
    "name": "Marco Candiani",
    "address": {
      "street": "Borgo man",
      "city": "Milan",
      "buildingNumber": "10",
      "countryCode": "IT",
      "postalCode": "20125"
    }
  },
  "description": "Payment for invoice",
  "paymentCode": "PAY123",
  "targetAmount": 10,
  "targetCurrency": "EUR",
  "paymentProduct": "sepa_credit_transfers",
  "supportedPaymentProduct": [
    "sepa_credit_transfers",
    "instant_sepa_credit_transfers"
  ]
}

Per i dettagli dei singoli paranetri si rimada alla sezione Payment Details. Nella sezione Payment Details sono descritti più parametri rispetto il prodotto in questione, ovvero WhiteLabel, in quanto quest'ultimo è stato semplificato e alleggerito per un utilizzo più user-friendly ed immediato.

Esito del pagamento

Una volta concluso il processo di pagamento il PSU verrà reindirizzato sulle pagine indicate nell'oggetto completionRedirectUrls.

Indipentemente dalla URL sulla quale il PSU verrà reindirizzato è necessario verificare il pispStatus. Le callback all'interno dell'oggetto completionRedirectUrls (onSuccess e onFailure) fanno riferimento esclusivamente alla UI e non all'esito del pagamento vero e proprio. Sono quindi due indicatori differenti e indipendenti.

A questo punto la TPP riceverà da parte d Fabrick una notifica S2S con l'esito del pagamento o, opzionalmente, tutti gli stati intermedi. Per i dettagli sulle notifiche si rimanda alla sezione dedicata Notifiche S2S .

In ogni momento è sempre possibilie invocare l'API GET getPaymentDetails per reucperare tutti i dettagli del relativo pagamento.

GET {{domain}}/win/v4.0/wl-pisp/initiate/payment-request/{{paymentRequestId}}

{
  "status": "OK",
  "payload": {
    "paymentRequestId": "5d1c6b43-15c0-44fe-8f61-721a35ace216",
    "status": "EXECUTED_CREDITOR",
    "createdDatetime": "2026-07-07T13:09:04.062+0000",
    "completedDatetime": "2026-07-07T13:10:46.943+0000",
    "stepCode": "PISP5",
    "paymentCode": "PAY123",
    "bankPaymentId": "1a72ff2b-8acc-4ece-be7b-a95db1948ed0",
    "creditor": {
      "name": "Paolo Rossi",
      "account": {
        "value": "IT96G0503456841900000000001",
        "valueType": "IBAN",
        "currency": "EUR"
      }
    },
    "debtor": {
      "userId": 0,
      "userCode": "USER123",
      "bankId": 5,
      "account": {
        "value": "IT1234567891011121314151617",
        "valueType": "IBAN",
        "currency": "EUR"
      }
    },
    "bankPaymentCreatedDatetime": "2026-07-07T13:09:01.034+0000",
    "updatedDatetime": "2026-07-07T13:10:46.953+0000",
    "targetAmount": 10,
    "targetCurrency": "EUR",
    "paymentProduct": "sepa-credit-transfers",
    "description": "Payment for invoice",
    "scaCompleted": true
  }
}

Ricerca pagamenti

Per ricercare uno o più pagamenti è possibile utilizzare l'API POST SearchPayments come indicato di seguito:

POST {{domain}}/active-engine/v4.0/initiate/payments/search
{}

Lista banche

Tramite l'API POST SearchBanks è possibile recuperare la lista completa delle banche esposte da Fabrick, comprese quelle ancora in lavorazione per i diversi stati europei.

Come anticipato non è necessario implementarla perchè fa parte dell'aggregazione gestita su pagina Fabrick, ma ovviamente è a disposizione per qualsiasi utilità:

POST {{domain}}/active-engine/v4.0/initiate/banks/search
{}