Passa al contenuto principale

Fabrick Pass - Iniziazione Pagamenti Outbound

Introduzione​

Il prodotto Fabrick Pass AIS & PIS Services for Corporates consente all’FPP di avviare pagamenti verso i propri clienti. Il vincolo è che il conto di addebito (uno o più di uno) deve essere detenuto dall’FPP. Nei paragrafi seguenti verranno descritti nel dettaglio tutti gli endpoint esposti dalla piattaforma: sia quelli relativi alla parte di pagamento vera e propria sia quelli di configurazione, come la gestione dei clienti.

Setup​

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

Inoltre, verranno effettuati i seguenti controlli creditizi:

  • 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, per le persone giuridiche richiediamo le seguenti informazioni:

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

  • Riconoscimento del rappresentante legale/beneficial owners;

  • 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 (debtor) e sui dati dei propri utenti che utilizzeranno il servizio (creditors).

Gestione Conti Debtor​

Questa sezione elencherà e descriverà gli endpoint che consentiranno all’FPP di interrogare i propri dati e modificare alcuni parametri.

Ricerca Conti Debtor​

L’endpoint POST SearchDebtorsAccounts consente agli FPP di ottenere la lista dei conti in whitelist che ha a disposizione per inizializzare pagamenti. È possibile ottenere sia la lista completa (senza body request) sia filtrare per i seguenti parametri del conto:

  • account: un oggetto che descrive il conto debtor, con i seguenti parametri:
    • currency: la valuta del conto
      • value: il valore che identifica il conto
      • valueType: il tipo del valore
  • bankEnvironment: può essere LIVE o SANDBOX
  • bankId: codice univoco assegnato da Fabrick alla banca
  • bankServiceCode: indica il codice del customer service ed è definito dalla banca
  • companyId: codice univoco assegnato da Fabrick alla company
  • debtorAccountCode: è il codice associato al conto, definito durante la fase di setup
  • debtorAccountId: codice univoco assegnato da Fabrick al conto
  • serviceId: codice univoco assegnato da Fabrick al servizio associato alla company

Di seguito un esempio di request:

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

{
    "account": {
        "value": "IT90P0306901000100000633153",
        "valueType": "IBAN",
        "currency": "EUR"
    },
    "debtorAccountCode": "ISP sandbox PROVA 3"
}

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

{
    "status": "OK",
    "payload": {
        "list": [
            {
                "bankId": 2,
                "account": {
                    "value": "IT90P0306901000100000633153",
                    "valueType": "IBAN",
                    "currency": "EUR"
                },
                "companyId": 22,
                "serviceId": 1241,
                "createdDatetime": "2023-03-06T14:26:23.260+0000",
                "updatedDatetime": "2023-03-06T14:35:14.190+0000",
                "debtorAccountId": 1444,
                "debtorAccountCode": "ISP sandbox PROVA 3",
                "bankServiceCode": "ALLPRODUCTS",
                "bankEnvironment": "SANDBOX"
            }
        ]
    }
}

La lista è un oggetto che contiene i seguenti dati:

  • account: un oggetto che descrive il conto debtor, con i seguenti parametri:
    • currency: la valuta del conto
    • value: il valore che identifica il conto
    • valueType: il tipo del valore
  • bankEnvironment: può essere LIVE o SANDBOX
  • bankId: codice univoco assegnato da Fabrick alla banca
  • bankServiceCode: indica il codice del customer service ed è definito dalla banca
  • companyId: codice univoco assegnato da Fabrick alla company
  • createdDatetime: il momento in cui il conto debtor è stato creato
  • debtorAccountCode: è il codice associato al conto, definito durante la fase di setup
  • debtorAccountId: codice univoco assegnato da Fabrick al conto
  • serviceId: codice univoco assegnato da Fabrick al servizio associato alla company
  • updatedDatetime: il momento in cui il conto debtor è stato aggiornato l’ultima volta

