Payment Details

Questa sezione è dedicata sia al TPP (prodotto Fabrick ActiveEngine) che all'FPP (prodotto Fabrick Pass). Per questo motivo, la creazione del flusso di pagamento è omessa in quanto differente e quindi descritta nel relativo documento; analogamente il percorso delle richieste HTTP, che risulterà generico.

Il flusso e i concetti illustrati sono invece esattamente gli stessi per entrambi i prodotti.

Tipi di pagamento supportati

I tipi di pagamento, definiti come payment-product, sono i seguenti:

• SEPA_CREDIT_TRANSFERS
• INSTANT_SEPA_CREDIT_TRANSFERS
• TARGET_2_PAYMENTS
• CROSS_BORDER_CREDIT_TRANSFERS

Quando la richiesta viene creata, le costanti possono essere utilizzate sia con "-" che con "_" e anche in formato minuscolo (es: sepa-credit-transfers).

SEPA Credit Transfer

È lo strumento per effettuare pagamenti in euro tra clienti titolari di conti correnti presso istituti situati nei paesi SEPA (Single Euro Payments Area). Con il SEPA Credit Transfer è possibile effettuare bonifici in euro all'interno dell'Area SEPA.

SEPA Instant Credit Transfer

L'SCT Inst è una soluzione di bonifico bancario istantaneo (Instant Payments - IP) che consente il trasferimento di fondi tra titolari di conto dell'area SEPA entro 10 secondi operativi. I servizi basati sullo schema SCT Inst sono disponibili 24 ore su 24, 365 giorni l'anno. I bonifici istantanei nazionali o SEPA sono possibili solo quando le banche coinvolte hanno aderito allo stesso schema (o circuito) dei pagamenti istantanei. Com'è noto, tuttavia, l'adesione allo schema è facoltativa poiché le banche devono verificare l'adeguatezza applicativa, infrastrutturale, organizzativa e contrattuale.

Al momento esistono solo due circuiti:

• TIPS

• RT-1 EBA clearing

Ovviamente una banca può aderire anche a entrambi i circuiti.

TARGET 2

Il sistema TARGET 2 (Trans-European Automated Real-Time Gross Settlement Express Transfer System) è un circuito di regolamento interbancario che consente ai partecipanti di effettuare, in tempo reale, trasferimenti di denaro in condizioni di sicurezza, affidabilità ed efficienza. Il sistema utilizza un'unica piattaforma condivisa (SSP) creata e gestita dalla Banca d'Italia, dalla Deutsche Bundesbank e dalla Banque de France a beneficio dei sistemi finanziari europei, che, a livello operativo e legale, fanno riferimento alle rispettive banche centrali, sulla base di standard armonizzati. Oggi TARGET2 è la principale piattaforma europea per il regolamento in tempo reale dei pagamenti di importo elevato.

Cross Border

Il pagamento Cross Border è un termine che si riferisce a transazioni che coinvolgono individui, aziende, banche o istituti di regolamento operanti in almeno due paesi diversi. Include anche il trasferimento disposto tra filiali della stessa banca situate in paesi diversi. Dal 1° gennaio 1999, i bonifici bancari in euro con controparte presso banche UE beneficiano del canale di accesso diretto e immediato al regolamento tramite TARGET.

Non tutte le banche supportano tutti i tipi di prodotto; le informazioni al riguardo sono indicate, per ciascun ASPSP, nell'oggetto supportedPayments descritto in precedenza.

Dettagli pagamento

Dopo aver effettuato un pagamento, è sempre possibile visualizzare l'esito, o lo stato intermedio, tramite l'endpoint GET Payment Details. La richiesta è diversa tra FPP e TPP; per i dettagli consultare il documento specifico. Sia per TPP che per FPP è possibile aggiungere il booleano refresh come query string: se impostato su true, consentirà di recuperare i dati aggiornati in tempo reale richiedendoli direttamente alla banca. In caso contrario, con refresh uguale a false o non presente, i dati verranno recuperati in base alle ultime informazioni ricevute dai sistemi di Fabrick.

Di seguito è riportato un esempio di risposta:

{

    "payment": {
        "paymentId": "12345",
        "bankPaymentId": "12345678-1234-1234-1234-123456781234",
        "createdDatetime": "2022-07-11T09:37:43.793+0000",
        "targetAmount": 35000.27,
        "targetCurrency": "EUR",
        "paymentProduct": "SEPA-CREDIT-TRANSFERS",
        "status": "PENDING",
        "pispStatus": "AUTHENTICATED",
        "bankStatus": "PDNG",
        "scaStatus": "scaMethodSelected",
        "statusHistory": [{
            "retrievedDatetime": "2022-07-11T09:37:43.806+0000",
            "status": "PENDING",
            "bankStatus": "PDNG"
        }],
        "pispStatusHistory": [{
            "retrievedDatetime": "2022-07-11T09:37:46.734+0000",
            "pispStatus": "AUTHENTICATED"
        }, {
            "retrievedDatetime": "2022-07-11T09:37:43.806+0000",
            "pispStatus": "CREATED"
        }],
        "paymentCode": "payment_code",
        "description": "description test - id",
        "scaCompleted": false,
        "authorizationType": "EMBEDDED",
        "hasBeenReceivedByBank": true,
        "psuErrorMessages": [
        {
          "code": "string",
          "description": "string",
          "messageDatetime": "2023-09-04T09:55:37.535Z"
        }
      ],
        "creditor": {
            "account": {
                "accountId": 0,
                "currency": "string",
                "value": "string",
                "valueType": "string"
            }
        },
        "debtor": {
            "account": {
                "accountId": 0,
                "currency": "string",
                "value": "string",
                "valueType": "string"
            },
            "bankId": 0,
            "bankProfileId": 0,
            "userId": 0
        }
    }
}

