Financial Split Payments

View as Markdown

Introduction

Financial Split Payments (FSP) is a product that enables the collection of incoming payment flows from different gateways, generated via alternative payment methods, cards, or account-to-account transactions, in order to disburse them through a single payout flow to merchants and all other parties involved in the client's business process (aggregators, intermediaries, platforms, etc.).

FSP can be integrated with Fabrick payment products or used in standalone mode. Below is a brief table summarizing the modes that will be described in detail:

Integration Type	Mode	APIs Involved	When to use it
Combined with Fabrick	Static	Fabrick pisp APIs	If Fabrick products are already used and dynamic split is not needed.
Combined with Fabrick	Dynamic	Fabrick pisp APIs + FSP APIs (split)	If Fabrick products are already used and dynamic split is needed.
Standalone	Static	Money-IN APIs	For an integration independent of other Fabrick products.
Standalone	Dynamic	Money-IN APIs + FSP APIs (split)	For an independent integration with dynamic split management.

In static mode, the split percentage of the amount towards the various accounts is defined during the contract phase, so no further API development will be required. The split percentage will therefore always be the same for every payment that needs to be handled with the split.

The dynamic approach, on the other hand, allows you to decide the split percentage via API for each individual amount received on the account. Therefore: for each incoming payment flow, the merchant selects the allocation quotas among the stakeholders;

FSP executes the split processes asynchronously relative to the requests and updates the merchant's backend systems on the status of these processes via callbacks.

Regarding the integration type, two typologies are possible:

• combined with Fabrick transactional products: such as PSD2 Pay by Bank or Fabrick Orchestra with multiple alternative payment methods, which automatically notify FSP of the expected credit (Money In) to be validated.

• in standalone mode: in this case, it is the aggregator's responsibility to communicate the Money-In attributes and specify the allocation of the relative quotas among the various clients.

A simple overview is available here (in Italian).

Glossary

FSP Technical system underlying the Financial Split Payments product.

Aggregator Legal entity that aggregates one or more clients.

Client Entity that receives its allocated quota of credits from a specific Money In through a first-level split payment operation. A client can have multiple contracts in relation to different aggregators.

Money In Credit received on the aggregator's account. Each Money In is typically split among the aggregator's clients based on their respective quotas.

Money Out The portion of funds allocated to a client. Money Outs are processed through the cashout flow. This concept corresponds to "Cash In" in the Financial Split Payments contract. Within FSP, it is the technical entity used to trigger the distribution of funds, i.e., cashout, based on split rules, applied fees, and residual allocations.

Cash Out A second-level split payment where each Money Out is allocated to one or more beneficiaries.

CashoutOrders Define how the amount of a single moneyOut is distributed through a cashout operation. Each Dynamic Cashout request includes one or more Cashout Orders, each specifying the rules for splitting the moneyOut.

Split Payment Rules A split rule is a part of a Cashout Order that defines a single cashout operation. It specifies the amount to be transferred to a specific beneficiary, effectively determining how the overall moneyOut is distributed.

Dynamic Cashout A process that defines one or more cashoutOrders, each specifying the split rules for distributing the amount of a moneyOut among one or more beneficiaries.

Net Residual The remaining amount after all cashouts have been defined and applicable fees deducted. This residual is assigned to a third party—typically the client—specified in the cashoutOrders definition.

Integration Guide: combined with Fabrick

In this mode, FSP works in combination with Fabrick's transactional products, such as PSD2 Pay by Bank or Fabrick Orchestra. This simplifies the process since all payment information is already implicitly known to Fabrick. In fact, for every payment executed with one of the Fabrick products, FSP will already be awaiting the credit, knowing the relative details in advance.

Static Mode

In this case, no FSP development is required since the split rules will be established during the setup phase and will be valid and applied for all credits.

It will be sufficient to develop the payment initialization APIs with the chosen Fabrick product.

Dynamic Mode

In this second case, however, it will be necessary to integrate the API service to apply the split rules for each credit.

The first step to create a dynamic cashout request consists of invoking the Moneyout list service. See the GET MoneyOutList service. The output of this service provides the list of moneyOuts available for cashout. An example of the service response is as follows:

{
  "status": "OK",
  "errors": [],
  "payload": [
    {
      "moneyOutCode": "MO2025101510000000001156",
      "amount": 100.00,
      "currency": "EUR",
      "moneyInSender": "SenderName",
      "moneyInTransferId": "EA24020312345678912345678912IT",
      "moneyInDescription": "AXYD302"
    }
  ]
}

