Payee

Payees are external bank accounts to which payments can made from Fiat Accounts and Virtual Accounts. Different types of payments can be made to the same Payee depending on the bank details provided for the Payee at the time of creation.

Please be informed that payouts to Payees of different entities (owners) are forbidden. This means that only the End User who is the owner of the Payee, may initiate payments to it.

On creation, Payee's address object is required regardless of currency.
Creating Payee without providing this information will result in getting 400 Bad Request response.

Payee address can be updated (excluding the country). The format of the request does not change.

Payment Scheme resolution

Payment scheme resolution is determined by the nature of the bank details provided. We facilitate money transfers across multiple members via the EagleNet network. When bank details correspond to a FR-managed Fiat or Virtual account, we enforce the EAGLE_NET_TRANSFER scheme, overriding any future payment scheme resolution. These payees will always be assigned this payment scheme.

For external payouts, the payment scheme is resolved based on two factors: the provided payee details (including currency, country, and bank details) and the payment rails available for your setup. Since payment rails can be limited by currency and country, this is the primary factor in our determination. After identifying potential schemes, we validate bank details for each. Because a combination of country and currency can be supported by multiple schemes with potentially conflicting details, we validate details against all of them, and validation only fails if none possess sufficient details for resolution. Otherwise, valid schemes are selected and returned. Additionally, we verify if the accounts you are using can support all valid resolved schemes, filtering out those that cannot. While this information is not yet accessible via API, it is provided during the onboarding process. Should this topic raise questions, please direct them to your customer success manager or the relevant channel used during onboarding.

In case of failure and validation error standard FiatRepublic error response will be returned, with each message prefixed with potential payment scheme for which validation error is applicable to. Please see the example:

{
    "errorCode": "INVALID_REQUEST_DATA",
    "message": "Invalid Payee input data. Not enough data for any payment scheme. Potential schemes are [ACH, ACH_SAME_DAY, WIRE].",
    "warnings": [
        {
            "position": "bankDetails.routingCodes[0].value",
            "issue": "[ACH] The value of 'ABA' should have exactly 9 characters."
        },
        {
            "position": "bankDetails.routingCodes[0].value",
            "issue": "[ACH_SAME_DAY] The value of 'ABA' should have exactly 9 characters."
        },
        {
            "position": "bankDetails.routingCodes[1].value",
            "issue": "[WIRE] The value of 'WIRE' should have exactly 9 characters."
        }
    ]
}

It is important to note that the scheme resolution process does not alter payee structure or our broader treatment of payees. Please refer to the next section for further details and general guidance regarding required bank details per scheme.

Resolved schemas will be available as paymentScheme array of strings field upon successful creation of a payee:

"paymentSchemes":[
      "FPS",
      "CHAPS"
]

"paymentSchemes":[
      "SCT"
   ]

"paymentSchemes":[
      "DE"
   ]

"paymentSchemes":[
      "SWIFT"
   ]

Additional details required only for USD Payees:

To create a USD Payee, the following additional details must be provided as part of the Payee's object:

• address: State field (however for non US addresses it can be province, voivodeship, region)
• for bank details you must provide either:
  • (bankDetails.iban , bankDetails.bic AND bankDetails.routingCodes ) OR
  • (bankDetails.accountNumber , bankDetails.bic AND bankDetails.routingCodes )
  • at least one of bankDetails.bankCountry OR bankDetails.bankAddressCountry must also be provided.

The bankDetails required for a Payee depend on the currency and the type of payment you want to make to the Payee. You can find the complete list here: Required Bank Details for Payees

To maintain the highest standards of compliance and effectively restrict third-party payments, a Compliance Review is automatically initiated when there is a discrepancy between the Payee's name and the End User's name, ensuring all Payment processes are transparent and secure.

We work on Compliance Review during business hours.

Payee Statuses