• paymentId: indica l'ID univoco assegnato al pagamento da Fabrick

• bankPaymentId: indica l'ID univoco assegnato al pagamento dalla banca finale

• paymentCode: parametro opzionale che indica il codice scelto dal TPP/FPP in fase di creazione del pagamento. Lunghezza massima 70 caratteri.

• description: indica la causale del pagamento. Ad oggi la maggior parte delle banche limita la stringa a 140 caratteri come indicato dalla normativa PSD2. È possibile aggiungere l'ID univoco scelto dal TPP/FPP per consentire una successiva riconciliazione; in questo caso si consiglia di inserirlo all'inizio della descrizione per evitare che venga troncato.

• authorizationType: indica il tipo di flusso esposto dalla banca

• createdDatetime: indica la data di creazione della richiesta di pagamento su Fabrick

• targetAmount: indica l'importo del pagamento

• targetCurrency: indica la valuta del pagamento

• paymentProduct: indica il tipo di pagamento: SEPA-CREDIT-TRANSFERS | INSTANT-SEPA-CREDIT-TRANSFERS

• status, bankStatus e pispStatus: v. sezioni seguenti

• scaStatus: indica lo stato SCA.

  • RECEIVED: una risorsa di autorizzazione o di cancellazione-autorizzazione è stata creata con successo.

  • PSU_IDENTIFIED: il PSU relativo alla risorsa di autorizzazione o di cancellazione-autorizzazione è stato identificato.

  • PSU_AUTHENTICATED: il PSU relativo alla risorsa di autorizzazione o di cancellazione-autorizzazione è stato identificato e autenticato, ad esempio tramite password o token di accesso.

  • SCA_METHOD_SELECTED: il PSU/TPP ha selezionato la relativa procedura SCA. Se il metodo SCA è scelto implicitamente poiché ne è disponibile uno solo, questo è il primo stato da riportare al posto di "received".

  • STARTED: la procedura SCA indirizzata è stata avviata.

  • FINALIZED: la procedura SCA si è conclusa con successo.

  • FAILED: la procedura SCA è fallita.

  • EXEMPTED: la SCA è stata esentata per la transazione correlata; la relativa autorizzazione ha avuto esito positivo.

• scaCompleted: indica quando un utente ha completato la fase SCA e terminato il flusso di pagamento.

• statusHistory e pispStatusHistory: è possibile visualizzare tutti gli stati intermedi del pagamento. Gli oggetti vengono aggiornati tramite polling da Fabrick verso la banca, pertanto è possibile che un cambio di stato rapido non venga intercettato.

• hasBeenReceivedByBank: indica che il pagamento è stato effettivamente creato dall'ASPSP del debitore.

• psuErrorMessages: è un parametro valorizzato solo nel caso in cui si verifichi un errore lato banca e quest'ultima fornisca ulteriori dettagli. L'elemento è un vettore per gestire eventuali errori multipli all'interno dello stesso flusso. Ad oggi è sempre composto da zero elementi (la banca non ha fornito dettagli) o al massimo da uno. L'oggetto contiene il codice dell'errore e un'eventuale descrizione. Questo errore è gestito direttamente dal front-end di Fabrick, pertanto può essere utilizzato dall'FPP solo per scopi di logging e/o analisi. Non è necessario gestire la UX lato PSU, anche perché i messaggi potrebbero essere in una lingua diversa e/o non di facile interpretazione.

• creditor: informazioni sul beneficiario.