The second step to create a dynamic cashout request involves invoking the POST CreateDynamicCashout service. This service allows the execution of cashout transactions for the specified moneyOut amounts, facilitating the distribution of funds according to the defined split rules. The service operates asynchronously. The response confirms whether the request has been accepted for processing or, in case of incoming payload validation errors, returns the detected issues. The outcome of any accepted processing is communicated to the caller via callback. For each moneyOut specified in a cashoutOrder, split payment rules must be defined, indicating the amounts to be allocated to the designated beneficiaries. Below is an example of the service input. Here, a cashoutOrder including two split rules is defined. Additionally, the netResidual, the call identifier, and references are specified so that FSP can execute the callback to notify the status of the cashout process.

{
  "validationCallbackUri": "https://merchant.com/validation",
  "resultCallbackUri": "https://merchant.com/validation",
  "requestId": "a089a4bc-96df-48e2-92ba-9941aa718088",
  "cashOutOrders": [
    {
      "moneyOutCode": "MO122549191289212ANVZ000528",
      "splitRules": [
        {
          "amount": 10.93,
          "beneficiary": {
            "accountName": "Example",
            "paymentMethod": {
              "iban": "IT92V0326803202677155639978",
              "type": "SCT",
              "whitelisted": true
            }
          }
        }
      ]
    }
  ],
  "netResidual": {
    "accountName": "MERCHANTCOMPANY SPA",
    "paymentMethod": {
      "iban": "IT60X0542811101000000123456",
      "type": "SCT",
      "whitelisted": true
    }
  }
}

Constraints for Dynamic Cashout Execution

Split Consistency

Cashout can only be executed if the sum of all amounts assigned to beneficiaries, added to applicable fees, exactly matches the total amount of the moneyOut.

Distinct Beneficiaries

Each split rule must define unique beneficiaries. No beneficiary can appear more than once within the same rule.

Residual Allocation

A netResidual must be defined to credit any remaining amount after applying the split rules and deducting fees. The netResidual must not be present among the beneficiaries defined in the split rules.

Currency Homogeneity

The currency of the moneyOut, cashoutOrders, and netResidual must be the same.

Outcome Management

The cashout operation ends with a positive or negative outcome. In case of failure, it is the caller's responsibility to submit a new cashout request for the affected moneyOut.

 

Validation Callback

Asynchronous communication from FSP to the callers' backend systems occurs via callbacks. The callback communicates the outcome of the substantive validation of the dynamic cashout request. The system checks the availability of the moneyout elements included in the request and, if enabled, performs the VoP check when SCT payment methods are used. If the validation outcome is OK, the cashout process is initiated and a subsequent callback reports its outcome. In case of a KO outcome, validation errors are reported and the entire cashout request is rejected. The moneyout elements included in the request remain available for future dynamic cashout requests. A KO outcome occurs when the cashout request is insufficiently funded, or when VoP checks are enabled and at least one of them fails. The callback is executed via the POST method on the endpoint specified by the caller. The invocation of the service does not require authorization. In case of technical call failure, a retry policy is applied to attempt the call multiple times.

Below is the structure of the callback message.

{
  "requestCorrelationId": "string",
  "requestDateTime": "string",
  "validationResult": "OK",
  "cashOutOrdersErrors": [
    {
      "moneyOutCode": "string",
      "errors": [
        {
          "errorCode": "string",
          "description": "string",
          "params": "string"
        }
      ]
    }
  ]
}

• requestCorrelationId: Correlation ID of the dynamic cashout call.
• requestDateTime: Date and time of the request. ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.
• validationResult: Possible validation outcomes:
  • OK: validation completed successfully;
  • KO: validation failed and cashout process interrupted.
• cashOutOrdersErrors: CashoutOrders with errors.
• moneyOutCode: ID of the unprocessable moneyout.
• errors: Represents any error occurring during the lifecycle of a request, including both validation failures and execution issues:
  • errorCode: error code;
  • description: error description;
  • params: additional error descriptions.

Integration Guide: Standalone

In standalone mode, it is the aggregator's responsibility to communicate the Money-In attributes and specify the allocation of the relative quotas among the various clients. For this reason, it will be necessary to integrate the following API service to share payment information with FSP.

Static / Dynamic Mode

Regarding the distinction between static or dynamic mode, nothing changes compared to the integration with Fabrick products; they always have the same meaning. Below we will describe the endpoint in question.

Creating the Money-in Request

The POST CreateMoney-in service allows the aggregator to communicate an expected credit to FSP, i.e., the data necessary to verify movements on the aggregator's account. Below is an example of using this service:

Input example:

The details of the fields included in the request are explained in the technical documentation of the service.