Dettagli Conto Debtor​

L’endpoint GET getDebtorAccount consente di visualizzare le informazioni relative a un singolo conto FPP:

GET /api/fabrick/pass/v4.0/initiate/conf/outbound/white-lists/debtor-accounts/{debtorAccountId}

Nel path richiede il parametro debtorAccountId, un codice univoco assegnato da Fabrick al conto.

Aggiornamento Debtor AccountCode​

L’endpoint PUT updateDebtorAccount consente agli FPP di modificare il debtorAccountCode:

PUT /api/fabrick/pass/v4.0/initiate/conf/outbound/white-lists/debtor-accounts/{debtorAccountId}

{
  "debtorAccountCode": "ISP sandbox PROVA"
}

Nel path richiede il parametro debtorAccountId, un codice univoco assegnato da Fabrick al conto.

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

Gestione Conti Debtor - Dettagli AISP​

Con il prodotto Pass AIS & PIS Services for Corporates è possibile aggregare conti di addebito per mantenerne il controllo e ottenere informazioni relative a saldi e movimenti tramite le API descritte in questa sezione. È inoltre possibile aggregare conti al solo scopo di lettura anche se non usati per effettuare pagamenti.

Aggregare un nuovo conto bancario​

È possibile aggiungere un nuovo conto tramite POST aggregateNewAccount

POST /api/fabrick/pass/v4.0/access/outbound/aggregation

{
    "completionRedirectUrls": {
        "onSuccess": "https://www.fabrick.com",
        "onFailure": "https://www.google.it"
    }
}

dove:

completionRedirectUrls è un oggetto che contiene nei parametri URL dove l’utente verrà reindirizzato al termine del workflow:

  • onFailure: URL in caso di errore della procedura
  • onSuccess: URL in caso di successo della procedura

In response verrà restituito l’initiationRedirectUrl a cui il cliente verrà reindirizzato per procedere con l’aggregazione del conto.

{
    "status": "OK",
    "payload": {
        "initiationRedirectUrl": "...s/v4.0/outbound-aggregation/...",
        "status": "WORK_IN_PROGRESS",
        "workflowId": "abcd1234-1234-5678-7654-12345abcdefg",
        "createdDatetime": "2024-02-05T10:25:04.282+0000"
    }
}

La pagina su cui il PSU atterrerà è mostrata di seguito:

pis_out_ais_1

Una volta selezionata la banca, il PSU visualizzerà la seguente schermata

pis_out_ais_2

Ovviamente la scelta tra SANDBOX e LIVE compare solo nell’ambiente di pre-produzione.

Successivamente il PSU dovrà selezionare se è titolare o delegato come mostrato nello screenshot seguente:

pis_out_ais_3

A questo punto il PSU arriverà a una schermata di riepilogo:

pis_out_ais_4

Da questa pagina è possibile effettuare tutte le operazioni relative ai conti aggregati:

Add Bank​

Questa funzione avvierà il flusso per consentire una nuova aggregazione.

Disconnect​

Questa funzionalità rimuoverà il consenso, il che significa che Fabrick non avrà più la possibilità di aggiornare i conti collegati a quel consenso.

Renew​

Questa funzione rinnoverà il consenso.

Delete​

Questa funzione eliminerà definitivamente il conto; sarà quindi necessario procedere con una nuova aggregazione nel caso in cui si voglia ripristinare lo stesso conto. Per Fabrick sarà sempre un nuovo conto, quindi non verrà riconciliato con quello precedentemente eliminato.

Account Management​

Questa funzione consente di selezionare i conti che saranno resi visibili all’FPP tramite le API successive.

pis_out_ais_5

Ottenere la lista conti​

Usando GET getAccounts è possibile recuperare la lista dei conti aggregati

GET /api/fabrick/pass/v4.0/access/outbound/accounts

Per i dettagli sulla response, vedere il documento Accounts details.

Ottenere i saldi​

