Step by step guide



This guide will drive you through the end to end functionality that our platform provides as it is depicted in the figure below.


iocash logo

Create a user


The first thing to do to be able to start operating in ioCash platform is to create a user. To do so you have to do the following:

  • Ethereum address creation (optional): For requesting the user creation to ioCash API you can provide an Ethereum address. This Ethereum address wil be linked to the wallet of the user when created. You can either ask the user to provide the Ethereum address or create a new one from scratch for him. When creating it, you should make sure that only the user will have access to its private key. Alternatively, if you are not planning in making calls against our smart contracts, you can leave this field empty when making the request. We will automatically generate an Ethereum address for the user and throw the private key away.
  • Create user API call: You can use two different HTTP requests depending if the user you are creating corresponds to an individual or a company: POST /api/v2/public/users/natural or POST /api/v2/public/users/juridical. If the response is successfull, you will get the “id” of the user that you will need to keep for further steps. See the create user docs for full information about this HTTP request.

Verify user's mobile phone


The user will not be able to operate until he has reached the minimum level of identification (KYC 0). For that, he/she will need to verify the phone number introduced in the creation of user. You have to use the HTTP request POST /api/v1/public/users/{id}/request-otp to request a code that will be sent via sms to the pone number informed in the creation of user. Then you will have to use POST /api/v1/public/users/{id}/validate-otp to validate the code. If the code sent to us is the same as the one that was sent via sms to the user, he/she will pass to status VERIFIED and reach level KYC 0. You can find all details about these requests on the KYC level 0 docs.

If the user needs to change the phone number because the one informed in the creation of user is not correct, you can use the HTTP request PATCH /api/v1/public/users/{id}/mobile-phone. For more information check the update phone number docs.

Wallet creation


Once a user verifies his/her phone number and passes to KYC 0, our system will automatically internally start the creation of a wallet for the user. This wallet will be created with the Ethereum address provided.

When the wallet creation is finished, the user status will change to ACTIVATED. At this moment you can retrieve the wallet of the user to get its id (you will need for further operations). To do so, you should call this HTTP Request: GET /api/v1/public/wallets?userId="XXX" where you should include the userId received in the create user request response. On the response you will get all the information about the wallet, including its id. You can check that the status of the wallet is READY and thus the wallet is ready to start making operations. For more information about this HTTP request, refer to the Get wallet info docs.

With the successful creation of the wallet, the user onboarding is finished and he/she is now ready to start operating. Alternatively, if your application requires it, the user can be upgraded to higher KYC levels to increase its limits of operation. Refer to the KYC transitions doc for full information about how to transition to higher KYC levels.

You can also create extra wallets for the user if you need it. For that, refer to create extra wallet doc.



Once you have an activated user with an operative wallet, the first operation you have to do is to fund it. There are two ways of doing so in ioCash: using a credit/debit card or a bank transfer.

Card cash-in


In order to fund money into the wallet with a credit/debit card, the user needs to enter the data of the card. You need introducing it in a specific form generated per each request. You can generate a new form in order to start a cash-in process using this HTTP Request: POST /api/v1/public/wallets/{walletId}/cards/cashIns.

As required in request you need a `successUrl` (where form will redirect after success) and a `rejectUrl` (where form will redirect after error)

As a response you will get a paymentUrl in which introduce card data. After introduce data, it will redirect to successUrl/rejectUrl but the balance will not be available yet. Please note that, after 15 minutes, if you have not submitted the form, the card cash-in movement will expire.

Because cash-in is asynchronous, after a few seconds, the balance and available balance of the wallet will be increased with the cashed-in amount. For more information about the process, refer to the card cash-in docs.

SEPA cash-in


The wallet of a user can also be funded via SEPA cash-in i.e. a bank account transfer. The user will just order a transfer from an external bank account to the IBAN associated with the wallet. Once the money reaches the account, the movement is validated by the electronic money entity and the balance and available balance of the wallet are increased with cashed-in amount.

For this operation, you do not need to make any interaction with the API. For more information about this step go to the SEPA cash-in docs.

Transfer


Once the wallet of the user has funds, you can start transferring money to other ioCash wallets. For that, you will of course need at least two wallets.

Transfers can be triggered from the API or directly by calling the smart contract.

To know more about transfer operations please refer to the transfer docs.

Cash-out


To finish the cycle and test of the end-to-end functionality, you can do a cash-out. With a cash-out you can transfer money from the io-cash wallet to an external bank account. The HTTP request you have to call is: POST /api/v1/public/wallets/{walletId}/cashOuts with the parameter of the sender’s wallet ID. In the request you have to include the quantity and external IBAN number to which the money is to be sent. To know more about this operation you can check the cash-out docs.

Once the operation is executed, the balance of the sender’s wallet will be diminished by the cashed-out amount.


Other operations


Apart from the main end to end functionality described with the previous steps, you can at any moment check the information of the wallet of the users by calling the request: GET /api/v1/public/wallets?userId="XXX". Check full functionality in get wallet info docs.

Additionally, you can also check the movements that a wallet has performed by using GET /api/v1/public/wallets/{walletId}/movements. Please check get movements list docs for it.