Banking as a Service

Integrating with Fabrick's BaaS APIs enables you to:

Automate financial operations;
Reconcile transactions;
Reduce manual work;
Build sophisticated financial workflows;
Provide a seamless payment experience for your customers.

This guide is designed to help you rapidly integrate Fabrick’s Banking as a Service (BaaS) solution into your backend systems. This guide provides the technical foundation you need to get up and running in your sandbox and production environments, to build a robust, maintainable integration that scales with your business.

Banking as a Service API Integration Guide

This integration guide covers:

Authentication and setup - How to configure your API credentials securely;
Account management - Retrieving and managing your Fabrick cash accounts;
Creating wire transfers - Step-by-step instructions for initiating money transfers;
Monitoring transfer status - Real-time tracking of your transactions;
Banking availability rules - Understanding execution dates and business day logic;
Error handling - Common issues and how to resolve them.

Integrating Banking as a Service API

Prerequisites

Ensure you have:

A Fabrick subscription;
A Sella cash account linked to your Fabrick subscription;
API credentials.

Integration Flow

Integration Steps

Step 1: Retrieve Your Accounts

Note: Ensure you are using the correct environment and API credentials.

sandbox.fabrick.com (SANDBOX)

api.fabrick.com (LIVE)

Before you can send payments or monitor transactions, you need to retrieve your cash accounts and their unique identifiers.

To retrieve your cash accounts, use the GET Accounts endpoint:

https://api.fabrick.com/api/gbs/banking/v4.0/accounts

Request Example

curl --location 'https://api.fabrick.com/api/gbs/banking/v4.0/accounts' \
 --header 'Content-Type: application/json' \
 --header 'Api-Key: {{YOUR_API_KEY}}' \
 --header 'Auth-Schema: S2S'

Response Example

{
  "status": "OK",
  "errors": [],
  "payload": {
    "list": [
      {
        "accountId": "30493889",
        "iban": "IT80R0326822300052819105040",
        "abiCode": "03268",
        "cabCode": "22300",
        "accountNumber": "0052819105040",
        "accountName": "Company Operating Account",
        "activationDate": "2024-01-15",
        "currency": "EUR"
      }
    ]
  }
}

Field	Description	Usage
`accountId`	Unique Sella account identifier for the cash account	Required in all transaction requests
`iban`	Full IBAN number (SEPA format)	For SEPA transfers and reconciliation
`abiCode`	Italian Banking Association code	Reference information
`cabCode`	Branch code	Reference information
`currency`	Account denomination (EUR)	Validation and conversion for currency
`activationDate`	When the account became active	Account lifecycle tracking

To Retrieve Specific Account Details

Use the GET Accounts endpoint and include the accountId in the URL:

curl --location 'https://api.fabrick.com/api/gbs/banking/v4.0/accounts/{{accountId}}' \
 --header 'Content-Type: application/json' \
 --header 'apikey: {{YOUR_API_KEY}}' \
 --header 'Auth-Schema: S2S'

Using the Cash Account Management API package you can also:

GET Account Balance: Retrieves the balance of a specific cash account;
GET Account Transactions: Retrieves the transactions of a specific cash account;
GET Account Reserved Entries: Retrieves the reserved entry list of an account.

Step 2: Creating Wire Transfers: The Core Operation

Money transfer creation is the fundamental operation for automated payments. Both standard SEPA Credit Transfer (SCT) and SEPA Instant Credit Transfer (SCT Inst) transfers are supported.

Prerequisites

Before initiating a transfer, ensure:

Account Verification: You have a valid accountId from the Get Accounts call.
Creditor Information: Complete details of the payment recipient.
You have defined your Verification of Payee (VoP) strategy.

The Verification of Payee (VoP) process applies to SEPA Credit Transfers and ensures that the IBAN provided for a transfer matches the intended beneficiary’s name. To enable verification for each payment, set the X-VoP-Force-Verification header to true.

Create a Wire Transfer

Use the POST Create Money Transfer endpoint:

https://api.fabrick.com/api/gbs/banking/v4.1/accounts/{{accountId}}/payments/money-transfers

