Skip to main content

Payment Initiation Inbound

Introduction​

The Fabrick Pass Pay by Bank product allows FPP to collect payments from its customers. The constraint is that the credit account (one or more of one) must be held by FPP. In the following paragraphs, all the endpoints exposed by the platform will be described in detail: both relating to the actual payment part and to the configuration, such as customer management. The following diagram shows the complete high-level flow:

pispSequenceDiagram

Setup​

In order to use the PISP service, the FPP must provide, in addition to the census personal data, its own account data (IBAN). Each account will be identified by a CreditorAccountId¸ a unique ID associated with the FPP account that cannot be changed; a CreditorAccountCode will also be assigned which can later be updated by FPP according to its own naming convention criteria. These parameters will be useful for carrying out operations within the PISP service.

In addition, the following credit checks will be carried out:

  • KYC Onboarding

    • Acquisition of personal data (including residence and domicile);
    • Check on reliable external databases;
    • Remote identification;
    • AML questionnaire (self-declaration);
    • Risk profile.

  • KYC continuously (variable frequency on the level of risk)

    • Confirmation of residence/domicile;

    • Confirmation of the AML questionnaire.

In addition, we require the following information for legal entities:

  • Company data acquisition (e.g. company name, SAE / ATECO, turnover, number of employees)

  • Legal representative/beneficial owners recognition;

  • Check on reliable external databases (search, CRIF report).

The FPPs will have the control endpoints that will allow them to carry out queries on their data (creditor) and on the data of their users who will use the service (debtors).

In addition, the FPP may decide to set the service in two ways:

  • Default; the payment method is made via Iban or via saved Account
  • Payment without Iban; the user can choose over the default methods also through the bank selection (without Iban entry)

Creditor Accounts Management​

This section will list and describe the endpoints that will allow the FPP to manage its creditor accounts, modify some parameters and, se necessary, delete them..

Search Creditors Accounts​

The POST SearchCreditorsAccounts endpoint allows FPPs to obtain the list of accounts that it has available for crediting funds. It is possible to obtain both the complete list (no body request) or filter by some account parameters, for example the creditorAccountCode or the account object:

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

{}

Below is an example of answer where the list with the complete information of the available accounts is shown:

{
    "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​

The GET getCreditorAccount endpoint allows you to view information relating to a single FPP account, the creditorAccountId to be searched must be entered in the request path.

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

The information relating to the single creditorAccountId will be output

{
    "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​

The PUT updateCreditorAccount endpoint allows FPPs to modify, given a creditorAccountId, the code associated with it (creditorAccountCode.) and the name of the holder The creditorAccountId has to be entered in the path of the request:

PUT /api/fabrick/pass/v4.0/initiate/conf/white-lists/creditor-accounts/{creditorAccountId} 
{
  "creditorAccountCode": "NewUnicreditSnd"
  "name": "MARIO VERDI"
}

The output will show the change just made with the account information.

{
    "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​

The DEL deleteCreditorAccount endpoint, as already specified, allows the deletion of an account. Once canceled, it can no longer be used for the crediting of funds.

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

The information of the account removed from the systems will be output.

Debtor Management​

The endpoints that will be illustrated in the following paragraphs will be useful for FPP to manage its users/customers (in this product "debtors"). Through the use of the APIs that will be described.

This section is optional as it is possible to make a payment request without creating/managing a debtors directory. The latter case is recommended for that FPP that manages occasional customers, so it does not need to reconcile all payments for each customer. Obviously a mixed mode is also allowed

Create a Debtor​

Through the POST createDebtor endpoint it is possible to create a user's registry by entering a series of information as the example shows:

POST /api/fabrick/pass/v4.0/initiate/debtors
{
  "debtorCode": "piero.verdi",
  "email": "piero.verdi@outlook.it",
  "name": "Piero",
  "surname": "Verdi"
  "debtorType": "NATURAL_PERSON"
}

The unique code associated with the user debtorId with the information entered in the input will be returned.

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

The debtorId once associated with a user cannot be modified.

debtorType indicates the type of person, natural or legal and can take the values NATURAL_PERSON and LEGAL_PERSON. In this second case it is possible to add the parameter businessName, a free string to be valued with the name of the company:

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

The optional input mobile parameter is deprecated, the inserted value will be ignored and not saved

Search Debtors​

With the POST searchDebtors endpoint you can search the list of your customers. It is possible to filter through some information such as email, name, surname or telephone number. In case of body without parameters, the list of all customers will be returned.

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

In output you will have the list of users with their personal information:

{
    "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"
            }
        ]
    }
}

