Payment Initiation Inbound

Introduzione

Il prodotto Fabrick Pass Pay by Bank consente agli FPP di incassare pagamenti dai propri clienti. Il vincolo è che il conto di accredito (uno o più di uno) deve essere intestato all’FPP. Nei paragrafi seguenti verranno descritti in dettaglio tutti gli endpoint esposti dalla piattaforma: sia quelli relativi alla parte di pagamento vera e propria sia quelli relativi alla configurazione, come la gestione dei clienti. Il seguente diagramma mostra il flusso completo ad alto livello:

Setup

Per poter utilizzare il servizio PISP, l’FPP deve fornire, oltre ai dati anagrafici, i dati del proprio conto (IBAN). Ogni conto sarà identificato da un CreditorAccountId¸ un ID univoco associato al conto dell’FPP che non può essere modificato; verrà inoltre assegnato un CreditorAccountCode che potrà successivamente essere aggiornato dall’FPP secondo i propri criteri di convenzione di naming. Questi parametri saranno utili per eseguire operazioni all’interno del servizio PISP.

Inoltre, verranno effettuati i seguenti controlli:

• KYC Onboarding

  • Acquisizione dei dati anagrafici (inclusi residenza e domicilio);
  • Verifica su database esterni affidabili;
  • Identificazione da remoto;
  • Questionario AML (autodichiarazione);
  • Profilo di rischio.

• KYC continuativo (frequenza variabile in base al livello di rischio)

  • Conferma di residenza/domicilio;

  • Conferma del questionario AML.

Inoltre, richiediamo le seguenti informazioni per le persone giuridiche:

• Acquisizione dei dati societari (es. denominazione sociale, SAE / ATECO, fatturato, numero di dipendenti)

• Riconoscimento del legale rappresentante/titolari effettivi;

• Verifica su database esterni affidabili (ricerca, report CRIF).

Gli FPP avranno a disposizione gli endpoint di controllo che consentiranno di effettuare interrogazioni sui propri dati (creditore) e sui dati dei propri utenti che utilizzeranno il servizio (debitori).

Inoltre, l’FPP può decidere di impostare il servizio in due modalità:

• Default; il metodo di pagamento avviene via Iban o tramite Account salvato
• Payment without Iban; l’utente può scegliere oltre ai metodi di default anche tramite la selezione della banca (senza inserimento Iban)

Creditor Accounts Management

Questa sezione elencherà e descriverà gli endpoint che consentiranno all’FPP di gestire i propri conti creditore, modificare alcuni parametri e, se necessario, eliminarli..

Search Creditors Accounts

L’endpoint POST SearchCreditorsAccounts consente agli FPP di ottenere l’elenco dei conti disponibili per l’accredito dei fondi. È possibile ottenere sia l’elenco completo (nessuna body request) sia filtrare per alcuni parametri del conto, ad esempio il creditorAccountCode o l’oggetto account:

POST /api/fabrick/pass/v4.0/initiate/conf/white-lists/creditor-accounts/search

{}

Di seguito un esempio di risposta in cui viene mostrata la lista con le informazioni complete dei conti disponibili:

{
    "status": "OK",
    "payload": {
        "list": [
            {
                "creditorAccountId": 1,
                "creditorAccountCode": "UnicreditSnd",
                "bankId": 1,
                "name": "MARIO ROSSI",
                "account": {
                    "value": "IT18L0200811770000019486580",
                    "valueType": "IBAN",
                    "currency": "EUR"
                },
                "createdDatetime": "2021-01-11T17:40:24.693+0000",
                "updatedDatetime": "2021-01-11T17:40:24.693+0000"
            }
        ]
    }
} 

Account Creditor Details

L’endpoint GET getCreditorAccount consente di visualizzare le informazioni relative a un singolo conto dell’FPP; il creditorAccountId da ricercare deve essere inserito nel path della request.

GET /api/fabrick/pass/v4.0/initiate/conf/white-lists/creditor-accounts/{creditorAccountId}

Verranno restituite in output le informazioni relative al singolo creditorAccountId

{
    "status": "OK",
    "payload": {
        "creditorAccountId": 1,
        "creditorAccountCode": "UnicreditSnd",
        "bankId": 1,
        "name": "MARIO ROSSI",
        "account": {
            "value": "IT18L0200811770000019486580",
            "valueType": "IBAN",
            "currency": "EUR"
        },
        "createdDatetime": "2021-01-11T17:40:24.693+0000",
        "updatedDatetime": "2021-01-11T17:40:24.693+0000"
    }
} 

Update Creditor Account

L’endpoint PUT updateCreditorAccount consente agli FPP di modificare, dato un creditorAccountId, il codice associato (creditorAccountCode.) e il nome dell’intestatario Il creditorAccountId deve essere inserito nel path della request:

PUT /api/fabrick/pass/v4.0/initiate/conf/white-lists/creditor-accounts/{creditorAccountId} 

{
  "creditorAccountCode": "NewUnicreditSnd"
  "name": "MARIO VERDI"
} 

L’output mostrerà la modifica appena effettuata con le informazioni del conto.