• debtor: informazioni sul debitore. Se il PSU utilizza il metodo di pagamento con selezione IBAN direttamente dalla pagina di redirect della banca (ovvero senza inserire l'IBAN nella parte TPP), queste informazioni potrebbero non essere restituite; non sarà quindi possibile conoscere l'IBAN di addebito, ad esempio.

  • value: indica il numero di conto.
  • valueType: indica il tipo di conto; può essere IBAN, MASKED_PAN o WALLET (MASKED_PAN è consentito solo per TPP ad oggi). In caso di WALLET il parametro value potrebbe essere un'email (ad esempio Paypal) o un ID (ad esempio Revolut).

Il parametro bankStatus

I diversi stati possibili (bankStatus) variano in base alle fasi del processo di pagamento, ad esempio il controllo del formato, il controllo SCA, la disponibilità dei fondi e così via. Se la richiesta di pagamento è stata invocata correttamente, lo stato mostrerà immediatamente RCVD, ovvero che la richiesta di pagamento è stata inviata e ricevuta dal soggetto incaricato di eseguirla. Cambierà poi stato per indicare le varie fasi. Gli stati finali sono solo 3:

• RJCT: il pagamento non è andato a buon fine;
• ACSC: il pagamento è andato a buon fine;
• ACCC: il pagamento istantaneo è andato a buon fine.

A seconda dell'ASPSP, della data e dell'ora del pagamento e di altre variabili, lo stato finale potrebbe richiedere del tempo. Gli stati intermedi sono:

• ACTC: autenticazione e correttezza sintattica;

• ACWC: l'ASPSP ha informato il PISP di aver apportato modifiche (es. sulla data);

• ACCP: il controllo sul "profilo di rischio finanziario" del PSU è stato verificato con esito positivo;

• ACFC: il controllo sulla disponibilità del PSU è stato verificato con esito positivo.

Il parametro status [deprecato]

Fabrick ha mappato i valori normativi in valori più semplici ed esplicativi per facilitare la creazione dell'interfaccia utente. I nuovi valori vengono restituiti tramite il parametro status, che può assumere una delle seguenti costanti:

• RECEIVED: è stata inviata una richiesta di pagamento alla banca ma non è stata autorizzata;
• PENDING: la banca ha preso in carico il pagamento;
• EXECUTED: il pagamento è andato a buon fine;
• REJECTED: il pagamento non è andato a buon fine;
• CANCELLED: il PSU ha chiuso il flusso di pagamento volontariamente (es tasto "Abbandona" da UI Fabrick) oppure ha annullato il pagamento dalla pagina della propria banca.

Se entro un'ora dalla creazione e/o dall'autenticazione la fase di autorizzazione da parte del PSU non è stata completata, il parametro status verrà forzato a Rejected, in quanto l'utente non avrà più la possibilità di autorizzarlo.

Il parametro pispStatus

Per semplificare la gestione dei pagamenti e avere un maggiore livello di dettaglio, Fabrick ha creato una nuova mappatura degli stati di pagamento che sostituirà la precedente:

• CREATED: il pagamento è stato creato dal PSU
• RECEIVED: il pagamento è stato ricevuto dalla banca del debitore
• AUTHENTICATED: il processo di autenticazione PSU (SCA) del pagamento è stato avviato: il PSU ha effettuato il login con utente e password
• ONGOING: il PSU ha completato il processo SCA ma la requestedexecutiondate non è ancora stata raggiunta. Ad esempio: il pagamento è stato richiesto per una data futura, è necessario attendere la data di esecuzione richiesta per essere elaborato.
• INITIALIZED: il PSU ha completato il processo SCA e la requestedexecutiondate (se presente) è stata raggiunta. Significa che la banca del debitore ha approvato l'inizializzazione del pagamento.
• CANCELLED: il PSU ha chiuso il flusso di pagamento volontariamente (es tasto "Abbandona" da UI Fabrick) oppure ha annullato il pagamento dalla pagina della propria banca.
• EXPIRED: il pagamento è scaduto perché abbandonato dal PSU. È trascorsa più di un'ora dall'avvio della SCA senza che sia mai stata completata (stato RECEIVED o AUTHENTICATED).
• REJECTED: il pagamento è stato rifiutato dalla banca del debitore
• REQUIRED_ACTION: lo stato del flusso di pagamento deve essere verificato e potenzialmente corretto. Il pagamento non diventa definitivo e richiede un'azione aggiuntiva (sono trascorsi più di 5 giorni lavorativi dall'inizializzazione del pagamento).
• EXECUTED_DEBTOR: il pagamento è stato eseguito dalla banca del debitore
• EXECUTED_CREDITOR: il pagamento è stato ricevuto dalla banca del beneficiario. La banca del beneficiario ha confermato l'esecuzione del pagamento. Questo stato è possibile solo in due casi: per i pagamenti istantanei poiché il circuito funziona in handshake (con eccezioni, il fatto che sia eseguito significa che è stato anche ricevuto) e per i pagamenti (anche non istantanei) tra banche del gateway Fabrick, ad esempio da Sella a Sella.

In questo diagramma gli stati in giallo sono considerati finali. Inoltre, come si può vedere dal diagramma, una volta che il pagamento raggiunge uno degli stati al di sotto della linea tratteggiata, non può più essere revocato. Ad esempio, un pagamento con data futura potrebbe essere revocato, nel qual caso lo stato diventerebbe CANCELLED.

Se entro un'ora dalla creazione e/o dall'autenticazione la fase di autorizzazione da parte del PSU non è stata completata, il parametro pispStatus verrà forzato a Expired, in quanto l'utente non avrà più la possibilità di autorizzarlo. Ulteriori dettagli sono riassunti nella tabella seguente.

Questo è da intendersi come il periodo massimo di tempo che può rimanere in quel pispStatus. Ad esempio, dopo 1 ora dalla creazione del pagamento alla banca (RECEIVED), se l'utente non compie alcun passo, il pagamento verrà impostato in EXPIRED. Solo mezz'ora invece se l'utente ha eseguito il processo di autenticazione (ma non l'autorizzazione). Negli altri casi il parametro pispStatus si sposterà al pispStatus successivo secondo il diagramma precedente. Il pispStatus arriva in INITIALIZED immediatamente; come detto, la tabella mostra l'intervallo di tempo massimo, ovvero il caso peggiore.

pispStatus	finale/in corso	TEMPO AL FINALE - SEPA	TEMPO AL FINALE - ISTANTANEO
AUTHENTICATED	IN CORSO	1/2 ora	1/2 ora
RECEIVED	IN CORSO	1 ora	1 ora
EXECUTED_DEBTOR	FINALE
INITIALIZED	IN CORSO	6 giorni (BPM 10 giorni)	1 ora
REJECTED	FINALE
EXPIRED	FINALE
ONGOING	IN CORSO	6 giorni (BPM 10 giorni)	1 ora
EXECUTED_CREDITOR	FINALE
CREATED	IN CORSO	secondi	secondi
CANCELLED	FINALE
REQUIRED_ACTION	IN CORSO	Giorni (richiede azione manuale)	Giorni (richiede azione manuale)