The list of associated accounts will also be returned for each customer. For details refer to the Debtor Accounts Management section

Debtor Details​

The GET getDebtor endpoint allows you to search information relating to a single user. The complete personal information relating to the indicated debtorId will be available as output:

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

User data output

{
    "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​

The PUT updateDebtor endpoint allows you to update the user database parameters. For a user it is possible to modify the following parameters:

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

Below is an example

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

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

In response you will have the complete registry with the changes made

{
    "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​

The DEL deleteDebtor endpoint allows you to delete a user's registry:

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

The response returns the information of the user just deleted.

By deleting the debtor, all payment links relating to the debtor will be invalidated. The deleted debtor will be able to conclude one or more payments only se these have already been initialized (i.e. the debtor finds himself on the bank's page and therefore the GET getPaymentDetails therefore returns the payment object).

Debtor Accounts Management​

Save Debtor Iban​

Through the POST CreateDebtorAccount endpoint, the user will have the opportunity to save their IBAN to make the payment; in the future he will not have to re-enter the iban but, through the application, he will be able to access his own address book and select it. The user's debtoriId must be present in the endpoint path.

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

The following elements must be present in the body request:

  • account: object that contains the reference parameters of the IBAN
    • Currency: the currency of the account
    • Value: the actual IBAN
    • Valuetype: in this case it will always be valued with IBAN
  • accountLabel: short description of the account
  • bankEnviroment: indicates the environment of the account, it can be SANDBOX (test environment exposed by each ASPSP) or with LIVE (a real account in the production environment).
  • bankId: indicates the unique code associated with the bank to which the IBAN belongs. It can be retrieved from the SearchBanks API or from other APIs described below.
{
  "account": {
    "currency": "EUR",
    "value": "IT05D36xxxxxxx67",
    "valueType": "IBAN"
  },
  "accountLabel": "conto Hype ",
  "bankEnvironment": "SANDBOX",
  "bankId": 19,
}

The accountId will be returned as output, a unique code useful for making payments se the user decides to select a previously saved iban.

 "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​

Through the endpoint PUT UpdateDebtorAccount the user will have the possibility to update the description previously attributed to an account. The new description must be entered as input to the call and, in the path of the call, in addition to the debtorId, the accountId to be modified must also be present.

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

Request

{
  "accountLabel": "Nuova Descrizione"
}

The body response will contain all the information about the account with the new description.

{
    "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​

Through the endpoint DEL deleteDebtorAccount it will be possible to delete a specific debtorAccountId from the debtor's database. In the path of the call must be present debtorId and the debtorAccountId

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

Search banks​

When we want to create a different UI and know before the information of each ASPSP (bank), we can invoke the POST Search Banks endpoint.

POST /api/fabrick/pass/v4.0/initiate/banks/search
{
  "pisLevels": [1,2,3,4]
}

In this case we can filter by pisLevel. Again, for each ASPSP, the supportedPayments object will be returned, see Banks document for details.

To get the details related to a single ASPSP, you can use the GET getBank endpoint:

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

Fabrick also provides a series of APIs to manage the credit institutions to be shown to its customers in case you only want a sub-list of all those supported (See White and Black Banks list document).

Payment Flow with UI Fabrick Pass​

Fabrick provides its own User Interface to be able to process payments in a transparent way for FPPs. In this case, the FPP will have at its disposal a set of APIs that it can call to switch from its own interfaces to that of Fabrick PASS and proceed with all the steps useful for payment. Below is the sequence diagram of the payment flow through the Fabrick Pass UI.

pispUiApp

Create Payment​

Through the endpoint POST CreatePayment the FPP will have to transmit to Fabrick the useful data to initialize the payment flow and in response it will receive a link where the user will be redirected for payment. The FPP will be able to choose different options based on the information in its possession or user experience preferences. Below are all the possible cases.

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"]
}

The following data must be specified in the call input:

  • debtorId: unique code assigned to the debtor user

  • debtorCode: descriptive code assigned to the user. If both debtorId and debtorCode are present in the request, the match entered when creating the debtor must be exact. Otherwise only one of debtorId and debtorCode can be inserted in the body

  • *description: this description is equivalent to the payment description that will be sent to the bank.

    It is recommended to use only alphanumeric characters. Do not use special characters, including those that might be considered standard, such as “-”, “.”, and “,”. The reason is that each bank has its own restrictions, and it would be complicated to manage a different payment description for each one.

  • customDescription: it is a further optional description that will appear only on the Fabrick UI during the payment phase. For example, the description parameter could contain a unique id to allow subsequent reconciliation, while the customDescription parameter could only contain a more user-friendly description relating to the payment that is about to be made

  • targetAmount: the amount of the payment (in whole or decimal format)

  • targetCurrency: the currency of the payment according to the ISO 4217 Alpha 3 model, for example EUR

  • paymentCode: it is a free string and can be used by FPP for example for a possible internal mapping (optional parameter). Max length 70 char.

  • creditorAccontId: represents the account ID of the FPP

  • paymentProduct: type of payment, it can be sepa-credit-transfers or instant-sepa-credit-transfers

  • supportedPaymentProduct: this optional parameter allows the FPP to indicate to the PSU the types of payment allowed. In the previous example, having entered both payment types, the Fabrick UI will allow the PSU to choose whether to make a standard or instant payment. If the bank does not support, for example, the instant then the ordinary bank transfer will be selected directly. Obviously the supportedPaymentProduct array must contain the type indicated by paymentProduct.

  • completionRedirectUrls: object that contains within the url parameters where the user must be redirected at the end of the workflow. The FPP can enter a url in case of success (onSuccess) and one in case of error of the procedure (onFailure) . The urls can't be null.

Response:

{
    "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..."
    }
}

The following information is available in the payload

  • paymentRequestId: unique id of the initialized workflow (not to be confused with the paymentId) represents the code of the user's authorization workflow towards the Fabrick Pass UI.
  • initiationRedirectUrl: link where the user must be identified in order to proceed with the payment via Fabrick Pass
  • status: status of the workflow (see Workflow status document)

At the time of the creation the displayed status will be WORK_IN_PROGRES the other statuses having been completed can be displayed on the endpoint GET payment-requests

  • Date: in addition to the createdDatetime, which will always appear, there may be two other dates:
    • createdDatetime, workflow creation date
    • completedDatetime, flow completion date
    • cancelledDatetime, flow stop date

During the payment phase, the PSU will enter the IBAN value and UI will also be able to decide to save it as a favorite in order to select it for subsequent payments,

FPP knows the debtor IBAN​

If the UI of the FPP foresees the insertion of the IBAN already in a previous phase, then it will be possible to pass it inside the request thanks to the debtorAccount parameter:

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​

As a third solution it will be possible to directly enter the debtorAccountId so that the flow on the Fabrick page skips all the first steps (IBAN entry, bank service selection where required) and allow the PSU to confirm only the part on the information. Below is an example of a 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​

As anticipated, it is possible to initialize a payment flow without having registered a debtor. In this case Fabrick will save these data only for regulatory purposes and they won't be available for the FPP. Technically will be mandatory to insert the isPaymentLite parameter as showed in the following sample. There are two further choices on the FPP side:

  • set the customer's email address in the body
    • let the customer enter their email on the Fabrick UI
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 case of LEGAL_PERSON the object debtorInfo will be

"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"
    ]
}

