---
title: "Banking as a Service"
description: "In this document, you'll find an introduction to the world of Banking as a Service."
url: "https://docs.fabrick.com/en/payment-institution/banking-as-a-service/introduction/money-transfer-vop/"
language: "en"
---

# 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:

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

#### Request Example

```bash
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

```json
{
  "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:

```bash
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:

```text
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.

```bash
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)

```json
{
  "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:

```http
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:

1. Match local records using `moneyTransferId`.

2. Compare status values.

3. If unchanged, no action is needed.

4. If changed, update your database and trigger downstream processes.

5. 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.