Below are some notes on using the service:

• The currencies used must be among those supported by FSP.
• All amounts in the CreateMoney-in request must use the same currency.
• FSP does not support currency conversion.
• The reconciliationCallbackUri attribute, if provided by the caller, allows FSP to send a callback to the client system to notify the outcome of the accounting reconciliation.
• The service can return OK or KO as an outcome.
• OK means the reconciliation process has been taken in charge; if successful, FSP initiates Cashin and Cashout as specified in the contract with clients.
• Clients are identified via their VAT number.
• Only client identifiers active in the aggregator's domain are allowed.
• clientIds must not be repeated within the request.
• The createMoney-in request is identified by the creditTransferId field.
• The value of creditTransferId can only be reused after the previous request has completed reconciliation with a KO outcome.

FSP Reconciliation Process

Once the expected credit data has been acquired, FSP examines the observed credits received on the aggregator's account. Reconciliation is performed between an expected credit and an observed credit that share the same unique identifier, transferId. Reconciliation then verifies that the two credits match according to the following rules:

• The acquirer associated with the expected credit must be correctly identified and recognized.
• Both credits must be denominated in the same currency.
• The amounts of the expected credit and the observed credit must be identical.

The reconciliation process can have three outcomes:

• OK: Reconciliation completed successfully.
• KO: At least one reconciliation rule was violated; in this case, the request can be resent with correct data.
• IN_PROGRESS: Reconciliation is still ongoing, as not all required credit data is available yet.

When reconciliation is finally completed, the outcome is automatically updated to OK or KO.

Reconciliation Callback

FSP can send a callback to the caller to notify the outcome of the reconciliation process. This happens if the reconciliationCallbackUri field was provided in the POST CreateMoney-in request. The structure of the callback payload is illustrated below.

{
  "reconciliationOutcome": {
    "creditTransferId": "TRN/CRO",
    "reconciliationStatus": "OK||KO||IN_PROGRESS",
    "moneyIn": {
      "amount": {
        "value": 100,
        "currency": "EUR"
      }
    },
    "observedTransfer": {
      "amount": {
        "value": 100,
        "currency": "EUR"
      }
    }
  }
}

The following table describes the structure of the callback payload.

Field	Type	Mandatory	Usage
reconciliationOutcome	Object	Y	Response data container.
reconciliationOutcome.creditTransferId	String	Y	Bank transfer identifier, TRN/CRO, shared by the expected and observed credit.
reconciliationOutcome.reconciliationStatus	Enum: OK, KO, IN_PROGRESS	Y	Reconciliation status.
reconciliationOutcome.moneyIn	Object	Y	Amount details.
reconciliationOutcome.moneyIn.amount	Object	Y	Credit amount.
reconciliationOutcome.moneyIn.amount.value	Number, two decimals	Y	Account lifecycle tracking.
reconciliationOutcome.moneyIn.amount.currency	String ISO 4212	Y	Currency code, 3 characters.
reconciliationOutcome.observedTransfer	Object	Y	Observed credit description.
reconciliationOutcome.observedTransfer.amount	Object	N	Amount details, if available.
reconciliationOutcome.observedTransfer.amount.value	Number, two decimals	N	Amount details, if available.
reconciliationOutcome.observedTransfer.amount.currency	String ISO 4212	N	Currency code, if available.

The IN_PROGRESS status is reported by the callback when reconciliation is not completed within the defined time threshold.

Technical Aspects Regarding Callback Invocation

The callback is sent using the POST method to the endpoint specified in the POST CreateMoneyIn request. In case of invocation failure, FSP applies its retry policies. The callback is invoked without any authorization mechanism; however, Fabrick can provide the list of IP addresses to whitelist.

ResultCallback

Invoked by FSP to notify the consumer of the operation outcomes.

Currently, it is only available for dynamic mode and the Fabrick products integration type.

The callback is executed via the POST method on the endpoint specified by the caller. The invocation of the service does not require authorization. In case of technical call failure, a retry policy is applied to attempt the call multiple times.

The following example shows the content structure of the callback.

{
  "requestCorrelationId": "string",
  "requestDateTime": "string",
  "completionDateTime": "string",
  "cashOutOrdersResults": [
    {
      "moneyOutCode": "string",
      "cashOutCode": "string",
      "cashOutAmount": 0,
      "currency": "string",
      "outcome": "OK",
      "error": {
        "errorCode": "string",
        "description": "string",
        "params": "string"
      },
      "transfer": {
        "amount": 0,
        "currency": "string",
        "accountName": "string",
        "paymentMethod": {
          "transferId": "string",
          "iban": "string",
          "whitelisted": true,
          "countryISOCode": "string",
          "address": "string",
          "swiftCode": "string",
          "accountNumber": "string",
          "city": "string",
          "type": "SCT"
        }
      }
    }
  ]
}