As shown above the POST CreatePayment API returns a link: this link has a default duration of 3 hours. it is possible to extend the duration of the link thanks to the Pay By Link mode. It will be sufficient to add the parameter paymentDurationDays as shown in the following example:

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"
}

the paymentDurationDays is an integer and indicates the link duration in days and it can assume a value between 1 and 30 days.

As previously mentioned, the link returned by the POST CreatePayment API has a default duration and can be configurable. However it is important to know that

each workflow can be associated with one and only one payment initialization to the ASPSP.

The FPP can verify that the payment has been initialized simply invoking the **GET getPaymentDetails ** API (see Payment Status VS Workflow status section).

From a UX point of view, the payment is initiated as soon as the user confirms the authorization; the first steps on the Fabrick pages are in fact only for setup purpose (IBAN selection, eventually service selection and payment type, ...) and are therefore performed without any interaction with the bank.

In any case we recommend to create always a new link and never reuse the same one in order to avoid additional checks and ensure a better behavior on the user side.

Step UI Fabrick Pass​

When the user is redirected to the Fabrick Pass UI, the following steps will be performed:

  1. Transactional Data Summary: the PSU is redirected to the Fabrick web page (co-brended FPP) where it displays the payment information. This information cannot be changed in any way by the customer. On this screen it will be possible to customize a series of elements such as the title, the sub-title and any description of the service that FPP makes available to the user. These elements must be communicated to Fabrick who will proceed with the change of the display elements. With reference to the other screens, only the title chosen by the FPP will be shown.
  2. IBAN insertion / selection: the PSU types the IBAN code of the debit account or, alternatively, decides to use an IBAN code among those previously used to top up the wallet (appropriately masked).
  3. Bank and / or Banking Service Selection: the ABI code in the IBAN allows you to associate the account with the bank but there may be some cases in which the association is not unique. The customer is then asked to select the bank and the service associated with the type of reference account.
  4. T & C Service: using the appropriate checkbox, the PSU can request the saving of the IBAN code to speed up subsequent top-up operations. Before continuing, the PSU confirms that it has read and accepted the Terms and Conditions of the service and that it has read Fabrick's information on the processing of personal data.
  5. SCA: Fabrick redirects the PSU to the website of the Account Rooting Institute to perform the SCA and authorize the payment.
  6. Operation outcome: the PSU finally returns to the FPP application where it displays the operation's result.