Motivo dello stato

Oltre agli stati indicati in precedenza, Fabrick ha creato una mappatura per aggiungere ulteriori dettagli in caso di errori da parte della banca durante la richiesta di creazione di un pagamento.

Ovviamente, dato il numero di banche gestite, la tabella seguente è da considerarsi come informazione aggiuntiva e pertanto non è garantito che sia sempre presente.

Codice	Messaggio	Descrizione
FBK_RCE	REJECTED_CREATION_ERROR	Il pagamento è stato rifiutato perché la chiamata di creazione ha ricevuto una risposta di errore
FBK_RCE_FUF	REJECTED_CREATION_ERROR_FOR_UNKNOWN_FORMAT	Il pagamento è stato rifiutato perché la chiamata di creazione ha ricevuto una risposta di errore in un formato sconosciuto
FBK_RSF	REJECTED_SCA_FAILED	Il pagamento è stato rifiutato perché il processo SCA è fallito
FBK_EFR	EXPIRED_FROM_RECEIVED	Il pagamento è scaduto perché l'utente non ha avviato il processo SCA
FBK_EFA	EXPIRED_FROM_AUTHENTICATED	Il pagamento è scaduto perché l'utente non ha completato il processo SCA
FBK_RAP	REQUIRED_ACTION_PENDING	Il pagamento richiede un'azione perché non è passato a uno stato finale da giorni
FBK_RAE	REQUIRED_ACTION_ERROR	Il pagamento richiede un'azione perché è presente un errore che necessita attenzione
FBK_RAE_BSF	REQUIRED_ACTION_EXECUTED_BUT_SCA_FAILED	Il pagamento richiede un'azione perché la SCA è fallita ma lo stato è eseguito
FBK_RAE_MDI	REQUIRED_ACTION_EXECUTED_MISSING_DEBTOR_IBAN	Il pagamento richiede un'azione perché lo stato è eseguito ma il valore IBAN del debitore non è stato ottenuto (obbligatorio per i controlli AML)
FBK_RA_SUR	REQUIRED_ACTION_SCASTATUS_UNKNOWN_RECEIVED	Il pagamento richiede un'azione perché lo scaStatus è UNKNOWN da molto tempo con stato RECEIVED
FBK_RA_SUA	REQUIRED_ACTION_SCASTATUS_UNKNOWN_AUTHENTICATED	Il pagamento richiede un'azione perché lo scaStatus è UNKNOWN da molto tempo con stato AUTHENTICATED
FBK_RA_SUI	REQUIRED_ACTION_SCASTATUS_UNKNOWN_INITIALIZED	Il pagamento richiede un'azione perché lo scaStatus è UNKNOWN da molto tempo con stato INITIALIZED
FBK_RA_SUO	REQUIRED_ACTION_SCASTATUS_UNKNOWN_ONGOING	Il pagamento richiede un'azione perché lo scaStatus è UNKNOWN da molto tempo con stato ONGOING
FBK_001	PsuDocumentsInvalid	Uno o più documenti che identificano il PSU non sono validi
FBK_002	PsuTokenInvalid	Il PSU non dispone di alcun supporto token
FBK_003	PsuCredentialsNotValid	Alcune credenziali PSU non sono valide
AC01	IncorrectAccountNumber	Il formato del numero di conto specificato non è corretto
AC02	InvalidDebtorAccountNumber	Numero di conto debitore non valido o mancante
AC03	InvalidCreditorAccountNumber	IBAN errato nell'SCT
AC04	ClosedAccountNumber	Il numero di conto specificato è stato chiuso nei libri contabili della banca del conto
AC06	BlockedAccount	Il conto specificato è bloccato e impedisce la registrazione di transazioni
AC10	InvalidDebtorAccountCurrency	La valuta del conto debitore non è valida o è mancante
AC11	InvalidCreditorAccountCurrency	La valuta del conto beneficiario non è valida o è mancante
AC13	InvalidDebtorAccountType	Il tipo di conto debitore è mancante o non valido
AM01	ZeroAmount	L'importo del messaggio specificato è uguale a zero
AM02	NotAllowedAmount	L'importo specifico della transazione/messaggio è superiore al massimo consentito
AM04	InsufficientFunds	L'importo dei fondi disponibili per coprire l'importo del messaggio specificato è insufficiente
AM06	TooLowAmount	L'importo della transazione specificato è inferiore al minimo concordato
AM07	BlockedAmount	L'importo specificato nel messaggio è stato bloccato dalle autorità di regolamentazione
BE08	BankError	Restituito come risultato di un errore bancario
CN01	AuthorisationCancelled	L'autorizzazione è stata annullata
CUST	RequestedByCustomer	Annullamento richiesto dal debitore
DT01	InvalidDate	Data non valida (es. data di regolamento errata)
DS14	UserDoesNotExist	L'utente è sconosciuto al server
DS28	ReturnForTechnicalReason	Restituzione a seguito di problemi tecnici che hanno determinato una transazione errata
DS0H	NotAllowedAccount	Il firmatario non è autorizzato a firmare per questo conto
FF03	InvalidPaymentTypeInformation	Le informazioni sul tipo di pagamento sono mancanti o non valide. Uso generico se non è possibile specificare il Livello di servizio o il codice Strumento locale
FR01	Fraud	Restituito come risultato di una frode
TK01	TokenInvalid	Il token non è valido
TKXP	TokenExpired	Token scaduto
UCRD	UnknownCreditor	Beneficiario sconosciuto

