Fiat Accounts are bank-detail-enabled payment accounts used to receive fiat deposits and execute payouts. They are assigned unique bank details (such as an IBAN or Account Number/Sort Code) that can be targeted by external payment rails depending on the currency of the account.
Fiat Account Schema
| Attribute | Description | Format / ENUMS |
|---|---|---|
| id string | Unique identifier of the Fiat Account. | e.g. fac_ov8jkx67ndy1dbglam |
| businessId string | Unique identifier for the Business that owns the Fiat Account. A Business represents a Member's legal entity. A Member can have several businesses. | e.g. biz_emv4j231821oaz56yx |
| owner object | The entity that owns the Fiat Account. | |
| owner.type string | Owner type of the Fiat Account. | MEMBER |
| owner.id string | Unique identifier of the owner of the Fiat Account. | e.g. mbr_emv4j231821oaz56yx |
| ibanCountry string | Depending on your agreement, you can choose the IBAN country from the available list. Required field for all currencies, except GBP and USD. | DE, DK, GB, LU |
| balance object | The real-time liquidity state of the account. | |
| balance.actual string | Full balance of the account, including any pending transactions. | e.g. 1000.00 |
| balance.available string | Available balance of the account that can be consumed or paid out. | e.g. 800.00 |
| balance.reserved string | Total of all pending payouts that have been initiated but not yet completed. | e.g. 200.00 |
| currency string | Currency of the Fiat Account. | Three-letter ISO 4217 code e.g. GBP, EUR, USD, AUD |
| bankDetails object | Details of the banking credentials that have been allocated to the Fiat Account. | |
| bankDetails.bankName string | Name of the banking provider under which the Fiat Account has been created. | e.g. Partner Bank S.A. |
| bankDetails.accountHolderName string | Name of the account holder. This is the name that will appear on the recipient's statement when payments are sent from this account. | |
| bankDetails.country string | Country where the account is held. | Two-letter ISO 3166-1 alpha-2 e.g. GB, LU |
| bankDetails.iban string | IBAN associated with the account. Depending on the currency and country, the account will typically have at least an IBAN or an accountNumber. | |
| bankDetails.bic string | SWIFT BIC associated with the account. Depends on the account currency and country. Not all accounts will have a BIC. | |
| bankDetails.accountNumber string | Account Number associated with the account. | |
| bankDetails.routingCodes array of objects | One or more routing codes associated with the account. Typically used in conjunction with the account number. | |
| bankDetails.routingCodes[].type string | Type of the routing code. | SORT_CODE, BSB |
| bankDetails.routingCodes[].value string | Value of the routing code. | |
| label string | An optional string to easily identify the account on the Dashboard. | e.g. EUR Client Funds |
| status string | The current lifecycle state of the account. | CREATED, ACTIVE, ACTIVATION_FAILED, BLOCKED, UNBLOCKING, CLOSED |
| tags array of strings | Tags associated with the account to designate its regulatory and operational purpose. Note: CLIENT_MONEY and CORPORATE are mutually exclusive. See the Fiat Account Concept Guide for strict tag upgrade rules. | CLIENT_MONEY, CORPORATE, MASTER |
| createdAt integer | Epoch timestamp (in milliseconds) at which the object was created. | e.g. 1637593856104 |
| updatedAt integer | Epoch timestamp (in milliseconds) at which the object was last updated. | e.g. 1637593856104 |
| metadata object (or null) | Additional data in JSON key:value format. | See Metadata |
Fiat Account Statuses
The creation of a Fiat Account is asynchronous as it requires the generation of bank details with the underlying banking provider. Upon creation, Fiat Accounts have the status CREATED, which is updated to ACTIVE once bank details are assigned. This process usually takes no more than a few seconds.
The best way to monitor this lifecycle is to create a Webhook that listens for the FIAT_ACCOUNT.STATUS_UPDATED event.
| Fiat Account Status | Description |
|---|---|
CREATED | The account has been created on Fiat Republic and is awaiting allocation of bank details from the underlying banking provider. It cannot be used at this stage. |
ACTIVE | The account is active and can start receiving and making payments. |
BLOCKED | The account is temporarily blocked. No payments to/from the account can be processed. Accounts may be blocked for compliance reasons or via the API for your own risk management. |
UNBLOCKING | The account is in the process of having a block removed. |
CLOSED | The account is permanently closed and cannot be used. This status is terminal. |
ACTIVATION_FAILED | We were not able to assign bank details to the Fiat Account due to an upstream provider error. |
Fiat Account Balance
Each Fiat Account has 3 separate balances:
| Balance Type | Description |
|---|---|
balance.actual | The actual settled balance of an account taking into consideration all posted transactions. |
balance.reserved | The sum of all payouts initiated from the account that are not yet fully completed. |
balance.available | The net balance available for new payouts.Available Balance = Actual Balance - Reserved Balance |
"balance": {
"actual": "1000.00",
"available": "800.00",
"reserved": "200.00"
}