Fabrick PASS allows FPPs to expose even only a subset of banks using the white list and black list APIs described in the FabrickPassPisp document.

United Kingdom case​

In the event that the credit account is in the United Kingdom of Great Britain and Northern Ireland, therefore in sterling (GBP), Fabrick relies on the technological partner Token.io.

The payment flow and all input parameters remain the same, the only differences to highlight are:

  • targetCurrency: it will be GBP and not EUR - paymentProduct: it will be always faster-payment, no other possibilities. - description: maximum 18 characters and alphanumeric only (a-z and 0-9, no special characters)
{
    "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"
}

The link returned in response has the same duration, therefore the default value or the value indicated by the paymentDurationDays parameter. The duration on the Token side is only 20 minutes, for this reason once the Fabrick link is clicked the PSU will only have 20 minutes to complete the payment.

To date, for regulatory reasons, to use the banks exposed by Token (English banks) as debit accounts it is necessary to have a credit account in sterling (GBP).

Get Payment Details​

Through the endpoint GET getPaymentDetails the FPP will be able to get the information relating to the payment flow:

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": {}
            }
        }
    }
}

All parameters are described in the Payment Details document. As regards isSettled and isSettlementProcess you can find the description in the next section Bank reconciliation

Payment Status VS Workflow status​

At the end of the payment workflow in response to the GET getPaymentDetails, information regarding the status of the workflow and payment will be displayed:

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

The Workflow status (payload.status) concerns graphic elements and user UX (see Workflow details doc); the Payment Status (payload.payment.pispStatus) gives indications on the actual payment.