Request Headers (Required)

X-Time-Zone: Always set to Europe/Rome;
Auth-Schema: Always S2S for server-to-server authentication;
Api-Key: Your assigned Fabrick API key;
accountId: The source account.

curl --location 'https://api.fabrick.com/api/gbs/banking/v4.1/accounts/{{accountId}}/payments/money-transfers' \
 --header 'apikey: {{YOUR_API_KEY}}' \
 --header 'Auth-Schema: S2S' \
 --header 'Content-Type: application/json' \
 --header 'X-Time-Zone: Europe/Rome' \
 --data '{
  "creditor": {
    "name": "John Doe",
    "account": { "accountCode": "IT59B0300203280461484318754" }
  },
  "executionDate": "2025-05-28",
  "description": "Refund from ACME SPA",
  "amount": 55.50,
  "currency": "EUR",
  "isUrgent": false,
  "isInstant": false,
  "feeType": "SHA"
}'

Field Descriptions

Field	Type	Description
`creditor.name`	String	Recipient's full name. Must be accurate for VoP compliance.
`creditor.account.accountCode`	String	IBAN for SEPA transfers or SWIFT for non-SEPA transfers.
`executionDate`	Date (YYYY-MM-DD)	Date when the transfer is executed; must follow banking availability rules.
`description`	String	Transfer reason / causale. Maximum 140 characters.
`amount`	Number	Transfer amount. Maximum 2 decimals.
`currency`	String	Money transfer currency (EUR).
`isInstant`	Boolean	Default `false`; set to `true` for instant transfers.

For an IBAN used outside Italy, additional creditor address fields are required: creditor.address.address, creditor.address.city, creditor.address.countryCode.

Step 3: Response Example (Success)

{
  "status": "OK",
  "errors": [],
  "payload": {
    "moneyTransferId": "628947306",
    "cro": "4393165470703268",
    "trn": null,
    "status": "BOOKED",
    "direction": "OUTGOING",
    "description": "Refund from ACME SPA",
    "createdDatetime": "2025-10-27T17:37:59.225+0200",
    "debtorValueDate": "2025-10-28",
    "creditorValueDate": "2025-10-29",
    "amount": {
      "debtorAmount": 100.50,
      "debtorCurrency": "EUR",
      "creditorAmount": 100.50,
      "creditorCurrency": "EUR",
      "currencyRatio": 1
    },
    "isUrgent": false,
    "isInstant": false,
    "feeType": "SHA",
    "fees": []
  }
}

Key Response Fields

Field	Meaning
`moneyTransferId`	Unique identifier for this transfer. Use this for status tracking.
`CRO`	Italian banking reference number, used for SCT within the same bank.
`TRN`	Transaction Reference Number, ISO 20022 identifier used in SEPA messages.
`status`	Current transfer state: `WORK_IN_PROGRESS`, `BOOKED`, `EXECUTED`, `REJECTED`.
`debtorValueDate`	Date when funds leave your account.
`creditorValueDate`	Date when funds arrive in the recipient's account.
`fees`	Fees associated with the transfer.

Step 4: Transfer Status Codes

Status Code	Description
`WORK_IN_PROGRESS`	Transfer created before 16:00, still processing.
`BOOKED`	Transfer created after 16:00, scheduled for the next business day.
`EXECUTED`	Successfully processed by the bank.
`REJECTED`	Transfer failed, e.g. invalid IBAN or insufficient funds.

Validate Execution Dates

Instant SCT

For instant payments (isInstant == true), there is no need to specify executionDate: transfers are made within seconds, 24/7/365.

Ordinary SCT

The recommendation is to create the money transfer before the bank cut-off time at 16:00 Europe/Rome. executionDate is optional because the system automatically calculates the first available date.

Avoid non-business days:

Saturdays and Sundays;
Italian public holidays: January 1, April 25, May 1, June 2, August 15, November 1, December 8, December 25-26;
Easter Monday.

Minimum execution date rules:

Before 16:00 on a business day: today;
After 16:00 on a business day: tomorrow;
Banking holiday: next business day.

Monitoring the Transfer Status

