Skip to main content

FSP Standard

In the standard mode the FSP product works in combination with Fabrick’s transactional products, such as PSD2 Pay by Bank or Fabrick Orchestra, In this page we will decribe how to manage the process throuch API.

Creating a dynamic cashout request​

The first step in creating a dynamic cashout request is to invoke the Moneyout list service. See the service GET MoneyOutList. 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 in creating a dynamic cashout request involves invoking the POST CreateDynamicCashout service. This service allows for 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 input payload validation errors, returns the detected issues. The outcome of any accepted processing is communicated to the caller through a callback. For each specified moneyOut in a cashoutOrder, split payment rules must be defined, specifying the amounts to be allocated to the designated beneficiaries. This is an example of the service input. Here, a cashoutOrder is defined that includes two split rules. Additionally, the netResidual, the call identifier, and the references are specified so that FSP can perform 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​

The cashout can only be executed if the sum of all amounts assigned to beneficiaries plus 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 split rules and deducting fees. The netResidual must not be listed 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 results in either a successful or failed outcome. In the event of failure, the caller is responsible for submitting a new cashout request for the affected moneyOut.

Verification of Payee (VoP)​

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

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

VoP Check Outcomes:

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

Detailed information can be found at this link:

  • Verification Payee Scheme Rulebook

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 to enable VoP checks for dynamic cashout requests, or not:

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

Whitelisted Flag Behavior​

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

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

The following is a typical process flow that involves VoP verification:

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

Callbacks​

Asynchronous communication from the FSP to the backend systems of the callers takes place via two callbacks:

  • validationCallback
  • resultCallback

The callback is executed in a fire-and-forget manner. This means that the system does not expect nor process any response from the callback endpoint. The responsibility for handling the callback data lies entirely in the receiving system.

ValidationCallback​

The callback communicates the result of the substantial validation of the dynamic cashout request. The system checks the availability of the moneyout items included in the request and, if enabled, performs the VOP check when using SCT-type payment methods. If the validation result is OK, the cashout process is initialized and a subsequent callback reports its outcome. In case of a KO result, validation errors are reported and the entire cashout request is rejected. The moneyout items included in the request remain available for future dynamic cashout requests. A KO result occurs when the cashout request is not sufficiently funded, or when VoP checks are enabled and at least one of them fails. The callback is performed using the POST verb on the endpoint specified by the caller. The service invocation does not require authorization. In case of technical failure of the call, a retry policy is applied to attempt the call multiple times.

This 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: Request date and time. Format ISO 8601: YYYY-MM-DDThh:mm:ss.sssZ.
  • validationResult: Possible validation outcomes:
    • OK: validation successfully completed;
    • KO: validation failed and the cashout process was aborted.
  • cashOutOrdersErrors: CashoutOrders with errors.
  • moneyOutCode: ID of the unprocessable moneyout.
  • errors: Represents any error that occurs during the lifecycle of a request, including both validation failures and execution issues:
    • errorCode: error code;
    • description: error description;
    • params: Additional error descriptions.

ResultCallback​

It is invoked by the FSP to notify the consumer about the outcome of the submitted dynamic cashout operations. The callback is performed using the POST verb on the endpoint specified by the caller. The service invocation does not require authorization. In case of technical failure of the call, a retry policy is applied to attempt the call multiple times.

The following example shows the structure of the callback content.

{
  "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: Request date and time. Format ISO 8601: YYYY-MM-DDThh:mm:ss.sssZ.
  • completionDateTime: Date and time indicating when the processing of the request was completed. Format ISO 8601: YYYY-MM-DDThh:mm:ss.sssZ.
  • cashOutOrdersResults: represents a processed cashout order. If the cashout was successfully executed, the response includes the associated bank transfer details. If the execution failed, the transfer information is omitted and error details are provided instead.
  • moneyOutCode: moneyout identifier associated with the cashout.
  • cashOutCode: system-generated cashout identifier.
  • cashOutAmount: cashout amount expressed with two decimal digits.
  • currency: cashout currency. Format 3 char ISO 4217.
  • outcome: Possible validation outcomes:
    • OK: validation successfully completed;
    • KO: validation failed and the cashout process was aborted.
  • error: section populated in case of outcome KO:
    • errorCode: error code;
    • description: error description;
    • params: additional error information.
  • transfer: details of the bank transfer associated with this cashout. The transfer may be shared across multiple cashouts. This field is present only if the cashout was successfully processed.
  • amount: transfer amount.
  • currency: transfer currency. ISO 4217.
  • accountName: Recipient's full name for the bank transfer.
  • 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 the type is SCT, this identifier contains either the TRN code or the CRO code.
  • iban: IBAN of the beneficiary. This field is required when the selected payment method is SEPA (SCT).
  • whitelisted: The whitelisted flag indicates whether, in the case of SCT payment type, the IBAN-beneficiary pair should be considered trustworthy and therefore exempt from the VoP check. Not present if the transfer is WIRE.
  • countryISOCode: Beneficiary's country code expressed using the two-character ISO 3166 format. Present if type is WIRE.
  • address: Beneficiary's address. Must not be provided unless type is WIRE; optional when type is WIRE.
  • swiftCode: SWIFT code required in case of an international bank transfer (WIRE). Should be populated if type is WIRE.
  • accountNumber: Bank account number required for international transfers. Should be populated if type is WIRE.
  • city: City of residence of the beneficiary. 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 credit transfers, WIRE for non-SEPA transfers.