Platform basics guide


Contents

Introduction



It's important to highlight that ioCash is a mix of smart contracts and API. Which is the main reason behind having a hybrid platform? Our system enables a new world of possibilities, making fiat money available on the blockchain, being able to natively execute operations. Besides that, cash-in and cash-out operations need to be integrated with nowadays banking and payments systems, which are out of the blockchain space. That`s the main reason behind having a hybrid approach. Having said that, we are working on having a full decentralized approach, being able to launch commands indistinctly at smart contracts or API level, using a mix of decentralization and shared repositories ( coming soon ).

The Concepts



Here is a list of the concepts that you will see listed throughout this guide.

  • Client: A client in our system is a company that has opened an account in ioCash to use our API platform in order to build their own client applications. Most of the functionality in ioCash is managed by client apps, which are the ones that can create users and wallets, make operations, etc.
  • User: A user in ioCash system is an entity that has opened or is in the process of opening an account in the system. There are two types of users: Natural users that correspond to individual persons and Juridical users that identify companies or institutions.
  • Wallet: A wallet is an account opened by a user in the ioCash platform through a client application. Wallets are where the user´s funds reside, and are composed of an electronic money account (with a real banking IBAN that the user can use to transfer funds using SEPA transfers) , a DLT account address that reflects at all times the balance in the banking account, and the ioCash wallet itself, which conciliates and operates the other two. Client apps operate always through the ioCash wallet API, or through direct calls to the DLT. At present, only one wallet per user inside a client app can be created and it is limited to Euros, though in the near future ioCash will allow for multiple wallets and currencies.
  • Movements: Movements are the operations that can be performed with a wallet that affect the funds in it. All movements that take place in ioCash wallet happen always both in the DLT and the bank account.
  • SEPA cash-in: A SEPA cash-in is a transfer from an external bank account into an ioCash´s user bank account (his IBAN address in the system) through a SEPA order in the origin bank. It is the main method used to fund an account.
  • Card cash-in: A card cash-in is a funding operation in which the user uses his external credit or debit card to fund his ioCash account.
  • Transfer: In our system, a transfer is the movement of funds between users that have an ioCash account, so they are both inside the ioCash ecosystem. When a transfer is executed in our system, two movements are generated: movement Transfer Out (funds going out of an account) and movement Transfer In (funds going into an account). They are both related to the same movement ID.
  • Cash-out: A cash-out is a transfer out from an ioCash wallet onto an external bank account. It is done through a SEPA transfer.
  • KYC: “Know Your Customer” (KYC) is a requisite part of the European banking regulation that obliges financial institutions to know the identity of their customers. All users operating in the system have a KYC level which goes from 0 to 4, depending on the amount of identification information they have provided. KYC levels limit the quantity of the operations that users can do with their wallets in an annual, quarterly and by individual operation basis.
  • Limits: Related to the KYC, limits are the annual, quarterly and single operation limits that users have when operating their wallets, according to their KYC level.
  • DLT: “Decentralized Ledger Technology” (DLT), referring mainly to blockchain technology, it is used sometimes in the documentation to refer to the blockchain network on which the client and wallet operate. ioCash is based on ethereum and is network agnostic -in the sense that it can operate on any ethereum network- though due to security considerations, only a limited set of networks is offered for operations at this point.

Client accounts


The first step to being able to operate and build client applications in ioCash, is to have a client account. To create one you have to register and be logged in the platform. Then, you will have to get the Authorization API key to use any ioCash functionality and be able to build your client applications. To get started with an API key, take a look to the getting started docs

When creating a client account, he will choose an Ethereum network, with the help of ioCash experts, that will be the available network on which the wallets belonging to the client account users will operate.

Client accounts can have 3 different status:

  • Active: An active client account can perform all operations (create wallets etc). This means that user wallets belonging to this client account can perform all normal operations (unless individually restricted). This is the usual status of a functioning client account.
  • Deactivated: A deactivated client account cannot perform any operation. This means it cannot create users or wallets, and the wallets belonging to this client cannot perform any operation. This is the usual status for a client account that has recently been created (and is not activated yet) or accounts that have been discontinued.
  • Restricted: A restricted client account can only perform certain types of operations. It cannot create new users or wallets, and wallets under this account cannot perform any cash-in or transfer movements, but they can still do cash-out operations. This status is mainly used for client accounts that are in the process of being deactivated, to give a period to the present users to take their funds out of the system.


Users and wallets