{
    "status": "OK",
    "payload": {
        "creditorAccountId": 1,
        "creditorAccountCode": "NewUnicreditSnd",
        "bankId": 1,
        "name": "MARIO VERDI",
        "account": {
            "value": "IT18L0200811770000019486580",
            "valueType": "IBAN",
            "currency": "EUR"
        },
        "createdDatetime": "2021-01-11T17:40:24.693+0000",
        "updatedDatetime": "2021-01-11T17:40:24.693+0000"
    }
} 

Delete Creditor Account

L’endpoint DEL deleteCreditorAccount, come già specificato, consente la cancellazione di un conto. Una volta cancellato, non potrà più essere utilizzato per l’accredito dei fondi.

DELETE /api/fabrick/pass/v4.0/initiate/conf/white-lists/creditor-accounts/{creditorAccountId} 

Verranno restituite le informazioni del conto rimosso dai sistemi.

Debtor Management

Gli endpoint illustrati nei paragrafi seguenti saranno utili all’FPP per gestire i propri utenti/clienti (in questo prodotto “debitori”). Tramite l’uso delle API che verranno descritte.

Questa sezione è opzionale in quanto è possibile effettuare una richiesta di pagamento senza creare/gestire una rubrica debitori. Quest’ultimo caso è consigliato per quegli FPP che gestiscono clienti occasionali, quindi non hanno bisogno di riconciliare tutti i pagamenti per ciascun cliente. Ovviamente è consentita anche una modalità mista

Create a Debtor

Tramite l’endpoint POST createDebtor è possibile creare un’anagrafica utente inserendo una serie di informazioni come mostrato nell’esempio:

POST /api/fabrick/pass/v4.0/initiate/debtors

{
  "debtorCode": "piero.verdi",
  "email": "piero.verdi@outlook.it",
  "name": "Piero",
  "surname": "Verdi"
  "debtorType": "NATURAL_PERSON"
}

Verrà restituito il codice univoco associato all’utente debtorId con le informazioni inserite in input.

{
    "status": "OK",
    "payload": {
        "debtorId": 2,
        "debtorCode": "piero.verdi",
        "name": "Piero",
        "surname": "Verdi",
        "email": "piero.verdi@outlook.it"
    }
}

Il debtorId una volta associato a un utente non può essere modificato.

debtorType indica il tipo di persona, fisica o giuridica e può assumere i valori NATURAL_PERSON e LEGAL_PERSON. In questo secondo caso è possibile aggiungere il parametro businessName, una stringa libera da valorizzare con il nome della società:

{
  "debtorCode": "piero.verdi",
  "email": "piero.verdi@outlook.it",
  "businessName": "Verdi spa",
  "debtorType": "LEGAL_PERSON"
}

Il parametro input opzionale mobile è deprecato, il valore inserito verrà ignorato e non salvato

Search Debtors

Con l’endpoint POST searchDebtors è possibile cercare la lista dei propri clienti. È possibile filtrare tramite alcune informazioni come email, nome, cognome o numero di telefono. In caso di body senza parametri, verrà restituita la lista di tutti i clienti.

POST /api/fabrick/pass/v4.0/initiate/debtors/search 

In output si avrà la lista degli utenti con le loro informazioni personali:

{
    "status": "OK",
    "payload": {
        "list": [
            {
                ....
            },
            {
                "debtorId": 2,
                "debtorCode": "piero.verdi",
                "accounts": [
                    {
                        "accountId": 24,
                        "bankId": 19,
                        "bankServiceCode": "aCode",
                        "bankEnvironment": "LIVE",
                        "accountLabel": "conto HYPE ",
                        "account": {
                            "value": "IT53B36772XXXXXXXXXXXXXX362",
                            "valueType": "IBAN",
                            "currency": "EUR"
                        },
                        "createdDatetime": "2021-03-04T11:09:34.070+0000",
                        "updatedDatetime": "2021-03-04T11:09:34.070+0000"
                    }
                ],
                "name": "Piero",
                "surname": "Verdi",
                "email": "piero.verdi@outlook.it",
                "createdDatetime": "2021-03-04T10:08:08.309+0000",
                "updatedDatetime": "2021-03-04T10:08:08.309+0000"
            }
        ]
    }
}

Per ciascun cliente verrà restituita anche la lista dei conti associati. Per i dettagli fare riferimento alla sezione Debtor Accounts Management

Debtor Details

L’endpoint GET getDebtor consente di ricercare informazioni relative a un singolo utente. Saranno disponibili in output le informazioni personali complete relative al debtorId indicato:

GET /api/fabrick/pass/v4.0/initiate/debtors/{debtorId}

Output dati utente

{
    "status": "OK",
    "payload": {
        "debtorId": 2,
        "debtorCode": "piero.verdi",
        "accounts": [
            {
                "accountId": 24,
                "bankId": 19,
                "bankServiceCode": "aCode",
                "bankEnvironment": "LIVE",
                "accountLabel": "conto HYPE",
                "account": {
                    "value": "IT53B36772XXXXXXXXXXXXXX362",
                    "valueType": "IBAN",
                    "currency": "EUR"
                },
                "createdDatetime": "2021-03-04T11:09:34.070+0000",
                "updatedDatetime": "2021-03-04T11:09:34.070+0000"
            }
        ],
        "name": "Piero",
        "surname": "Verdi",
        "email": "piero.verdi@outlook.it",
        "createdDatetime": "2021-03-04T10:08:08.309+0000",
        "updatedDatetime": "2021-03-04T10:08:08.309+0000"
    }
}