Payment status is the element to be considered the most. If the payment object is present we suggest to ignore totally the workflow status.

For example a user could close the browser to authorize the payment through his own smartphone, in this case the workflow status will remain in WORK_IN PROGRESS, but the payment was successfully authorized.

What se the payment object is missing? In this case the payment was never initialized and then the workflow can be canceled (see Delete a workflow in Workflow details document) or waiting for it to expire automatically.

For detailed information about the payment statuses and their relative meaning, it is possible to consult the FabrickPassPisp documentation.

Deepening​

In terms of completeness of the documentation, we report the expected behavior. After 1h from the creation of a workflow, se this has not yet reached a final state, it will be forced according to the following rules:

  • will be set to EXPIRED se the payment is RECEIVED

  • will be set to COMPLETED_SUCCESS se the payment is PENDING or EXECUTED

  • will be set to COMPLETED_FAILURE se the payment is REJECTED or CANCELED

Once the workflow has a final state it cannot change anymore. For example, se after three hours the payment changes status passing from RECEIVED to EXECUTED, the workflow will still remain in EXPIRED.

Cancel a Payment Workflow​

Through the endpoint DEL cancelPaymentWorkflow the FPP will be able to cancel the link relating to the payment flow:

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

The link can be canceled se and only se the PSU hasn't started the payment yet (i.e. the request hasn't arrived at the bank and the PSU is still on the Fabrick dashboard). In positive case so, you will get the following response:

{
    "status": "OK"
}

Otherwise:

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

If the PSU will try to open the same old link Fabrick will show him the following error message

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

Bank reconciliation​

Fabrick has developed a reconciliation system to allow FPP to verify the effective crediting of the payment to its bank account.

As known, Fabrick has no control over third-party banks, for this reason the solution can only be adapted se the credit account is a "Fabrick" account, i.e. a bank managed by the group's gateway such as Sella. The FPP will obviously not have to change its current account, but it will eventually be sufficient to open only a technical Sella account.

In case of activation of the service in response to the GET Payment Details endpoint, two additional parameters will be available as shown in the following example:

where:

  • isSettlementProcess: indicates that the payment will be included in the reconciliation process (the crediting bank is a Fabrick bank) and therefore the FPP can expect the following three parameters. This parameter will be always present, eventually false, - isSettled: boolean which indicates, se set to true, that the account in question has been credited;
  • cro: string type parameter valued with the CRO (Operation Reference Code) of the payment. The cro parameter is valued according to the following logic: - bank transfer NOT booked and to the same bank (Sella su Sella): the CRO is assigned - bank transfer NOT booked and to another bank: the TRN is assigned
    • booked bank transfer (both same bank and another bank): the CRO is assigned at the time of insertion; when it is executed, it remains the CRO se on the same bank, it becomes TRN se on another bank - valueDate: indicates the transaction value date.

The pispStatus parameter will not be valued in EXECUTED_CREDITOR as it will always be valued with the information provided by the ASPSP.

The reconciliation takes place by evaluating the bookingDate, the amount and the reason (description) for the payment, for this reason, to optimize the process, the FPP have to:

  • insert an alias agreed in the setup phase with Fabrick, i.e. a string that is always constant associated with the FPP itself
  • a unique id or guid for each payment.

It is advisable to enter these two string before any other piece of information in order to avoid truncating of the reason.

For the correct functioning of the reconciliation service, it is currently necessary to ensure that the reason is different for each payment request.

In the event that a payment attempt is unsuccessful, the reason for payment must therefore be changed for the next attempt. For example, you could add the ending "_n" to the guid with n equal to the attempt number (_1, _2,..).

Utilities APIS​

Fabrick also exhibits validation services for individual payment data, thus giving the FPP the possibility to carry out checks before initializing the actual payment phase creating a dynamic and pre-filled UI. The advantage is to prevent possible errors by users giving the possibility of immediately identifying the reason. For details see Payment Details document.