When a client builds his API application, the first thing that he will do is to create user accounts. A user represents an individual person or a company. Users are registered in ioCash through their client and will be able to perform operations in it. A user account counts with the following parameters:

  • id: system identification number of the user account
  • client id: system identification number of the client in which application the user operates
  • User name: A freely chosen name inside the platform
  • First name: First name of the user (Only for natural person user)
  • Last name: Last name of the user (Only for natural person user)
  • Company name: Name of the company (Only for juridical person user)
  • Email: email of contact of the user
  • Phone: contact mobile phone of the user
  • Identification type: type of id document registered in the system. It can be DNI, NIE, NIF, TR or PAS
  • Identification number: number of the identification document
  • Status: The user account can have three different statuses:
    • Pending verification: The user account is in pending verification when the user has been created in our system, but its identity data is still in verification process. A pending user account does not have a wallet to which operate yet.
    • Verifed: The user identity has successfully verified and the system automatically starts the process of creating a wallet with which he/she can operate. A verified user cannot still operate.
    • Active: This status is reached when the wallet is created successfully for the user. An active user account can perform operations with their wallets. This is the normal status of a user since verification and creation of wallet processes are completed in few seconds.

When a user account is created, internally, a wallet is automatically created and associated with that user account. For the time being, this will be the only wallet that the user can own for that client application (in the future multi-wallet accounts functionality will be added). The wallet is where the user’s funds reside and it is composed of an electronic money account (with a real banking IBAN number) and a DLT address that reflects this bank account on the blockchain. Below, all the parameters of a wallet are described:

  • id: system identification number of the wallet
  • User id: id of the user account to which the wallet is associated
  • Client id: id of the client account to which the user and wallet are associated
  • Client alias: alias name of the client for internal easier identification purposes
  • DLT address: blockchain address associated to the wallet.
  • iban: IBAN number associated to the wallet.
  • Status: The wallet of a user can have two different status:
    • Pending: The wallet hasa been created but it is waiting for the creation and association of an IBAN number to it.
    • Ready: The wallet reaches its final status when the IBAN has been successfully created and added. This is the normal status of wallets.
  • Total Balance: This balance represents the funds of the account. Every time an operation is successfully carried out, it will be updated.
  • Available Balance: This balance represents the funds of the wallet on the blockchain, also in Euros and it is the one with which the user can operate. Normally, it will show the same balance amount than the total balance. However, in transfers and cash-out operations, the available balance of the orderer will be immediately changed to the new value and the total balance will be updated once the operation has been confirmed by the EM banking operator. Therefore for a short period of time, the two accounts will not be showing the same number. The available balance assures that the users cannot order a second operation that surpasses their total funds although the first one has not yet been confirmed.
  • Held Balance: It represents the part of the balance that is on hold. On hold means that the balance is still in the wallet, but cannot be used to do a transfer or cash out. A balance is automatically put on hold during the internal process after a transfer or cash out request has been received until the request has been processed.

To fulfill EM license compliance with KYC levels and anti money laundering rules, ioCash reserves the right to restrict user operations permissions. When the user is created and in a normal situation, all permissions of the user will be activated. The operations that can be restricted are:

  • Cash in: if permission denied, the user will not be able to perform card cash-in operations.
  • Cash out: if permission denied, the user will not be able to perform cash-out operations.
  • Transfer in: if permission denied, the user will not be able to receive any money from another ioCash account.
  • Transfer out if permission denied, the user will not be able to send any money to another ioCash account.

Functional flow of creating a user account:

First, a user makes the request via an ioCash signed up client app by providing all the needed information. The user account is created with the status of “Pending-verification”. When the user's identity data has been verified the status changes to "Verfied" and automatically a wallet -on Pending status- with a DLT address is created and associated to the user. At this point, an IBAN number is requested to our EM provider. When the IBAN is created and associated to the account successfully, the status of both Wallet and User changes to "Active" and the user is ready to start operating in the system.



Movements


An ioCash movement is any operation that can be performed with a wallet and affects the funds of it. Every movement in ioCash takes place in both the bank account and the DLT. Movements have the following parameters:

  • id: unique system identifier number for the movement
  • Account origin: Sender’s Wallet id number in a money transfer. In a card cash-in or cash-out, this field will appear empty. In a SEPA cash-in, it will contain the name of the external bank account holder making the transaction.
  • Account target: Receiver’s wallet id number in a money transfer. In a card cash-in, or a SEPA cash-in, this field will appear empty. In a cash-out, it will contain the name of the external bank account holder receiving the fund.
  • Concept: An optional description of the purpose of the movement. It can be up to 140 characters long. If the user does not provide one, the system sets a default one.
  • Amount: Amount of money being moved.
  • Created at: Timestamp (date and time) of the movement
  • DLT address origin: DLT address associated to the sender’s wallet in a money transfer. In a card cash-in, a cash-out or a SEPA cash-in this field will appear empty.
  • DLT address target: DLT address associated to the receiver’s wallet in a money transfer. In a card cash-in, cash-out or SEPA cash-in, this field will appear empty.
  • IBAN: In cash-out and SEPA cash-in, an external account participates in the movement. This field contains the IBAN number of this external account. In card cash-in or transfers this field appears empty
  • Status: A movement can have 3 different status:
    • Pending: When the movement has this status, it means that it has been ordered but it has not yet been confirmed.
    • Success: If the movement reaches this status, it means that it was successfully completed and thus the “total balance” and the DLT “available balance” are the same and equal to the new value..
    • Error: If this status is reached, it means that there was a problem with the operation. This error can be produced by 3 different reasons.
      1. Not enough funds. The DLT “available balance” has not enough funds to perform the requested operation.
      2. Generic error in EM entity. There is an error in the electronic money operator and thus operations are not available at the moment
      3. Compliance error. The operation surpasses the KYC limits or the user is not permitted to realize this operation
  • type: The movement can either be a card cash-in, bank account (SEPA) cash-in, transfer-in, transfer-out or a bank account cash-out. The functional flow of each of these movements are shown below.