Update Debtor Info

L’endpoint PUT updateDebtor consente di aggiornare i parametri dell’anagrafica utente. Per un utente è possibile modificare i seguenti parametri:

• debtorCode
• email
• mobile
• name.
• surname.

Di seguito un esempio

PUT /api/fabrick/pass/v4.0/initiate/debtors/{debtorId} 

{
   "email": "p.rossi@gmail.com"
}

In risposta si avrà l’anagrafica completa con le modifiche effettuate

{
    "status": "OK",
    "payload": {
        "debtorId": 2,
        "debtorCode": "piero.verdi",
        "accounts": [
            {
                "accountId": 24,
                "bankId": 19,
                "bankServiceCode": "aCode",
                "bankEnvironment": "LIVE",
                "accountLabel": "conto HYPE mio",
                "account": {
                    "value": "IT53B36772XXXXXXXXXXXXXX362",
                    "valueType": "IBAN",
                    "currency": "EUR"
                },
                "createdDatetime": "2021-03-04T11:09:34.070+0000",
                "updatedDatetime": "2021-03-04T11:09:34.070+0000"
            }
        ],
        "name": "Piero",
        "surname": "Verdi",
        "email": "p.rossi@gmail.com",
        "createdDatetime": "2021-03-04T10:08:08.309+0000",
        "updatedDatetime": "2021-03-04T11:29:45.946+0000"
    }
}

Delete a Debtor

L’endpoint DEL deleteDebtor consente di eliminare l’anagrafica di un utente:

DELETE /api/fabrick/pass/v4.0/initiate/debtors/{debtorId} 

La risposta restituisce le informazioni dell’utente appena eliminato.

Eliminando il debitore, tutti i link di pagamento relativi al debitore verranno invalidati. Il debitore eliminato potrà concludere uno o più pagamenti solo se questi sono già stati inizializzati (cioè il debitore si trova sulla pagina della banca e quindi la GET getPaymentDetails restituisce l’oggetto payment).

Debtor Accounts Management

Save Debtor Iban

Tramite l’endpoint POST CreateDebtorAccount, l’utente avrà la possibilità di salvare il proprio IBAN per effettuare il pagamento; in futuro non dovrà reinserire l’iban ma, tramite l’applicazione, potrà accedere alla propria rubrica e selezionarlo. Il debtoriId dell’utente deve essere presente nel path dell’endpoint.

POST /api/fabrick/pass/v4.0/initiate/debtors/{debtorId}/accounts

Nel body request devono essere presenti i seguenti elementi:

• account: oggetto che contiene i parametri di riferimento dell’IBAN
  • Currency: la valuta del conto
  • Value: l’IBAN vero e proprio
  • Valuetype: in questo caso sarà sempre valorizzato con IBAN
• accountLabel: breve descrizione del conto
• bankEnviroment: indica l’ambiente del conto, può essere SANDBOX (ambiente di test esposto da ciascun ASPSP) oppure LIVE (un conto reale nell’ambiente di produzione).
• bankId: indica il codice univoco associato alla banca a cui appartiene l’IBAN. Può essere recuperato dalla API SearchBanks o da altre API descritte di seguito.

{
  "account": {
    "currency": "EUR",
    "value": "IT05D36xxxxxxx67",
    "valueType": "IBAN"
  },
  "accountLabel": "conto Hype ",
  "bankEnvironment": "SANDBOX",
  "bankId": 19,
}

Verrà restituito in output l’accountId, un codice univoco utile per effettuare pagamenti se l’utente decide di selezionare un iban precedentemente salvato.

 "status": "OK",
    "payload": {
        "accountId": 23,
        "bankId": 19,
        "bankServiceCode": "aCode",
        "bankEnvironment": "SANDBOX",
        "accountLabel": "conto Hype ",
        "account": {
            "value": "IT05D36772XXXXXXXXXXXXXX567",
            "valueType": "IBAN",
            "currency": "EUR"
        },
        "createdDatetime": "2021-03-04T10:28:25.640+0000",
        "updatedDatetime": "2021-03-04T10:28:25.640+0000"
    }
}

Update Account Label

Tramite l’endpoint PUT UpdateDebtorAccount l’utente avrà la possibilità di aggiornare la descrizione precedentemente attribuita a un conto. La nuova descrizione deve essere inserita come input alla chiamata e, nel path della chiamata, oltre al debtorId, deve essere presente anche l’accountId da modificare.

PUT /api/fabrick/pass/v4.0/initiate/debtors/{debtorId}//accounts/{debtorAccountId}

Request

{
  "accountLabel": "Nuova Descrizione"
}

Il body response conterrà tutte le informazioni del conto con la nuova descrizione.

{
    "status": "OK",
    "payload": {
        "accountId": 23,
        "bankId": 19,
        "bankServiceCode": "aCode",
        "bankEnvironment": "SANDBOX",
        "accountLabel": "Nuova Descrizione",
        "account": {
            "value": "IT05D36772XXXXXXXXXXXXXX567",
            "valueType": "IBAN",
            "currency": "EUR"
        },
        "createdDatetime": "2021-03-04T10:28:25.640+0000",
        "updatedDatetime": "2021-03-04T10:58:38.835+0000"
    }
}