Usando GET getBalances è possibile recuperare la lista dei conti aggregati

GET /api/fabrick/pass/v4.0/access/outbound/accounts

Per i dettagli sulla response, vedere il documento Balances details.

Ottenere la lista movimenti​

Usando GET getTransactions è possibile recuperare la lista dei conti aggregati

POST /api/fabrick/pass/v4.0/access/outbound/accounts/transactions/search

{
  "fromDate": "2024-02-07T11:10:18.825Z",
  "toDate": "2024-02-07T11:10:18.825Z",
  "fromCreatedDate": "2024-02-07T11:10:18.825Z",
  "toCreatedDate": "2024-02-07T11:10:18.825Z",
  "offset": 0,
  "limit": 0,
  "sortBy": "string",
  "future": true,
  "accountIds": [
    0
  ],
  "type": "string"
}

Per i dettagli sulla response, vedere il documento Transactions details (PFM).

Gestione Creditor​

Gli endpoint che verranno illustrati nei paragrafi seguenti saranno utili all’FPP per gestire i propri creditor. Tramite l’uso delle API che verranno descritte, sarà possibile:

  • Creare un nuovo creditor
  • Ottenere la lista dei creditor
  • Aggiornare le informazioni del creditor
  • Eliminare un creditor
  • Visualizzare le informazioni relative a un singolo conto creditor

Creare Creditor​

Tramite l’endpoint POST createCreditor è possibile creare un nuovo conto creditor come mostrato nell’esempio seguente:

POST /api/fabrick/pass/v4.0/initiate/outbound/creditor-accounts
{
    "account": {
        "currency": "EUR",
        "value": "IT50B0306901000100000002043",
        "valueType": "IBAN"
    },
    "address": {
        "street": "Via Roma",
        "buildingNumber": "1",
        "city": "Milano",
        "postalCode": "20153",
        "countryCode": "IT"
    },
    "bankEnvironment": "SANDBOX",
    "creditorName": "MARIO ROSSI",
    "creditorCode": "INTESA_SANDBOX"
}

È possibile specificare i seguenti dati in input alla chiamata:

  • account: un oggetto che descrive il conto creditor, con i seguenti parametri:
    • currency: la valuta del conto
      • value: il valore che identifica il conto
      • valueType: il tipo del valore
  • address: un oggetto che descrive l’indirizzo del creditor, con i seguenti parametri:
    • buildingNumber
    • city
    • countryCode
    • postalCode
    • street
  • bankEnvironment: può essere LIVE o SANDBOX
  • creditorCode: è il codice associato al conto, può essere scelto dall’FPP
  • creditorName: è il nome del creditor

Verrà restituito il codice univoco associato all’utente creditorAccountId con la data/ora di creazione (createdDatetime), l’ultima data/ora di aggiornamento (updatedDatetime), le informazioni sulla company (companyId e serviceId) e le informazioni inserite in input.

{
    "status": "OK",
    "payload": {
        "creditorAccountId": 67370,
        "creditorName": "MARIO ROSSI",
        "companyId": 22,
        "serviceId": 1241,
        "creditorCode": "INTESA_SANDBOX",
        "address": {
            "street": "Via Roma",
            "buildingNumber": "1",
            "city": "Milano",
            "postalCode": "20153",
            "countryCode": "IT"
        },
        "createdDatetime": "2023-03-07T13:56:28.028+0000",
        "updatedDatetime": "2023-03-07T13:56:28.028+0000",
        "account": {
            "value": "IT50B0306901000100000002043",
            "valueType": "IBAN",
            "currency": "EUR"
        }
    }
}

Ricerca Creditor​

Con l’endpoint POST searchCreditors è possibile cercare la lista dei propri creditor. È possibile filtrare per tutti i parametri del body request. Di seguito un esempio di request:

POST /api/fabrick/pass/v4.0/initiate/outbound/creditor-accounts/search

{
    "creditorCode": "INTESA_SANDBOX1"
}

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

