The Virtual Account Object

❗️ Incoming breaking change

We will be implementing the UNBLOCKING status for the Virtual Accounts to streamline the process of account blocking.
UNBLOCKING status will be displayed, when a BLOCKED account is in the process of being unblocked.

As this is a breaking change, it will be implemented on the 29th May. Please keep in mind that not implementing this change will render account unblocking impossible.


Virtual Accounts can be created in multiple currencies and are used to receive fiat money from users and make payouts. Virtual Accounts have unique bank details associated with them but are linked to a MASTER Fiat Account. Virtual Accounts are used for collections and payouts only and do not have a balance associated with them. Any payments made to/from Virtual Accounts affect the balance of the Master Fiat Account with which they are linked.

Virtual Account Object

AttributeDescriptionFormat/Enum
id
string
Unique identifier of the Virtual Account.e.g. vac_5opkx8g1jo50lz4m3e
masterFiatAccountId
string
Unique identifier of a Fiat Account under which the Virtual Account has been created.e.g. fac_p96ed8b1k3n7zvma4o
status
string
Status of the accountCREATED, ACTIVE, ACTIVATION_FAILED, BLOCKED, UNBLOCKING,CLOSED
currency
string
Currency of the Virtual Account.Three-letter ISO 4217 code e.g. GBP, EUR , USD
ibanCountry
string
Depending on your agreement you can choose IBAN country, from the available list.
Required field for all currencies, except GBP
DE, DK, GB, LU
owner.type
string
Owner of the Virtual Account.MEMBER, END_USER
owner.id
string
Unique identifier of the owner of the Virtual Account.e.g. eus_j82rl497g47g5ykvzn, mbr_emv4j231821oaz56yx
businessId
string
Unique identifier for the Business that owns the Virtual Account. A Business represents a Member's legal entity with which it has signed up with Fiat Republic. A Member can have several businesses.e.g. biz_emv4j231821oaz56yx
label
string
An optional label to easily identify the account on the Dashboard.
bankDetails
array of strings
Details of the banking credentials that have been allocated to the Virtual Account.
bankDetails.bankName
string
Name of the banking provider under which the Virtual Account has been created.
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 country code e.g. GB
bankDetails.iban
string
IBAN associated with the account. Depending on the currency and country, 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. Depending on the currency and country, account will typically have at least an IBAN or an accountNumber.
bankDetails.routingCodes
object
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, ABA, WIRE
bankDetails.routingCodes.value
string
Value of the routing code.
createdAt
integer
Epoch timestamp at which the object was created.e.g. 1637593856104
updatedAt
integer
Epoch timestamp at which the object was last updated.e.g. 1637593856104
metadata
string
Additional data in JSON key:value format.See Metadata for more information.

The creation of Virtual Accounts is asynchronous as it requires the generation of bank details with the underlying banking provider. Therefore, upon creation, Virtual Accounts have the status CREATED which is then updated to ACTIVE once bank details are assigned. The process usually takes no more than a couple of minutes.

The best way to be informed of when a Virtual Account becomes Active is to create a Webhook that listens to the event VIRTUAL_ACCOUNT.STATUS_UPDATED

Virtual Account Statuses

Fiat Account StatusDescription
CREATEDThe Virtual Account has been created on Fiat Republic and is awaiting allocation of bank details from the underlying banking provider. The account cannot be used at this stage.
ACTIVEThe Virtual Account is active and can start receiving and making payments.
BLOCKEDThe Virtual Account is blocked temporarily and no payments to/from the account can be created. A Fiat Account could be blocked by Fiat Republic for compliance reasons, but you can also block fiat accounts via the API for your own risk management purposes.
It is highly recommended that you create a Webhook to monitor for this status change to ensure you can update your end users.
CLOSEDThe Virtual Account is closed permanently and cannot be used to make or receive payments anymore. This status is terminal.
ACTIVATION_FAILEDWe were not able to assign bank details to the Virtual Account due to some error.