Delete Debtor Account

Tramite l’endpoint DEL deleteDebtorAccount sarà possibile eliminare uno specifico debtorAccountId dal database del debitore. Nel path della chiamata devono essere presenti debtorId e il debtorAccountId

DELETE /api/fabrick/pass/v4.0/initiate/debtors/{debtorId}/accounts/{debtorAccountId}

Search banks

Quando vogliamo creare una UI differente e conoscere in anticipo le informazioni di ciascun ASPSP (banca), possiamo invocare l’endpoint POST Search Banks.

POST /api/fabrick/pass/v4.0/initiate/banks/search

{
  "pisLevels": [1,2,3,4]
}

In questo caso possiamo filtrare per pisLevel. Ancora, per ciascun ASPSP, verrà restituito l’oggetto supportedPayments, vedi documento Banks per i dettagli.

Per ottenere i dettagli relativi a un singolo ASPSP, è possibile usare l’endpoint GET getBank:

GET /api/fabrick/pass/v4.0/initiate/banks/{{bankId}}

Fabrick fornisce inoltre una serie di API per gestire gli istituti di credito da mostrare ai propri clienti nel caso in cui si voglia solo una sotto-lista di tutti quelli supportati (vedi documento White and Black Banks list).

Payment Flow with UI Fabrick Pass

Fabrick fornisce una propria User Interface per poter processare i pagamenti in modo trasparente per gli FPP. In questo caso, l’FPP avrà a disposizione un set di API che potrà chiamare per passare dalle proprie interfacce a quella di Fabrick PASS e procedere con tutti i passaggi utili al pagamento. Di seguito il sequence diagram del flow di pagamento tramite la UI di Fabrick Pass.

Create Payment

Tramite l’endpoint POST CreatePayment l’FPP dovrà trasmettere a Fabrick i dati utili a inizializzare il flow di pagamento e in risposta riceverà un link verso cui l’utente verrà reindirizzato per effettuare il pagamento. L’FPP potrà scegliere diverse opzioni in base alle informazioni in suo possesso o alle preferenze di user experience. Di seguito tutti i casi possibili.

FPP manages a debtors registry

Generic request

POST /api/fabrick/pass/v4.0/initiate/payment-requests

{
    "completionRedirectUrls": {
        "onSuccess": "https://www.succes.it",
        "onFailure": "https://www.fail.com"
        }
    "debtorCode": "piero.verdi",
    "debtorId": "2",
    "creditorAccountId": "1",
    "description": "Bonifico test n. 00004560000123",
    "customDescription": "una descrizione solo per la ui"
    "paymentCode": "SQFAR0000456",
    "targetAmount": "100",
    "targetCurrency": "EUR",
    “paymentProduct”:”sepa-credit-transfers | instant-sepa-credit-transfers”,
    "supportedPaymentProduct": ["sepa-credit-transfers", "instant-sepa-credit-transfers"]
}

Nell’input della chiamata devono essere specificati i seguenti dati:

• debtorId: codice univoco assegnato all’utente debitore
• debtorCode: codice descrittivo assegnato all’utente. Se sia debtorId sia debtorCode sono presenti nella request, il match inserito quando si crea il debitore deve essere esatto. Altrimenti è possibile inserire nel body solo uno tra debtorId e debtorCode
• description: questa descrizione è equivalente alla causale che verrà passata alla banca come descrizione del pagamento.

E' consigliato utilizzare solamente caratteri alfanumerici. Non usare caratteri speciali, compresi caratteri che potrrebbero essere considerati standard come "-", ".", ",". Il motivo è che ogni banca ha le proprie restrizioni e diventerebbe complicato gestire una causale differente per ognuna di loro.

• customDescription: è un’ulteriore descrizione opzionale che apparirà solo sulla UI di Fabrick durante la fase di pagamento. Ad esempio, il parametro description potrebbe contenere un id univoco per consentire la riconciliazione successiva, mentre il parametro customDescription potrebbe contenere solo una descrizione più user-friendly relativa al pagamento che sta per essere effettuato
• targetAmount: l’importo del pagamento (in formato intero o decimale)
• targetCurrency: la valuta del pagamento secondo il modello ISO 4217 Alpha 3, ad esempio EUR
• paymentCode: è una stringa libera e può essere usata dall’FPP ad esempio per un possibile mapping interno (parametro opzionale). Lunghezza max 70 char.
• creditorAccontId: rappresenta l’account ID dell’FPP
• paymentProduct: tipo di pagamento, può essere sepa-credit-transfers o instant-sepa-credit-transfers
• supportedPaymentProduct: questo parametro opzionale consente all’FPP di indicare alla PSU i tipi di pagamento consentiti. Nell’esempio precedente, avendo inserito entrambi i tipi di pagamento, la UI di Fabrick consentirà alla PSU di scegliere se effettuare un pagamento standard o istantaneo. Se la banca non supporta, ad esempio, l’istantaneo allora verrà selezionato direttamente il bonifico ordinario. Ovviamente l’array supportedPaymentProduct deve contenere il tipo indicato da paymentProduct.
• completionRedirectUrls: oggetto che contiene al proprio interno i parametri url dove l’utente deve essere reindirizzato al termine del workflow. L’FPP può inserire un url in caso di successo (onSuccess) e uno in caso di errore della procedura (onFailure). Gli url non possono essere null.