Ricerca pagamenti

Fabrick offre inoltre la possibilità di ricercare i pagamenti utilizzando qualsiasi tipo di filtro tramite l'endpoint POST Search Payments:

POST /v4.0/initiate/payments/search

Corpo della richiesta per TPP (Active Engine)

{
  "bankPaymentId": "string",
  "bankStatus": [
    "string"
  ],
  "createdDatetime": {
    "from": "2023-10-12T12:53:16.785Z",
    "to": "2023-10-12T12:53:16.786Z"
  },
  "creditor": {
    "account": {
      "bankCode1": "string",
      "bankCode2": "string",
      "bankCode3": "string",
      "branchCode1": "string",
      "branchCode2": "string",
      "branchCode3": "string",
      "countryCode": "string",
      "currency": "string",
      "value": "string",
      "valueType": "string"
    },
    "bicCode": "string",
    "email": "string",
    "name": "string"
  },
  "debtor": {
    "account": {
      "bankCode1": "string",
      "bankCode2": "string",
      "bankCode3": "string",
      "branchCode1": "string",
      "branchCode2": "string",
      "branchCode3": "string",
      "countryCode": "string",
      "currency": "string",
      "value": "string",
      "valueType": "string"
    },
    "accountId": "string",
    "bankId": "string",
    "bankProfileId": "string",
    "email": "string",
    "userCode": "string",
    "userId": "string"
  },
  "description": "string",
  "paymentCode": "string",
  "paymentProduct": "string",
  "paymentService": "string",
  "requestedExecutionDatetime": {
    "from": "2023-10-12T12:53:16.786Z",
    "to": "2023-10-12T12:53:16.786Z"
  },
  "pispStatuses": ["string"],
  "status": [
    "string"
  ],
  "targetAmount": {
    "from": 0,
    "to": 0
  },
  "targetCurrency": "string"
}

Corpo della richiesta per FPP (Pass)

{
  "filter": {
    "createdDateTime": {
      "greaterThanEquals": "2025-10-29T00:00:00.079",
      "lesserThanEquals": "2025-10-30T16:16:12.920"
    },
    "pispStatuses": {
      "in": [
        "REJECTED"
      ]
    },
    "description": { 
            "contains": "ProvaRevolut"
        }
  },
  "pagination": {
    "offset": 0,
    "limit": 300
  },
  "sorting": [
    {
      "fieldName": "createdDatetime",
      "direction": "ASCENDING"
    }
  ]
}

In caso di risposta positiva, si otterrà la lista dei pagamenti con tutte le relative informazioni; in caso contrario, una lista vuota:

{
    "errors": [],
    "payload": {
        "list": [
            {
                "bankPaymentId": "12345",
                "createdDatetime": "2020-03-04T15:43:27.550Z",
                "creditor": {
                    "account": {
                        "accountId": 123,
                        "cardId": 0,
                        "currency": "EUR",
                        "value": "ITXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                        "valueType": "IBAN"
                    },
                    "address": {
                        "city": "Biella",
                        "postalCode": "13900",
                        "street": "Via Italia"
                    },
                    "bicCode": "XXXXXXXXXXX",
                    "mail": "paolo.rossi@mail.it",
                    "name": "Paolo Rossi"
                },
                "debtor": {
                    "account": {
                        "accountId": 0,
                        "cardId": 0,
                        "currency": "EUR",
                        "value": "ITXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                        "valueType": "IBAN"
                    },
                    "bankId": 19,
                    "bankProfileId": 1,
                    "userId": 0
                },
                "description": "Test Payment",
                "executionDatetime": "2020-03-04T15:43:27.550Z",
                "fundsAvailable": true,
                "paymentCode": "123",
                "paymentId": 12345,
                "paymentProduct": "SEPA_CREDIT_TRANSFERS",
                "quotationDatetime": "2020-03-04T15:43:27.550Z",
                "requestedExecutionDatetime": "2020-03-04T15:43:27.550Z",
                "status": "ACCC",
                "targetAmount": 100,
                "targetCurrency": "EUR",
                "transactionCurrency": "EUR"
            }
        ],
        "pagination": {
            "limit": 0,
            "offset": 0,
            "pageCount": 0,
            "resultCount": 1
        }
    },
    "status": "OK"
}

API di utilità

Fabrick espone inoltre servizi di validazione per i singoli dati di pagamento. Nel caso del TPP, ciò è utile per verificare i parametri prima di inizializzare il pagamento, creando un'interfaccia dinamica e precompilata; il vantaggio è prevenire eventuali errori degli utenti offrendo la possibilità di identificare immediatamente il motivo. Nel caso dell'FPP, potrebbe essere utile per creare un'interfaccia personalizzata, poiché tutti i controlli sono già implementati nell'interfaccia di Fabrick.

Validate Debtor

Il servizio POST Validate Debtor restituisce l'ASPSP corretto relativo all'IBAN passato in input come indicato di seguito:

POST /v4.0/initiate/utils/debtor/validate 

{
  "debtorAccount": {
    "currency": "EUR",
    "value": "{{debtorAccount}}",
    "valueType": "IBAN"
  }
}

