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 (i.e. the Crypto platform), 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 baking 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 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.

This request is handled synchronously and a successful request will return an End User object in an ACTIVE status. At this point you can create a Virtual Account for the End User.

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]"
    }
}
{
    "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
}

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 currency of 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 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.

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
}

Did this page help you?