In risposta si ottiene:

{
    "payload": {
        "paymentRequestId": "b2aa355a-1234-5678-4321-11d97c97d6df",
        "status": "WORK_IN_PROGRESS",
        "createdDatetime": "2020-10-01T10:23:45.123+02:00",
        "initiationRedirectUrl": "https://www.fabrickPass.com/jwtToken..."
    }
}

Le seguenti informazioni sono disponibili nel payload

• paymentRequestId: id univoco del workflow inizializzato (da non confondere con il paymentId) rappresenta il codice del workflow di autorizzazione dell’utente verso la UI di Fabrick Pass.
• initiationRedirectUrl: link dove l’utente deve essere identificato per procedere con il pagamento tramite Fabrick Pass
• status: status del workflow (vedi documento Workflow status)

Al momento della creazione lo status mostrato sarà WORK_IN_PROGRES gli altri status, una volta completati, potranno essere visualizzati sull’endpoint GET payment-requests

• Date: oltre al createdDatetime, che apparirà sempre, potrebbero esserci altre due date:
  • createdDatetime, data di creazione del workflow
  • completedDatetime, data di completamento del flow
  • cancelledDatetime, data di interruzione del flow

Durante la fase di pagamento, la PSU inserirà il valore IBAN e la UI potrà anche decidere di salvarlo come preferito per poterlo selezionare per pagamenti successivi,

FPP knows the debtor IBAN

Se la UI dell’FPP prevede l’inserimento dell’IBAN già in una fase precedente, allora sarà possibile passarlo all’interno della request grazie al parametro debtorAccount:

POST /api/fabrick/pass/v4.0/initiate/payment-requests

{
    "completionRedirectUrls": {
        "onSuccess": "https://www.succes.it",
        "onFailure": "https://www.fail.com"
        }
    "debtorCode": "piero.verdi",
    "debtorId": "2",
    "debtorAccount": {
        "currency": "EUR",
        "value": "[iban]",
        "valueType": "IBAN"
    },
    "creditorAccountId": "1",
    "description": "RICPISPSQFAR00004560000470002",
    "paymentCode": "SQFAR0000456",
    "targetAmount": "100",
    "targetCurrency": "EUR",
    “paymentProduct”:”sepa-credit-transfers | instant-sepa-credit-transfers”
}

FPP manages debtors accounts registry

Come terza soluzione sarà possibile inserire direttamente il debtorAccountId così che il flow sulla pagina Fabrick salti tutti i primi step (inserimento IBAN, eventuale selezione del servizio dove richiesto) e consenta alla PSU di confermare solo la parte sulle informazioni. Di seguito un esempio di request:

POST /api/fabrick/pass/v4.0/initiate/payment-requests

{
    "creditorAccountId": 123,
    "debtorId": 321,
    "description": "causale",
    "debtorAccountId": 1,
    "completionRedirectUrls": {
        "onFailure": "https://daas.fabrick.com/daas-home?paymentCallbackRed=ko",
        "onSuccess": "https://daas.fabrick.com/daas-home?paymentCallbackRed=ok"
    },
    "paymentProduct": "sepa-credit-transfers",
    "targetAmount": "1",
    "targetCurrency": "EUR"
}

FPP doesn't manage a debtors registry

Come anticipato, è possibile inizializzare un flow di pagamento senza aver registrato un debitore. In questo caso Fabrick salverà questi dati solo per scopi regolamentari e non saranno disponibili per l’FPP. Tecnicamente sarà obbligatorio inserire il parametro isPaymentLite come mostrato nel seguente esempio. Ci sono due ulteriori scelte lato FPP:

• impostare l’indirizzo email del cliente nel body
  • lasciare che il cliente inserisca la propria email sulla UI di Fabrick

FPP knows the debtor info

{
    "completionRedirectUrls": {
        "onSuccess": "https://www.google.it/",
        "onFailure": "https://it.yahoo.com/?p=us"
    },
    "creditorAccountId": "81",
    "debtorInfo":{
        "name":"Paolo",
        "surname":"Rossi",
        "email":"paolo.rossi@test.com",
        "debtorType":"NATURAL_PERSON"
    },
    "debtorAccount": {
        "currency": "EUR",
        "value": "[iban]",
        "valueType": "IBAN"
    },
    "description": "10000005-284C-4196-9A93",
    "targetAmount": 0.1,
    "isPaymentLite": true,
    "paymentCode": "123456",
    "targetCurrency": "eur",
    "customDescription": "Lorem ipsum dolor",
    "paymentProduct": "sepa-credit-transfers",
    "supportedPaymentProduct": [
        "sepa-credit-transfers",
        "instant-sepa-credit-transfers"
    ]
}

In caso di LEGAL_PERSON l’oggetto debtorInfo sarà

"debtorInfo":{
    "businessName":"Piero SRL",
    "email":"piero.macaluso@fabrick.com",
    "debtorType":"LEGAL_PERSON"
},