{
    "status": "OK",
    "payload": {
        "list": [
            {
                "creditorAccountId": 67370,
                "creditorName": "MARIO ROSSI",
                "companyId": 22,
                "serviceId": 1241,
                "creditorCode": "INTESA_SANDBOX1",
                "address": {
                    "street": "Via Roma",
                    "buildingNumber": "1",
                    "city": "Milano",
                    "postalCode": "20153",
                    "countryCode": "IT"
                },
                "createdDatetime": "2023-03-07T13:56:28.028+0000",
                "updatedDatetime": "2023-03-07T13:58:26.019+0000",
                "account": {
                    "value": "IT70R0306948420100000000180",
                    "valueType": "IBAN",
                    "currency": "EUR"
                }
            }
        ]
    }
}

Aggiornare le informazioni del Creditor​

L’endpoint PUT updateCreditor consente di aggiornare le informazioni del creditor. Nel path richiede il parametro creditorAccountId, un codice univoco assegnato da Fabrick al conto creditor. Per un utente è possibile modificare tutti i seguenti parametri:

Nel seguente esempio aggiorneremo il creditorCode:

PUT /api/fabrick/pass/v4.0/initiate/outbound/creditor-accounts/{creditorAccountId}

{
    "creditorCode":"INTESA_SANDBOX1"
}

In response si otterranno tutte le informazioni del creditor:

Eliminare Creditor​

L’endpoint DEL deleteCreditor consente di eliminare un creditor:

DELETE /api/fabrick/pass/v4.0/initiate/outbound/creditor-accounts/{creditorAccountId}

Nel path richiede il parametro creditorAccountId, un codice univoco assegnato da Fabrick al conto creditor.

La response restituisce le informazioni dell’utente appena eliminato.

Dettagli Conto Creditor​

L’endpoint GET getCreditorAccount consente di visualizzare le informazioni relative a un singolo conto creditor:

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

Nel path richiede il parametro creditorAccountId, un codice univoco assegnato da Fabrick al conto creditor.

Verranno restituite le informazioni relative al singolo creditorAccountId.

Flusso di pagamento con UI Fabrick Pass​

Fabrick mette a disposizione una propria User Interface per poter effettuare pagamenti in modo trasparente per gli FPP. In questo caso, l’FPP avrà a disposizione un set di API che può chiamare per passare dalle proprie interfacce a quelle di Fabrick PASS e procedere con tutti i passi utili al pagamento.

Creare Payment Workflow​

Tramite l’endpoint POST CreatePaymentWorkflow l’FPP dovrà trasmettere a Fabrick i dati utili per inizializzare il flusso di pagamento e in response riceverà un link a cui l’utente verrà reindirizzato per il pagamento:

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

{
    "completionRedirectUrls": {
        "onSuccess": "https://www.google.com",
        "onFailure": "https://www.google.com"
    },
    "debtorAccountId": 1202,
    "description": "Utenze",
    "targetAmount": 0.1,
    "targetCurrency": "EUR",

    "creditorAccount": {
        "value": "IT50I0503456841900000000013",
        "valueType": "IBAN",
        "currency": "EUR"
    },
    "creditorAddress": {
        "street": "Via Roma",
        "buildingNumber": "1",
        "city": "Milano",
        "postalCode": "20153",
        "countryCode": "IT"
     },
    "creditorName": "Mario Rossi"
}