Fabrick provides complementary monitoring approaches:

Scheduled Monitoring

Run an automated job once a day, for example at 9:00 AM.

On-Demand Monitoring

Use when:

A customer asks about a specific transfer;
Immediate reconciliation is needed;
Testing or troubleshooting.

Account Monitoring

Near real-time detection and notification of incoming and outgoing transaction events on whitelisted accounts using callbacks.

Searching for Transfers

Use the Search Money Transfer API:

POST /money-transfers/search HTTP/1.1
Host: api.fabrick.com
X-Time-Zone: Europe/Rome
Content-Type: application/json
Auth-Schema: S2S
Api-Key: {YOUR_API_KEY}
accountId: {ACCOUNT_ID}

{
  "direction": "OUTGOING",
  "createdDatetime": {
    "from": "2025-05-18",
    "to": "2025-05-27"
  },
  "pagination": {
    "offset": 0,
    "limit": 2000
  }
}

Search Parameters

Recommended search window: a 7-day rolling window.

Parameter	Description
`direction`	`OUTGOING` for initiated transfers; `INCOMING` for received transfers.
`createdDatetime.from`	Search start date, e.g. now() - 7 days.
`createdDatetime.to`	Search end date, e.g. now().
`pagination.limit`	Maximum results per page.
`pagination.offset`	Starting position for pagination.

Status Reconciliation Logic

For each returned transfer:

Match local records using moneyTransferId.
Compare status values.
If unchanged, no action is needed.
If changed, update your database and trigger downstream processes.
Handle special states:
- REJECTED: alert customer, investigate reason, potentially retry;
- EXECUTED: confirm delivery and update records;
- BOOKED: keep monitoring after execution date.

Timeout Handling

If a request times out:

Do not assume the transfer failed;
Log the timeout with the exact timestamp;
For HTTP 500 and 504 errors, perform a validation search using beneficiary name, IBAN, amount, currency, and description;
Wait at least 100 seconds;
Update status based on search results;
Retry only after confirming via search.

This prevents duplicate transfers caused by timeout retry logic.

Error Handling and Validation

HTTP Status Codes

Code	Meaning	Action
200	OK	Process response normally.
400	Bad Request	Validate request and retry with corrections.
401	Unauthorized	Check credentials and regenerate tokens if needed.
403	Forbidden	Verify account access and permissions.
429	Too Many Requests	Implement exponential backoff.
500+	Server Error	Retry after 30 seconds; if persistent, contact Support.

Troubleshooting Common Validation Errors

Invalid IBAN

Check:

IBAN format;
IBAN is up to date;
Country prefix;
IBAN check digit algorithm.

Invalid Execution Date

Check:

Execution date is a business day;
Date is not in the past;
Date is within 30 business days;
Banking availability rules.

Invalid Description Field

Check:

Maximum 140 characters;
Avoid special characters except hyphens and spaces;
Use alphanumeric characters;
Abbreviate long reference information if necessary.

Support and Additional Resources

For technical issues, contact the Fabrick API Support team through the Fabrick website.

Getting Started with Fabrick APIs

Core Use-Case Scenarios

Reconciliation & Accounting: Automatically retrieve transaction lists for payment recognition and reconciliation.
Automated Payout Workflows: Automate refunds, loan disbursements, and reimbursements.
Cash Pooling & Multi-Account Management: Consolidate data across multiple cash accounts.
Local Payment Methods: Process F24, simplified F24, PagoPA, MAV/RAV, and Car Tax payments.
Safeguard Accounts: Manage custody accounts for regulated entities such as IMEL, PI, SGR, and SIM.

API Packages and Capabilities

API Package	Version	Purpose
Cash Account Management	v4.0	Retrieve account details, balances, and account transactions.
Payments / Money Transfers	v4.1	Create transfers, track status, and monitor transactions.

Authentication Methods

Fabrick supports:

API Key Authentication (S2S): Server-to-server communication;
OAuth 2.0: Delegated access and third-party integrations;
JWT (JSON Web Token): Token-based access.

For most direct integrations, use S2S authentication with your assigned API key.