FPP doesn't know the debtor info

POST /api/fabrick/pass/v4.0/initiate/payment-requests

{
    "completionRedirectUrls": {
        "onSuccess": "https://www.google.it",
        "onFailure": "https://it.yahoo.com"
    },
    "creditorAccountId": "123",
    "description": "10000005-284C-4196-9A93",
    "targetAmount": 0.1,
    "isPaymentLite": true,
    "paymentCode": "123456",
    "targetCurrency": "eur",
    "customDescription": "Lorem ipsum dolor",
    "paymentProduct": "sepa-credit-transfers",
    "supportedPaymentProduct": [
        "sepa-credit-transfers",
        "instant-sepa-credit-transfers"
    ]
}

Pay By Link

Come mostrato sopra, la API POST CreatePayment restituisce un link: questo link ha una durata di default pari a 3 ore. È possibile estendere la durata del link grazie alla modalità Pay By Link. Sarà sufficiente aggiungere il parametro paymentDurationDays come mostrato nel seguente esempio:

POST /api/fabrick/pass/v4.0/initiate/payment-requests

{
    "creditorAccountId": "81",
    "debtorId": 1841,
    "description": "Utenze",
    "completionRedirectUrls": {
        "onFailure": "https://daas.fabrick.com/daas-home?paymentCallbackRed=ko",
        "onSuccess": "https://daas.fabrick.com/daas-home?paymentCallbackRed=ok"
    },
    "paymentProduct": "sepa-credit-transfers",
    "targetAmount": 1,
    "paymentDurationDays": 30,
    "targetCurrency": "EUR"
}

il paymentDurationDays è un intero e indica la durata del link in giorni e può assumere un valore tra 1 e 30 giorni.

Deepening: link duration

Come già menzionato, il link restituito dalla API POST CreatePayment ha una durata di default e può essere configurabile. Tuttavia è importante sapere che

ciascun workflow può essere associato a una e una sola inizializzazione del pagamento verso l’ASPSP.

L’FPP può verificare che il pagamento sia stato inizializzato semplicemente invocando la API **GET getPaymentDetails ** (vedi sezione Payment Status VS Workflow status).

Dal punto di vista UX, il pagamento viene iniziato non appena l’utente conferma l’autorizzazione; i primi step sulle pagine Fabrick sono infatti solo a scopo di setup (selezione IBAN, eventuale selezione del servizio e tipo pagamento, ...) e quindi vengono eseguiti senza alcuna interazione con la banca.

In ogni caso consigliamo di creare sempre un nuovo link e non riutilizzare mai lo stesso per evitare controlli aggiuntivi e garantire un comportamento migliore lato utente.

Step UI Fabrick Pass

Quando l’utente viene reindirizzato alla UI di Fabrick Pass, verranno eseguiti i seguenti passaggi:

1. Transactional Data Summary: la PSU viene reindirizzata alla pagina web di Fabrick (co-branded FPP) che mostra le informazioni del pagamento. Queste informazioni non possono essere modificate in alcun modo dal cliente. In questa schermata sarà possibile personalizzare una serie di elementi come il titolo, il sotto-titolo ed eventuale descrizione del servizio che l’FPP mette a disposizione dell’utente. Questi elementi devono essere comunicati a Fabrick che procederà alla modifica degli elementi di visualizzazione. Con riferimento alle altre schermate, verrà mostrato solo il titolo scelto dall’FPP.
2. IBAN insertion / selection: la PSU digita il codice IBAN del conto di addebito o, in alternativa, decide di usare un codice IBAN tra quelli utilizzati in precedenza per ricaricare il wallet (opportunamente mascherato).
3. Bank and / or Banking Service Selection: il codice ABI nell’IBAN consente di associare il conto alla banca ma potrebbero esserci alcuni casi in cui l’associazione non è univoca. Al cliente viene quindi chiesto di selezionare la banca e il servizio associato al tipo di conto di riferimento.
4. T & C Service: tramite l’apposita checkbox, la PSU può richiedere il salvataggio del codice IBAN per velocizzare le successive operazioni di top-up. Prima di continuare, la PSU conferma di aver letto e accettato i Termini e Condizioni del servizio e di aver letto l’informativa di Fabrick sul trattamento dei dati personali.
5. SCA: Fabrick reindirizza la PSU al sito dell’istituto di radicamento del conto per effettuare la SCA e autorizzare il pagamento.
6. Operation outcome: la PSU torna infine all’applicazione dell’FPP dove viene mostrato il risultato dell’operazione.

Fabrick PASS consente agli FPP di esporre anche solo un sottoinsieme di banche utilizzando le API di white list e black list descritte nel documento FabrickPassPisp.

United Kingdom case

Nel caso in cui il conto di accredito sia nel Regno Unito di Gran Bretagna e Irlanda del Nord, quindi in sterline (GBP), Fabrick si affida al partner tecnologico Token.io.

Il flow di pagamento e tutti i parametri di input rimangono gli stessi, le uniche differenze da evidenziare sono:

• targetCurrency: sarà GBP e non EUR
• paymentProduct: sarà sempre faster-payment, nessun’altra possibilità.
• description: massimo 18 caratteri e solo alfanumerico (a-z e 0-9, nessun carattere speciale)