I seguenti dati possono/devono essere specificati in input alla chiamata:

  • companyId: codice univoco assegnato da Fabrick alla company

  • completionRedirectUrls: oggetto che contiene nei parametri URL dove l’utente deve essere reindirizzato al termine del workflow:

    • onFailure: URL in caso di errore della procedura
    • onSuccess: URL in caso di successo della procedura

  • creditorAccount: un oggetto che descrive il conto creditor, con i seguenti parametri:

    • currency: la valuta del conto
    • value: il valore che identifica il conto
    • valueType: il tipo del valore

  • creditorAccountId: codice univoco assegnato da Fabrick al conto creditor

  • creditorAddress: un oggetto che descrive l’indirizzo del creditor, con i seguenti parametri. Parametro opzionale, ma richiesti city e countryCode da alcune banche nel caso di un IBAN estero:

    • buildingNumber
    • city
    • countryCode
    • postalCode
    • street

  • creditorName: è il nome del creditor

  • debtorAccountId: codice univoco assegnato da Fabrick al conto

  • description: una breve descrizione

  • fppSubscriptionId: codice univoco assegnato da Fabrick alla subscription della company

  • paymentCode: parametro opzionale, può essere usato dall’FPP inserendo un codice per poter riconciliare i pagamenti. Lunghezza massima 70 caratteri

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

  • serviceId: codice univoco assegnato da Fabrick al servizio associato alla company

  • targetAmount: importo del pagamento (in formato intero o decimale)

  • targetCurrency: valuta del pagamento secondo il modello ISO 4217 Alpha 3, ad esempio EUR

    NOTE: se sia creditorAccountId sia creditorAccount sono presenti nella request, la corrispondenza inserita in fase di creazione del debtor deve essere esatta.

Di seguito un esempio di response:

{
    "status": "OK",
    "payload": {
        "paymentRequestId": "c2a0b01d-0624-44d9-a766-82491bcfd6e2",
        "status": "WORK_IN_PROGRESS",
        "createdDatetime": "2023-03-07T15:11:02.769+0000",
        "initiationRedirectUrl": "https://agata-fabrick-fabrick.dmz.tst/web/fabrick/pass/v4.0/payment-request-outbound/c2a..."
    }
}

Le seguenti informazioni sono disponibili nel payload:

  • createdDatetime: il momento in cui il workflow è stato creato
  • 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.
  • status: stato del workflow (vedi documento Workflow status)
  • initiationRedirectUrl: l’URL che reindirizza il PSU alla pagina Fabrick per procedere al pagamento

Al momento della creazione, lo status visualizzato sarà WORK_IN_PROGRESS. Gli altri stati completati potranno essere visualizzati sull’endpoint GET payment-requests.

Step UI Fabrick Pass​

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

  1. Transactional Data Summary: il PSU viene reindirizzato alla pagina web di Fabrick (co-branded FPP) dove vengono mostrate le informazioni di 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 sottotitolo ed eventuali descrizioni del servizio che l’FPP rende disponibili all’utente. Questi elementi devono essere comunicati a Fabrick che procederà alla modifica degli elementi di visualizzazione. In riferimento alle altre schermate, verrà mostrato solo il titolo scelto dall’FPP.
  2. Selezione tipo di pagamento: il PSU seleziona il tipo di pagamento, che può essere sepa-credit-transfers o instant-sepa-credit-transfers
  3. SCA: Fabrick reindirizza il PSU al sito dell’Account Rooting Institute per eseguire la SCA e autorizzare il pagamento.
  4. Esito operazione: il PSU torna infine all’applicazione dell’FPP dove viene mostrato l’esito dell’operazione.

Dettagli pagamento​

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

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

Nel path richiede il parametro paymentRequestId, un codice univoco assegnato da Fabrick al workflow inizializzato. Fare riferimento al documento Pisp Details per maggiori dettagli.

Payment Status VS Workflow status​

Al termine del workflow di pagamento, in response alla GET getPayment, verranno mostrate informazioni riguardo lo stato del workflow e del pagamento:

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

Lo Workflow status (payload.status) riguarda gli elementi grafici e la 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 workflow status.

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

E se l’oggetto payment è assente? In questo caso il pagamento non è mai stato inizializzato e quindi il workflow può essere cancellato o si può attendere che scada automaticamente.

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

Approfondimento​

Per 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 a EXPIRED se il pagamento è RECEIVED

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

  • verrà impostato a 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.

API di utilità​

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