This guide will drive you through the end to end functionality that our platform provides as it is depicted in the figure below.
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:
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.
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.
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.
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.
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.
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.
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.
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.