{
    "completionRedirectUrls": {
        "onSuccess": "http://fabrick.it",
        "onFailure": "http://google.it"
    },
    "creditorAccountId": "1",
    "debtorId": "1",
    "paymentCode": "testPayCode",
    "description": "test 0000000001",
    "targetAmount": 100,
    "targetCurrency": "GBP",
    "customDescription": "Lorem ipsum",
    "paymentProduct": "faster-payment"
}

Il link restituito in risposta ha la stessa durata, quindi il valore di default o il valore indicato dal parametro paymentDurationDays. La durata lato Token è solo 20 minuti, per questo motivo una volta cliccato il link Fabrick la PSU avrà solo 20 minuti per completare il pagamento.

Ad oggi, per ragioni regolamentari, per utilizzare le banche esposte da Token (banche inglesi) come conti di addebito è necessario avere un conto di accredito in sterline (GBP).

Get Payment Details

Tramite l’endpoint GET getPaymentDetails l’FPP potrà ottenere le informazioni relative al flow di pagamento:

GET /api/fabrick/pass/v4.0/initiate/payment-requests/{paymentRequestId}

Response sample:

{
    "status": "OK",
    "payload": {
        "paymentRequestId": "c29f4289-0291-4c38-ab6c-cf137591ea92",
        "status": "COMPLETED_SUCCESS",
        "createdDatetime": "2024-04-02T16:20:46.790+0000",
        "completedDatetime": "2024-04-02T16:22:03.202+0000",
        "initiationRedirectUrl": "https://fabrick.com/.../payment-request/c29...",
        "stepCode": "PAYMENT_WORKFLOW",
        "payment": {
            "paymentId": "924652",
            "creditorAccountId": 1081,
            "debtorId": 1841,
            "debtorAccount": {
                "value": "IT85U02008XXXXXXXXXXXXXX451",
                "valueType": "MASKED_IBAN",
                "currency": "EUR"
            },
            "paymentRequestCode": "c29f4289-0291-4c38-ab6c-cf137591ea92",
            "bankPaymentId": "PITA978337",
            "createdDatetime": "2024-04-02T16:21:33.777+0000",
            "targetAmount": 0.1,
            "targetCurrency": "EUR",
            "paymentProduct": "SEPA-CREDIT-TRANSFERS",
            "status": "PENDING",
            "pispStatus": "INITIALIZED",
            "bankStatus": "ACCP",
            "scaStatus": "finalised",
            "statusHistory": [
                {
                    "retrievedDatetime": "2024-04-02T16:21:58.488+0000",
                    "status": "PENDING",
                    "bankStatus": "ACCP"
                },
                {
                    "retrievedDatetime": "2024-04-02T16:21:33.824+0000",
                    "status": "RECEIVED",
                    "bankStatus": "RCVD"
                }
            ],
            "pispStatusHistory": [
                {
                    "retrievedDatetime": "2024-04-02T16:21:58.488+0000",
                    "pispStatus": "INITIALIZED"
                },
                {
                    "retrievedDatetime": "2024-04-02T16:21:34.943+0000",
                    "pispStatus": "RECEIVED"
                },
                {
                    "retrievedDatetime": "2024-04-02T16:21:33.824+0000",
                    "pispStatus": "CREATED"
                }
            ],
            "description": "Utenze",
            "scaCompleted": true,
            "authorizationType": "REDIRECT",
            "hasBeenReceivedByBank": true,
            "debtor": {
                "userCode": "Piero Verdi",
                "bankId": 1,
                "account": {
                    "value": "IT85U02008XXXXXXXXXXXXXX451",
                    "valueType": "MASKED_IBAN",
                    "currency": "EUR"
                }
            },
            "creditor": {
                "name": "Paolo Rossi",
                "account": {
                    "value": "IT85U02008XXXXXXXXXXXXXX123",
                    "valueType": "IBAN",
                    "currency": "EUR"
                }
            },
            "psuErrorMessages": [],
            "isSettled": false,
            "isSettlementProcess": true
            "_links": {
                "scaRedirect": {}
            }
        }
    }
}

Tutti i parametri sono descritti nel documento Payment Details. Per quanto riguarda isSettled e isSettlementProcess puoi trovare la descrizione nella sezione successiva Bank reconciliation

Payment Status VS Workflow status

Al termine del workflow di pagamento, nella risposta della GET getPaymentDetails, verranno mostrati informazioni relative allo status del workflow e del pagamento:

{
    "status": "OK",
    "payload": {
        ...
        "status": "WORK_IN_PROGRESS",
        ...
        "payment": {
            ...
            "pispStatus": "AUTHENTICATED",
            ...
        }
    }
}

Il Workflow status (payload.status) riguarda elementi grafici e UX utente (vedi doc Workflow details); il Payment Status (payload.payment.pispStatus) fornisce indicazioni sul pagamento effettivo.

Il Payment status è l’elemento da considerare maggiormente. Se l’oggetto payment è presente suggeriamo di ignorare totalmente lo status del workflow.

Ad esempio un utente potrebbe chiudere il browser per autorizzare il pagamento tramite il proprio smartphone; in questo caso lo status del workflow rimarrà in WORK_IN PROGRESS, ma il pagamento è stato autorizzato con successo.