• requestCorrelationId: Correlation ID of the dynamic cashout call.
• requestDateTime: Date and time of the request. ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.
• completionDateTime: Date and time indicating when request processing was completed. ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.
• cashOutOrdersResults: represents a processed cashout order. If the cashout was executed successfully, the response includes details of the associated bank transfer. If execution failed, transfer information is omitted and error details are provided.
• moneyOutCode: identifier of the moneyout associated with the cashout.
• cashOutCode: identifier of the cashout generated by the system.
• cashOutAmount: cashout amount expressed with two decimal places.
• currency: cashout currency. 3-character ISO 4217 format.
• outcome: Possible validation outcomes:
  • OK: validation completed successfully;
  • KO: validation failed and cashout process interrupted.
• error: section populated in case of a KO outcome:
  • errorCode: error code;
  • description: error description;
  • params: additional error information.
• transfer: details of the bank transfer associated with this cashout. The transfer can be shared among multiple cashouts. This field is present only if the cashout was processed successfully.
• amount: transfer amount.
• currency: transfer currency. ISO 4217.
• accountName: Full name of the bank transfer recipient.
• paymentMethod: information regarding the payment method to be used for the split transaction. Supported options are SEPA bank transfer and international bank transfer. SEPA transfers are indicated as SCT, while international transfers are indicated as WIRE.
• transferId: Transfer identifier. When type is SCT, this identifier contains the TRN or CRO code.
• iban: Beneficiary's IBAN. This field is mandatory when the selected payment method is SEPA (SCT).
• whitelisted: The whitelisted flag indicates whether, in the case of the SCT payment type, the IBAN-beneficiary pair should be considered trusted and therefore exempt from the VoP check. Not present if the transfer is of type WIRE.
• countryISOCode: Beneficiary country code expressed in two-character ISO 3166 format. Present if type is WIRE.
• address: Beneficiary address. Must not be provided unless type is WIRE; optional when type is WIRE.
• swiftCode: SWIFT code required in case of international bank transfer (WIRE). Must be populated if type is WIRE.
• accountNumber: Bank account number required for international transfers. Must be populated if type is WIRE.
• city: Beneficiary's city of residence. Required when the selected payment method is international bank transfer. Must not be provided unless type is WIRE; optional when type is WIRE.
• type: Supported payment types: SCT for SEPA transfers, WIRE for non-SEPA transfers.

Verification of Payee (VoP)

The Verification of Payee (VoP) process applies to SEPA Credit Transfers and was introduced under the EU Instant Payments Regulation, in force since October 9, 2025.

VoP ensures that the IBAN provided for a transfer matches the name of the intended beneficiary, helping to prevent fraud and misdirected payments.

Obviously, this section is useful for the dynamic mode, since in static mode accounts are checked during the setup phase.

VoP check outcomes:

• MATCH: Full match between IBAN and account holder name.
• CLOSE MATCH: Partial match. Error code: CMTC.
• NO MATCH: No match. Error code: NMTC.
• NOT AVAILABLE: VoP check could not be executed by the receiving PSP. Error code: NOAP.
• TECHNICAL ERROR: Internal system error. Error code: ERR.

Further information is available in the dedicated section.

VoP in the FSP Cashout Process

Within the Financial Split Payment framework, cashout operations are executed automatically in unattended mode.

During onboarding, merchants can decide whether or not to enable VoP checks for dynamic cashout requests:

• If VoP checks are disabled, the system skips verification for all cashout requests;
• If VoP checks are enabled, the system performs the check during the substantive validation phase of the cashout request.

Whitelisted Flag Behavior

When VoP checks are enabled, a whitelist flag can be used to handle VoP errors:

• whitelisted = TRUE: Forces the system to skip the VoP verification.
• whitelisted = FALSE and VoP checks enabled: VoP verification is enabled.
• whitelisted = FALSE and VoP checks disabled: VoP verification is disabled.
• If the field is not present in the payload, FALSE is assumed as the default value.

Below is a typical process flow involving Verification of Payee:

• A dynamic cashout request is submitted without the optional whitelisted field.
• If VoP errors occur, they are returned in the validation callback.
• The caller can then:
  • Correct the beneficiary data and resubmit the request, or
  • Resubmit the request with the same data setting whitelisted = TRUE to bypass VoP verification.