L'endpoint restituirà la lista degli ASPSP trovati, tra i quali l'utente deciderà quale utilizzare. Solitamente questa lista avrà dimensione pari a uno, come mostrato nell'esempio:

{
    "status": "OK",
    "payload": {
        "banks": [
            {
                "bankId": "17",
                "gateway": "Fabrick",
                "createdDatetime": "2019-07-15T08:55:22.206+0000",
                "deleted": false,
                "businessName": "Banca Sella",
                "labelName": "Banca Sella",
                "address": {
                    "city": "Biella",
                    "country": "Italy",
                    "countryCode": "IT"
                },
                "fiscalCode": "BSE",
                "abiCode": "03268",
                "customerServices": [],
                "media": [],
                "bankCode": "03268",
                "bankConnector": "3",
                "bankPisConnector": "101",
                "uris": {
                    "sandbox": "https://sandbox-psdgw-sella.fabrick.com",
                    "live": "https://psdgw-sella.fabrick.com"
                },
                "aisLevel": 1,
                "pisLevel": 4,
                "scaFlows": [],
                "scaMethods": [],
                "supportedPayments": {
                    "single": {
                        "sepa": {
                          "standard": true,
                          "future": true,
                          "multiCurrency": false
                        },
                        "instant": {
                            "standard": true
                        }
                    }
                },
                "isSupported": false,
                "isOnline": false,
                "lastUpdatedDatetime": "2019-08-19T15:30:27.461+0000",
                "lastOnlineUpdatedDatetime": "2019-07-15T08:55:22.206+0000"
            }
        ]
    }
}

Uno dei parametri più importanti per procedere con i passi successivi è l'oggetto supportedPayments, che indica i dettagli sui tipi di pagamento supportati.

Validate IBAN

Il servizio POST Validate IBAN verifica che l'IBAN passato in input sia corretto e valido. Ad esempio, potrebbe essere utilizzato per mostrare un controllo di validazione accanto ai campi "IBAN Beneficiario" e "IBAN Debitore" e consentire all'utente di correggere immediatamente i dati errati.

POST /v4.0/initiate/utils/iban/validate

