Creating End Users and Accounts
Create End Users and Accounts
Now, you will be able to start creating Accounts to make and receive payments. These can be created on behalf of yourselves - the Fiat Republic Member, or your end users.
Step 1: Create a Member Fiat Account
Member Fiat Accounts are owned by the Crypto platform and have two primary functions. Firstly, these accounts tend to be used for Member's treasury purposes e.g. payments to liquidity providers would typically occur to/from a Member Fiat Account. The other use of Member Fiat Accounts would be to pool deposits from End Users, via the use of Virtual Accounts.
Member Fiat Account Creation
You will typically only have a limited number of Member Fiat Accounts, and therefore can create them via the Dashboard instead of implementing an API flow.
To create a Member Fiat Account, you will need to use the create Fiat Account endpoint, providing the currency in which you wish to create said Fiat Account. You can also provide an optional label to be able to easily identify the Fiat Account on your Dashboard.
You will need to leave the endUserId field null (or not set) to create a Fiat Account for yourselves (the Member) rather than for an End User. The owner.type field in the response will be MEMBER, indicating that the account belongs to the Member.
curl --request POST \
--url https://sandbox.fiatrepublic.com/api/v1/fiat-accounts \
--header 'Content-Type: application/json' \
--data '
{
"currency": "GBP",
"label": "GBP Treasury Account"
}
{
"id": "fac_exz3l6d7bmn1myjr5v",
"businessId": "biz_ejl2vpn1m305rxko6b",
"owner": {
"type": "MEMBER",
"id": "mbr_ejl2vpn1m305rxko6b"
},
"balance": {
"actual": "0.00",
"available": "0.00",
"reserved": "0.00"
},
"currency": "GBP",
"bankDetails": null,
"label": "GBP Treasury Account",
"status": "CREATED",
"tags": [
"CORPORATE"
],
"createdAt": 1649843110831,
"updatedAt": 1649843110831,
"metadata": null
}
Fiat Account creation is an an asynchronous process as it requires the bank details to be generated by the underlying banking provider e.g. the IBAN or Account Number. Therefore, the initial status of the Fiat Account will be CREATED and the bankDetails field will be null.
Once bank details have been assigned, the status of the Fiat Account will be updated from CREATED to ACTIVE. This process usually takes no longer than a few seconds.
You can confirm the status of your Fiat Account by consuming the FIAT_ACCOUNT.STATUS_UPDATED or FIAT_ACCOUNT.UPDATED event, calling the GET Fiat Account endpoint, or on the Dashboard.
GET Fiat Account request example:
curl --request GET \
--url https://sandbox.fiatrepublic.com/api/v1/fiat-accounts/fac_exz3l6d7bmn1myjr5v \
--header 'Accept: application/json' \
{
"id": "fac_exz3l6d7bmn1myjr5v",
"businessId": "biz_ejl2vpn1m305rxko6b",
"owner": {
"type": "MEMBER",
"id": "mbr_ejl2vpn1m305rxko6b"
},
"balance": {
"actual": "0.00",
"available": "0.00",
"reserved": "0.00"
},
"currency": "GBP",
"bankDetails": {
"bankAddress": null,
"bankName": "Modulr FS Ltd.",
"accountHolderName": "GOOFY",
"country": "GB",
"iban": null,
"bic": null,
"accountNumber": "70855331",
"routingCode": {
"value": "000000",
"type": "SORT_CODE"
}
},
"label": "GBP Treasury Account",
"status": "ACTIVE",
"tags": [
"CORPORATE"
],
"createdAt": 1649843110831,
"updatedAt": 1649843111981,
"metadata": null
}
FIAT_ACCOUNT.STATUS_UPDATED event example
{
"id":"evt_r2pva4dgy9bleabxm7m031j9ln",
"event":"FIAT_ACCOUNT.STATUS_UPDATED",
"data":{
"id":"fac_exz3l6d7bmn1myjr5v",
"businessId":"biz_ejl2vpn1m305rxko6b",
"owner":{
"type":"MEMBER",
"id":"mbr_ejl2vpn1m305rxko6b"
},
"balance":{
"actual":"0.00",
"available":"0.00",
"reserved":"0.00"
},
"currency":"GBP",
"bankDetails":{
"bankAddress":null,
"bankName":"Fiat Republic",
"accountHolderName":"Crypto Exchange Inc.",
"country":"GB",
"iban":null,
"bic":null,
"accountNumber":"70855331",
"routingCodes":[
{
"value":"000000",
"type":"SORT_CODE"
}
]
},
"label":"GBP Treasury Account",
"status":"ACTIVE",
"tags":[
"CORPORATE"
],
"createdAt":1649843110831490,
"updatedAt":1649843111981766,
"metadata":null
},
"previousValues":{
"id":"fac_exz3l6d7bmn1myjr5v",
"status":"CREATED",
"bankDetails":null
},
"createdAt":1649843112003
}
Step 2: Create an End User
You'll need to create your customers as End Users on Fiat Republic's platform, before you can start creating Virtual Accounts for them.
End Users can be created using the create individual End User endpoint. For this request, you will need to provide the firstName, lastName, email, dob, and address of the user. You also have the option to add several other fields, including but not limited to nationality and linkedCryptoWallets.
The request is processed asynchronously, and a successful request results in the End User object being returned in a CREATED status.
To stay informed about status updates, setting up webhooks is advisable.
Also, note that we have recently introduced REJECTED status.
Keep in mind that a Virtual Account for the End User can only be created when the End User is in an ACTIVE status.
POST End User request example
curl --request POST \
--url https://sandbox.fiatrepublic.com/api/v1/end-users/individuals \
--header 'Accept: application/json' \
--data '
{
"person": {
"address": {
"line1": "123 Queens Road",
"city": "London",
"postalCode": "SE10 8QL",
"country": "GB"
},
"firstName": "John",
"lastName": "Doe",
"dob": "1995-06-15",
"phone": "+447123987456",
"email": "[email protected]",
"birthCountry": "GB",
"nationality": [
"GB"
],
},
"ipAddress": "35.191.2.17"
}
}
{
"id": "eus_2pjbyge1l2n0d9z8kl",
"person": {
"firstName": "John",
"lastName": "Doe",
"address": {
"line1": "123 Queens Road",
"line2": null,
"city": "London",
"state": null,
"postalCode": "SE10 8QL",
"country": "GB"
},
"email": "[email protected]",
"phone": "+447123987456",
"birthCountry": null,
"nationality": null,
"dob": "1995-06-15"
},
"ipAddress": null,
"linkedCryptoWallets": null,
"tags": [],
"status": "ACTIVE",
"createdAt": 1649850191451,
"updatedAt": 1649850191451,
"metadata": null
}
curl --request POST \
--url https://sandbox.fiatrepublic.com/api/v1/end-users/businesses \
--header 'Accept: application/json' \
--data '
{
"business": {
"companyName": "Kling Group",
"tradingName": null,
"type": "LIMITED",
"registrationNumber": "EzamFj",
"registrationDate": "2010-12-06",
"registeredAddress": {
"line1": "1309 Frami Parkway",
"line2": null,
"city": "East Ressie",
"state": null,
"postalCode": "W1A0AX",
"country": "NL"
},
"tradingAddress": {
"line1": "2531 Morissette Estates",
"line2": null,
"city": "Port Garrick",
"state": null,
"postalCode": "W1A0AX",
"country": "NL"
},
"phone": "+48444542323",
"website": "https://randomwebsit.com/home"
},
"businessPersons": [
{
"person": {
"firstName": "Ricky",
"middleName": null,
"lastName": "Kessler",
"address": {
"line1": "349 Steuber Spring",
"line2": null,
"city": "Paucekchester",
"state": null,
"postalCode": "W1A0AX",
"country": "GB"
},
"email": "[email protected]",
"phone": "+48444542323",
"birthCountry": null,
"nationality": [
"GB",
"US"
],
"dob": "1955-10-17",
"identificationDocument": null
},
"types": [
"DIRECTOR",
"UBO"
],
"ownership": "50.00"
},
{
"person": {
"firstName": "Davon",
"middleName": null,
"lastName": "Lemke",
"address": {
"line1": "7169 Opal Plaza",
"line2": null,
"city": "Bossier City",
"state": null,
"postalCode": "W1A0AX",
"country": "GB"
},
"email": "[email protected]",
"phone": null,
"birthCountry": null,
"nationality": [
"GB",
"US"
],
"dob": "1955-10-17",
"identificationDocument": null
},
"types": [
"UBO"
],
"ownership": "50.00"
},
{
"person": {
"firstName": "Akeem",
"middleName": null,
"lastName": "Schroeder",
"address": {
"line1": "0969 Augusta Glens",
"line2": null,
"city": "New Bill",
"state": null,
"postalCode": "W1A0AX",
"country": "GB"
},
"email": "[email protected]",
"phone": null,
"birthCountry": "GB",
"nationality": [
"GB",
"US"
],
"dob": "1955-10-17",
"identificationDocument": null
},
"types": [
"CONTACT"
],
"ownership": null
}
],
"ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}
{
"id": "eus_ka2yeb7ykbo05np3jv",
"business": {
"id": "biz_xz3l6d7bl8p0myjr5v",
"companyName": "Kling Group",
"tradingName": null,
"type": "LIMITED",
"registrationNumber": "EzamFj",
"registrationDate": "2010-12-06",
"registeredAddress": {
"line1": "1309 Frami Parkway",
"line2": null,
"city": "East Ressie",
"state": null,
"postalCode": "W1A0AX",
"country": "NL"
},
"tradingAddress": {
"line1": "2531 Morissette Estates",
"line2": null,
"city": "Port Garrick",
"state": null,
"postalCode": "W1A0AX",
"country": "NL"
},
"phone": "+48444542323",
"website": "https://randomwebsit.com/home"
},
"businessPersons": [
{
"id": "bps_x83lr41ozkg0dy5va2",
"person": {
"firstName": "Ricky",
"middleName": null,
"lastName": "Kessler",
"address": {
"line1": "349 Steuber Spring",
"line2": null,
"city": "Paucekchester",
"state": null,
"postalCode": "W1A0AX",
"country": "GB"
},
"email": "[email protected]",
"phone": "+48444542323",
"birthCountry": null,
"nationality": [
"GB",
"US"
],
"dob": "1955-10-17",
"identificationDocument": null
},
"businessEndUserId": "eus_ka2yeb7ykbo05np3jv",
"types": [
"DIRECTOR",
"UBO"
],
"ownership": "50.00",
"createdAt": 1731325958874,
"updatedAt": 1731325958874
},
{
"id": "bps_xpn6le155ye1v9jo4g",
"person": {
"firstName": "Davon",
"middleName": null,
"lastName": "Lemke",
"address": {
"line1": "7169 Opal Plaza",
"line2": null,
"city": "Bossier City",
"state": null,
"postalCode": "W1A0AX",
"country": "GB"
},
"email": "[email protected]",
"phone": null,
"birthCountry": null,
"nationality": [
"GB",
"US"
],
"dob": "1955-10-17",
"identificationDocument": null
},
"businessEndUserId": "eus_ka2yeb7ykbo05np3jv",
"types": [
"UBO"
],
"ownership": "50.00",
"createdAt": 1731325958910,
"updatedAt": 1731325958910
},
{
"id": "bps_opkx8g1jld50lz4m3e",
"person": {
"firstName": "Akeem",
"middleName": null,
"lastName": "Schroeder",
"address": {
"line1": "0969 Augusta Glens",
"line2": null,
"city": "New Bill",
"state": null,
"postalCode": "W1A0AX",
"country": "GB"
},
"email": "[email protected]",
"phone": null,
"birthCountry": "GB",
"nationality": [
"GB",
"US"
],
"dob": "1955-10-17",
"identificationDocument": null
},
"businessEndUserId": "eus_ka2yeb7ykbo05np3jv",
"types": [
"CONTACT"
],
"ownership": null,
"createdAt": 1731325958916,
"updatedAt": 1731325958916
}
],
"ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
"tags": [
"PEP"
],
"status": "CREATED",
"riskRating": "LOW",
"annualTurnoverRange": null,
"signupAt": null,
"sector": "CRYPTO",
"createdAt": 1731325958857,
"updatedAt": 1731325958857,
"metadata": null
}
For all End Users that should have access to USD there is additional set of data required.
POST End User for USD request example
More details regarding USD requirements can be found here
curl --request POST \
--url https://sandbox.fiatrepublic.com/api/v1/end-users/individuals \
--header 'Accept: application/json' \
--data
{
"person": {
"address": {
"line1": "4931 Filbert Street",
"city": "Philadelphia",
"state": "Pennsylvania",
"postalCode": "19108",
"country": "US"
},
"birthCountry": "US",
"nationality": ["NO", "US"],
"dob": "1983-11-24",
"firstName": "Theobold",
"lastName": "Watkins",
"email": "[email protected]",
"phone": "+16108449269",
"identificationDocument": {
"type": "PASSPORT",
"number": "123456789"
}
},
"ipAddress": "203.0.113.76"
}
{
"id": "eus_ka2yeb7y8l405np3jv",
"person": {
"firstName": "Theobold",
"middleName": null,
"lastName": "Watkins",
"address": {
"line1": "4931 Filbert Street",
"line2": null,
"city": "Philadelphia",
"state": "Pennsylvania",
"postalCode": "19108",
"country": "US"
},
"email": "[email protected]",
"phone": "+16108449269",
"birthCountry": "US",
"nationality": [
"NO",
"US"
],
"dob": "1983-11-24",
"identificationDocument": {
"number": "123456789",
"type": "PASSPORT"
}
},
"ipAddress": "203.0.113.76",
"linkedCryptoWallets": null,
"tags": [],
"status": "CREATED",
"riskRating": null,
"signupAt": null,
"createdAt": 1726561097440,
"updatedAt": 1726561097440,
"metadata": null
}
Step 3: Create a Virtual Account for the End User
Once your End User has successfully been created, you will be able to create a Virtual Account for this user using the create Virtual Account endpoint.
You will need to provide the ID of the Member Fiat Account (masterFiatAccountId) with which you want to link the End User's Virtual Account.
Virtual Account Currency
The
currencyof the Virtual Account will be inherited from the Master Fiat Account it is created against.
You will also need to specify an endUserId to indicate the End User for who you wish to create the Virtual Account. The owner.type field in the response will be END_USER, indicating that the account belongs to an End User (as opposed to a Member).
POST Virtual Account request example
curl --request POST \
--url https://sandbox.fiatrepublic.com/api/v1/virtual-accounts \
--header 'Content-Type: application/json' \
--data '
{
"endUserId": "eus_2pjbyge1l2n0d9z8kl",
"masterFiatAccountId": "fac_exz3l6d7bmn1myjr5v",
"label": "John Smith GBP Account"
}
{
"id":"vac_5opkx8g1jo50lz4m3e",
"masterFiatAccountId":"fac_exz3l6d7bmn1myjr5v",
"status":"ACTIVE",
"currency":"GBP",
"owner":{
"type":"END_USER",
"id":"eus_2pjbyge1l2n0d9z8kl"
},
"businessId":"biz_emv4j231821oaz56yx",
"label":"John Smith GBP Account",
"bankDetails":null,
"createdAt":1654177698929,
"updatedAt":1654177700236,
"metadata":null
}
As with the Fiat Account for the Member, the initial status of the account will be CREATED and will update to ACTIVE once bank details have been assigned.
You can confirm this has occurred by consuming the VIRTUAL_ACCOUNT.UPDATED or VIRTUAL_ACCOUNT.STATUS_UPDATED event or calling the Get Virtual Account endpoint.
VIRTUAL_ACCOUNT.UPDATED event example
{
"id":"evt_4r6j0azvyjr9fgts567g85bd1x2",
"event":"VIRTUAL_ACCOUNT.UPDATED",
"data":{
"id":"vac_5opkx8g1jo50lz4m3e",
"masterFiatAccountId":"fac_exz3l6d7bmn1myjr5v",
"status":"ACTIVE",
"currency":"GBP",
"owner":{
"type":"END_USER",
"id":"eus_2pjbyge1l2n0d9z8kl"
},
"businessId":"biz_emv4j231821oaz56yx",
"label":"John Smith GBP Account",
"bankDetails":{
"bankName":"Fiat Republic",
"accountHolderName":"John Smith",
"country":"GB",
"accountNumber":"12345678",
"routingCodes":[
{
"value":"000000",
"type":"SORT_CODE"
}
]
},
"createdAt":1654177698929,
"updatedAt":1654177700236,
"metadata":null
},
"previousValues":{
"id":"vac_5opkx8g1jo50lz4m3e",
"status":"CREATED",
"bankDetails":null
},
"createdAt":1649852906500
}
Virtual Account Mapping
You should map your Virtual Accounts to their respective customers on your system e.g. using the Virtual Account's
id. This will allow you to easily identify payins to this account and allocate them to the required customers on your side.
Step 4: GET Virtual Account bank details
Once you have a created Virtual Account for your End User, you will want to display the bank details of this account to the user so they want to make a fiat deposit. You can do this by calling the GET Virtual Account endpoint or by retrieving them directly from the webhook.
GET Virtual Account request example
curl --request GET \
--url https://sandbox.fiatrepublic.com/api/v1/virtual-accounts/vac_5opkx8g1jo50lz4m3e \
--header 'Accept: application/json' \
{
"id":"vac_5opkx8g1jo50lz4m3e",
"masterFiatAccountId":"fac_exz3l6d7bmn1myjr5v",
"status":"ACTIVE",
"currency":"GBP",
"owner":{
"type":"END_USER",
"id":"eus_2pjbyge1l2n0d9z8kl"
},
"businessId":"biz_emv4j231821oaz56yx",
"label":"John Smith GBP Account",
"bankDetails":{
"bankName":"Fiat Republic",
"accountHolderName":"John Smith",
"country":"GB",
"accountNumber":"12345678",
"routingCodes":[
{
"value":"000000",
"type":"SORT_CODE"
}
]
},
"createdAt":1654177698929,
"updatedAt":1654177700236,
"metadata":null
}
Updated about 1 month ago