It is important to note that if a user that is not permitted to make one of these operations tries to execute it, the movement will not even be created. The operation will be declined by ioCash system before that.


Functional flow of a card cash-in

In a card cash-in, funds are transferred to an ioCash wallet from an external debit or credit card. The process of the operation is as follows:

  1. The operation is triggered by a user, via its client. They make a request of card cash-in including all the information required.
  2. Our system receives and validates the cash-in from the card
  3. A new movement of type “CARD_CASHIN” is generated with status of “pending”.
  4. A mint transaction in the blockchain is created for the DLT address associated to the wallet’s user.
  5. Once the transaction is mined, the DLT “available balance” and the “total balance” of the wallet are updated to the new value
  6. The movement status changes to “success”

Functional flow of a SEPA cash-in

A SEPA cash-in is executed from an external bank account. The issuer of the transaction will write as the target of the transaction an IBAN of an ioCash wallet account. The steps of the operation inside ioCash are the following:

  1. The order of the transfer is received and validated in our system
  2. A movement of type “BANK_ACCOUNT_CASHIN” is created with status of “pending”.
  3. A mint transaction in the blockchain is created for the DLT address associated to the wallet’s user..
  4. Once the transaction is mined, the DLT “available balance” and the “total balance” of the wallet are updated to the new value.
  5. The movement status changes to “success”

Functional flow of a transfer

A transfer is a decentralized transaction of money between two ioCash wallets. When a transfer is requested by a user, due to its decentralized nature, it is directly executed against the DLT (the operation is requested through the DLT, not through the API). If enough funds are available in the user´s available balance (DLT wallet), the transfer process will start taking place. The steps are the following:

  1. A “TRANSFER_OUT” movement with Pending status is created in the sender´s account and the available balance is updated to the new amount (previous amount minus quantity sent). The sending amount will be blocked on the sender's wallet until the EME transaction is confirmed in the banking system.

  2. The Electronic Money Entity proceeds to validate the transaction. There are two possible outcomes:

    1. If the transfer meets all compliance requirements and is within the operation limits of the user, the operation takes place successfully on the EME account. A “TRANSFER_IN” movement in Pending status is then created in the receiver’s account. The system sends the order to the DLT to unhold and complete the transfer to the receiver account. After the transfer transaction is completed on the DLT, the movement status in both sender and receiver are updated to Success, Total Balance is updated in both the sender and receiver and the available balance is updated on the receiver.
    2. If the transfer does not meet all compliance requirements or is outside the user limits, the transaction is rejected by the EME. The system then orders to unhold the amount in the sender wallet and cancel the transfer. The receiver will not see the movement reflected in his account at all. After the transfer transaction is completed on the DLT, the movement status in the sender is updated to “Error”, and the available balance is updated back with the amount that had been held for the operation.

Functional flow of a cash-out

A cash-out is a transfer of money from an ioCash wallet to an external bank account via SEPA transfer. The user has to request the operation via its client, completing all the required information (amount, IBAN of the external account, the name of the owner of the external account). If the user has enough funds in its available balance (DLT wallet), the transfer process will start taking place. The steps are the following:

  1. The available balance of the user’s wallet is updated to the new value and a movement of type “BANK_ACCOUNT_CASHOUT” is created with the status of “pending”. The sending amount will be blocked on the sender's wallet until the EME transaction is confirmed in the banking system.

  2. The Electronic Money Entity proceeds to validate the transaction. There are two possible outcomes:

    1. If the cash-out meets all compliance requirements and is within the operation limits of the user, the operation takes place successfully on the EME account. The system sends the order to the DLT to unhold and complete the cash-out. The wallet total balance changes to the new value, equal to the DLT one (available balance) and the movement status changes to “Success”
    2. If the cash-out does not meet all compliance requirements or is outside the user limits, the transaction is rejected by the EME. The system then orders to unhold the amount in the user’s wallet and cancel the cash-out. The available balance (DLT) is updated back to the before operation value and the total balance never changes from its original quantity. Finally, the movement status is updated to “Error”