{
    "iban": "ITXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Vengono inoltre restituite tutte le informazioni relative all'IBAN stesso:

{
    "status": "OK",
    "payload": {
        "elements": {
            "countryCode": "IT",
            "controlCode": "XX",
            "bankCode1": "XXXXX",
            "branchCode1": "XXXXX",
            "accountNumber": "XXXXXXXXXXXX",
            "check1": "C"
        },
        "isValid": true
    }
}

Validate Sct-Inst

Come già descritto, l'adesione allo schema SEPA Instant Credit Transfer è facoltativa; per questo motivo Fabrick espone un servizio che consente di conoscere in anticipo la possibilità di effettuare il pagamento tra i due ASPSP. Come mostrato di seguito, l'endpoint POST Validate Sct-Inst accetta in input il creditorBankId, il creditorAccountId, le informazioni sul conto del debitore e il debtorBankId. In output restituisce la conferma che entrambe le banche hanno aderito allo stesso schema SCT-Inst. Con questo endpoint, in caso di esito negativo, l'utente può essere notificato durante l'inserimento dei dati che il pagamento non andrà a buon fine.

Caso TPP

POST /api/fabrick/active-engine/v4.0/initiate/utils/sct-inst/validate HTTP/1.1

{
  "creditorIban": "ITXXXXXXXXXXXXXXXXXXXXXXXXX",
  "debtorIban": "ITXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Caso FPP

POST /api/fabrick/pass/v4.0/initiate/utils/sct-inst/validate

{
  "creditorAccountId": {{creditorAccountId}},
  "creditorBankId": "1",
  "debtorAccount": {
    "currency": "EUR",
    "value": "ITXXXXXXXXXXXXXXXXXXXXXXXXX",
    "valueType": "IBAN"
  },
  "debtorBankId": "{{bankId}}"
} 

Di seguito è riportato un esempio di risposta positiva. La risposta è la stessa per TPP e FPP.

{
    "status": "OK",
    "payload": {
        "isValid": true
    }
} 

Validate Payment

Fabrick offre inoltre la possibilità di richiedere una validazione unica e completa del pagamento che sta per essere effettuato. Questo endpoint combina tutti i controlli descritti in un unico servizio, restituendo le informazioni necessarie per identificare esplicitamente eventuali dati errati inseriti dal PSU.

Di seguito è riportato un esempio di POST Validate Payment.

Caso TPP

POST /api/fabrick/active-engine/v4.0/initiate/banks/19/payments/sepa-credit-transfers/validate HTTP/1.1

{
    "debtor": {
        "userCode": "gian",
        "account": {
            "value": "ITXXXXXXXXXXXXXXXXXXXXXXXXX",
            "valueType": "IBAN",
            "currency":"EUR"
        }
    },
    "creditor": {
        "name": "Mario Rossi",
        "account": {
            "value": "ITXXXXXXXXXXXXXXXXXXXXXXXXX",
            "valueType": "IBAN",
            "currency":"EUR"
        }
    },
    "description":"Esempio Validate Payment",
    "targetAmount": "50",
    "targetCurrency":"EUR"
}

Caso FPP

POST /api/fabrick/pass/v4.0/initiate/banks/{bankId}/payments/{paymentProduct}/validate

{
    "debtorAccount": {
        "currency": "EUR",
        "value": "IT50I0503456841900000000003",
        "valueType": "IBAN"
    },
    "creditorAccountId": 1,
    "debtorCode": "0000470002",
    "paymentCode": "SQFAR0000456",
    "description": "RICPISPSQFAR00004560000470002",
    "targetCurrency": "EUR",
    "targetAmount": 50.0
}

Sia per TPP che per FPP, la risposta restituisce l'insieme dei controlli e i relativi risultati; grazie a queste informazioni, al PSU può essere consentito di procedere o di correggere gli errori.

{
    "status": "OK",
    "payload": {
        "creditorIbanElements": {
            "countryCode": "IT",
            "controlCode": "XX",
            "bankCode1": "XXXXX",
            "branchCode1": "XXXXX",
            "accountNumber": "XXXXXXXXXXXX",
            "check1": "A"
        },
        "debtorIbanElements": {
            "countryCode": "XX",
            "controlCode": "XX",
            "bankCode1": "XXXXX",
            "branchCode1": "XXXXX",
            "accountNumber": "XXXXXXXXXXXX",
            "check1": "C"
        },
        "isRequestedExecutionDateAllowed": true,
        "isChargeBearerAllowed": true,
        "isPaymentProductAllowed": true,
        "isInstantAllowed": true,
        "isCreditorIbanValid": true,
        "isDebtorIbanValid": true
    }
}

Get Execution Dates

I bonifici, una volta disposti, devono essere elaborati dalla banca prima di essere fisicamente accreditati. L'operazione consiste in alcuni controlli e disposizioni che l'istituto effettua, come la verifica dell'identità del soggetto che dispone il bonifico o la corrispondenza tra il codice IBAN e i dati del destinatario del bonifico. Ogni istituto di credito ha una scadenza per l'elaborazione delle operazioni e dei bonifici bancari: questo è il cut-off. Se il bonifico viene disposto entro l'orario di cut-off, la transazione viene elaborata anche nella stessa giornata; se il bonifico viene disposto dopo l'orario di cut-off, l'elaborazione del bonifico viene posticipata al giorno successivo. Grazie all'endpoint GET getExecutionDates è possibile individuare il giorno dell'operazione. Questo servizio, dati il creditorAccountId e il debtorAccountValue (debtorIban), restituisce una lista di date disponibili in cui è possibile effettuare un pagamento. È quindi possibile mostrare un calendario in cui solo queste date sono selezionabili, disabilitando tutte le altre. Di seguito è riportato un esempio che mostra come invocare l'endpoint GET Execution Dates.

Caso TPP

GET /api/fabrick/active-engine/v4.0/initiate/utils/execution-dates?creditorIban=ITXXXXXXXXXXXXXXXXXXXXXXXXX&debtorIban=ITXXXXXXXXXXXXXXXXXXXXXXXXX&fromDate=2020-03-30 HTTP/1.1

Caso FPP

GET /api/fabrick/pass/v4.0/initiate/utils/execution-dates? creditorAccountId=XXXXX&debtorIban=ITXXXXXXXXXXXXXXXXXXXXXXXXX&fromDate=2020-11-19

Di seguito è riportato un esempio di risposta. La risposta è la stessa per TPP e FPP.

{
    "status": "OK",
    "payload": {
        "validExecutionDates": [
            "2021-01-13",
            "2021-01-14",
            "2021-01-15",
            "2021-01-18",
            "2021-01-19",
            "2021-01-20",
            "2021-01-21",
            "2021-01-22",
            "2021-01-25",
            "2021-01-26"
        ]
    }
}

A seconda dell'orario di cut-off di ogni banca e della gestione interna dei pagamenti futuri, è possibile che l'array non contenga alcuna data; in questo caso non sarà possibile effettuare il pagamento.

Linee guida

Valutare l'esito di un pagamento

Una volta inizializzato un pagamento, è assolutamente necessario comprendere le varie fasi per poter fare la scelta più coerente con le proprie esigenze in base al comportamento desiderato.

Si presuppone che il pagamento in questione sia stato autorizzato, perché altrimenti, ovviamente, non avrà alcuna evoluzione. Per semplificare il processo al massimo, divideremo il flusso in 3 stati diversi:

• Pagamento autorizzato: questa informazione è disponibile immediatamente dopo l'autorizzazione del pagamento da parte del PSU; il vantaggio è quindi l'immediatezza dell'informazione, ma d'altra parte non vi è certezza dell'accredito in quanto non sono ancora stati effettuati controlli da parte della banca del debitore (controlli sintattici, controllo fondi, ...).
• Pagamento eseguito: in questo caso è necessario attendere che il pagamento passi dallo stato "preso in carico dalla banca" allo stato eseguito; si può così essere certi che tutti i controlli della banca del debitore siano stati completati con successo. Il bonifico viene quindi immesso nel circuito. I tempi sono variabili, ma uguali a quelli di un bonifico "standard": da qualche minuto a qualche giorno considerando gli orari di cut-off e i giorni festivi.
• Pagamento accreditato: questo è l'ultimo stato; a seguito di una riconciliazione si ha la certezza che il pagamento è stato accreditato. Lo svantaggio è quindi l'attesa più lunga rispetto ai primi due casi, che dipende anche dai tempi di contabilizzazione di ogni singola banca.

Sebbene i tre casi possano inizialmente sembrare simili, abbiamo in realtà visto differenze notevoli. Ovviamente cambia anche il livello di rischio: nell'ultimo caso il TPP/FPP avrà il 100% di certezza che il pagamento è stato ricevuto, nel secondo caso una percentuale leggermente inferiore (ovviamente nell'ordine dei decimi) e infine un livello più elevato nel primo caso, sebbene ancora minimo. A seconda delle proprie esigenze (tempi di consegna, tipo di prodotto, ...) il TPP/FPP potrà decidere su quale dei 3 stati fare affidamento per considerare il pagamento.

Ovviamente, nel caso di pagamento istantaneo, le considerazioni sopra citate non sono valide in quanto il tempo di accredito è immediato 24/7.

Stato del pagamento

Una volta avviato il flusso di pagamento, è certamente importante conoscerne l'esito; per questo motivo in questa sezione riportiamo alcune linee guida e consigli che potrebbero essere applicati.

La soluzione consigliata è abilitare le notifiche in modo che Fabrick (v. doc Notification S2S)

La seconda soluzione, da utilizzare preferibilmente solo in caso di reale necessità, è implementare un sistema di polling. In questo caso sarà sufficiente invocare in polling l'API GET getPaymentDetails e leggere il parametro pispStatus. Inoltre, in caso di polling, è importante che entri sempre in azione, evidenziando il fatto che non si fa affidamento sul callback di redirect sul proprio dominio (l'url indicato nella fase di richiesta che consente di reindirizzare il PSU alla propria applicazione una volta completata la fase di autorizzazione del pagamento). Questo aspetto è molto importante poiché il PSU potrebbe chiudere il browser anche prima di essere reindirizzato all'applicazione, pur avendo completato con successo la fase di autorizzazione.