E se manca l’oggetto payment? In questo caso il pagamento non è mai stato inizializzato e quindi il workflow può essere cancellato (vedi Delete a workflow nel documento Workflow details) oppure si può attendere che scada automaticamente.

Per informazioni dettagliate sugli status di pagamento e il loro significato relativo, è possibile consultare la documentazione FabrickPassPisp.

Deepening

In termini di completezza della documentazione, riportiamo il comportamento atteso. Dopo 1h dalla creazione di un workflow, se questo non ha ancora raggiunto uno stato finale, verrà forzato secondo le seguenti regole:

• verrà impostato su EXPIRED se il pagamento è RECEIVED

• verrà impostato su COMPLETED_SUCCESS se il pagamento è PENDING o EXECUTED

• verrà impostato su COMPLETED_FAILURE se il pagamento è REJECTED o CANCELED

Una volta che il workflow ha uno stato finale non può più cambiare. Ad esempio, se dopo tre ore il pagamento cambia stato passando da RECEIVED a EXECUTED, il workflow rimarrà comunque in EXPIRED.

Cancel a Payment Workflow

Tramite l’endpoint DEL cancelPaymentWorkflow l’FPP potrà cancellare il link relativo al flow di pagamento:

DEL /api/fabrick/pass/v4.0/initiate/payment-requests/{paymentRequestId}

Il link può essere cancellato se e solo se la PSU non ha ancora iniziato il pagamento (cioè la richiesta non è arrivata alla banca e la PSU è ancora sulla dashboard Fabrick). In caso positivo si otterrà la seguente risposta:

{
    "status": "OK"
}

Altrimenti:

{
    "status": "KO",
    "errors": [
        {
            "code": "AAS123",
            "description": "Payment already submitted"
        }
    ]
}

Se la PSU proverà ad aprire lo stesso vecchio link, Fabrick gli mostrerà il seguente messaggio di errore

"We are sorry but the session has expired. It is necessary to request access again through the third company."

Bank reconciliation

Fabrick ha sviluppato un sistema di riconciliazione per consentire all’FPP di verificare l’effettivo accredito del pagamento sul proprio conto bancario.

Come noto, Fabrick non ha controllo sulle banche terze, per questo motivo la soluzione può essere adattata solo se il conto di accredito è un conto “Fabrick”, cioè una banca gestita dal gateway del gruppo come Sella. L’FPP ovviamente non dovrà cambiare il proprio conto corrente attuale, ma eventualmente sarà sufficiente aprire solo un conto tecnico Sella.

In caso di attivazione del servizio, nella risposta dell’endpoint GET Payment Details saranno disponibili due parametri aggiuntivi come mostrato nel seguente esempio:

dove:

• isSettlementProcess: indica che il pagamento verrà incluso nel processo di riconciliazione (la banca di accredito è una banca Fabrick) e quindi l’FPP può aspettarsi i seguenti tre parametri. Questo parametro sarà sempre presente, eventualmente false,
• isSettled: boolean che indica, se valorizzato a true, che il conto in questione è stato accreditato;
• cro: parametro di tipo string valorizzato con il CRO (Codice Riferimento Operazione) del pagamento. Il parametro cro è valorizzato secondo la seguente logica:
  • bonifico NON contabilizzato e verso la stessa banca (Sella su Sella): viene assegnato il CRO
  • bonifico NON contabilizzato e verso un’altra banca: viene assegnato il TRN
  • bonifico contabilizzato (sia stessa banca sia altra banca): viene assegnato il CRO al momento dell’inserimento; quando viene eseguito, rimane il CRO se sulla stessa banca, diventa TRN se verso un’altra banca
• valueDate: indica la data valuta della transazione.

Il parametro pispStatus non verrà valorizzato in EXECUTED_CREDITOR in quanto sarà sempre valorizzato con l’informazione fornita dall’ASPSP.

La riconciliazione avviene valutando la bookingDate, l’amount e la causale (description) del pagamento; per questo motivo, per ottimizzare il processo, l’FPP deve:

• inserire un alias concordato in fase di setup con Fabrick, cioè una stringa sempre costante associata all’FPP stesso
• un id univoco o guid per ciascun pagamento.

Si consiglia di inserire queste due stringhe prima di qualsiasi altra informazione per evitare il troncamento della causale.

Per il corretto funzionamento del servizio di riconciliazione, attualmente è necessario assicurarsi che la causale sia diversa per ogni richiesta di pagamento.

Nel caso in cui un tentativo di pagamento non vada a buon fine, la causale di pagamento deve quindi essere cambiata per il tentativo successivo. Ad esempio, si potrebbe aggiungere il suffisso "_n" al guid con n uguale al numero di tentativo (_1, _2,..).

Utilities APIS

Fabrick espone inoltre servizi di validazione per i singoli dati di pagamento, dando così all’FPP la possibilità di effettuare controlli prima di inizializzare la fase di pagamento vera e propria creando una UI dinamica e pre-compilata. Il vantaggio è prevenire possibili errori degli utenti dando la possibilità di identificare immediatamente la causa. Per i dettagli vedi documento Payment Details.