Solo per FPP: v. la sezione Payment Status VS Workflow status nel documento Fabrick Pass - Payment Initiation Inbound.

L'API GET getPaymentDetails, come si può vedere dalla documentazione, consente di richiedere lo stato in tempo reale direttamente dalla banca tramite il parametro refresh; tuttavia, si consiglia di omettere questa opzione per i seguenti motivi:

1. Fabrick ha a sua volta implementato uno scheduler per le banche che gli consente di avere i dati aggiornati con un'ottima approssimazione al tempo reale (v. documento Schedulers).
2. Minore possibilità di errore, poiché Fabrick, per il pagamento specifico richiesto, restituirà sempre l'ultimo valore disponibile, a differenza del caso con refresh in cui la banca potrebbe restituire un errore per qualsiasi motivo.
3. Meno importante, ma ovviamente il tempo di risposta sarà più breve.

Si potrebbe considerare l'utilizzo del parametro refresh in presenza di un pulsante di aggiornamento nell'applicazione. In questo caso, come nella fase di creazione, è necessario inserire l'indirizzo IP del PSU.

Tornando ora alla logica dello scheduler, di seguito sono indicati alcuni suggerimenti sia facendo riferimento alla variabile status (deprecata) che alla variabile pispStatus.

Caso con status (deprecato)

Per verificare l'autorizzazione del pagamento, si deve considerare il parametro scaCompleted: sarà impostato su true in caso di pagamento autorizzato dal PSU, false in caso contrario.

In caso di polling, la fase di polling può essere considerata completata non appena il pagamento raggiunge uno stato finale: status = EXECUTED | REJECTED | CANCELED.

Lo scheduler di Fabrick continua anch'esso a fare polling alla banca secondo il seguente algoritmo finché non trova uno stato finale:

• ogni 30 secondi per i primi 5 minuti
• ogni minuto fino a mezz'ora
• ogni 15 minuti fino all'ora
• ogni 30 minuti fino a 12 ore
• ogni ora fino a 24 ore
• ogni 12 ore fino a 7 giorni
• ogni giorno fino a 30 giorni
• ogni 15 giorni fino a 60 giorni

In ogni caso, se dopo 1 ora dall'autenticazione il pagamento non è ancora stato autorizzato, lo stato verrà impostato su REJECTED; il PSU non avrà più la possibilità di procedere con l'autorizzazione (per Banca Sella dopo 15 minuti).

Nel caso in cui un pagamento rimanga in uno stato non finale per un certo periodo di tempo, ad esempio più di 4/5 giorni lavorativi, sarà sempre possibile aprire un ticket con tutti i dettagli necessari per consentire a Fabrick di segnalarlo alla banca finale e richiedere chiarimenti.

Caso con pispStatus

In questo caso l'FPP/TPP potrà valutare unicamente il parametro pispStatus, avendo già da esso tutte le informazioni necessarie senza dover considerare altri parametri. In caso di polling, la logica è esattamente la stessa del caso con status, ma può terminare non appena il pispStatus assume un valore finale (v. sezione Il parametro pispStatus).

Annullamento di un pagamento

In base alla normativa PSD2, un pagamento tramite canale PSD2 non può essere annullato una volta eseguito. Esistono tuttavia alcune eccezioni, in particolare:

- È possibile annullare un pagamento a data futura fino al momento del giorno di esecuzione. Purtroppo, se un pagamento viene iniziato durante l'orario di cut-off, potrebbe essere considerato, da alcune banche, come un pagamento a data futura poiché verrà preso in carico il primo giorno lavorativo.

- Alcune banche (es. Fineco) consentono l'annullamento del pagamento, entro un limite massimo di ore, se il cliente conferma che si tratta di una possibile frode/truffa (ad esempio tramite un flag). In questo caso, i tempi variano in base alla data di esecuzione e al tipo di pagamento: approssimativamente entro 18 ore per i bonifici SEPA ordinari.