Contents
Once you are registered as a client in ioCash, you can start creating accounts for your users so that they can start using the service.
The first interaction you have to do with the API is to create a user. There are two types of users you can create: individual persons (natural users) and companies (juridical users). The API requests you need to do are:
POST /api/v2/public/users/natural
POST /api/v2/public/users/juridical
With the following information provided as JSON for natural users:
{
“userName”: “johndoe”,
“firstName”: “John”,
“lastName”: “Doe”,
“email”: “johndoe@example.com”,
“mobilePhone”: “+34612345678”,
“dltAddress”: “0xSUF9AS84DS4ADVFFSDDDSSA92SFA0AxAFDS9DD4FAF”,
“dltNetwork”: “AlastriaTelsius”
}
and the following for juridical users:
{
“userName”: “CompanyA”,
“companyName”: “CompanyA”,
“email”: “companya@example.com”,
“mobilePhone”: “+34612345678”,
“dltAddress”: “0xSUF9AS84DS4ADVFFSDDDSSA92SFA0AxAFDS9DD4FAF”,
“dltNetwork”: “AlastriaTelsius”
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
userName | yes | string | A freely chosen identification for the user |
firstName | yes | string | The first name of the user. Only for Natural person |
lastName | yes | string | The last name of the user. Only for Natural person |
companyName | yes | string | The last name of the user. Only for Juridical person |
no | string | The email address of the user | |
mobilePhone | yes | string | A Spanish mobile phone number |
dltAddress | no | string | This Ethereum address will be used for the automatically created wallet for the user. You can either use an already existing address, if the user provides it, or create a new one for him/her. Alternatively, this field can be left empty if your use case does not need to directly operate against the DLT and will only use the APIs. * |
dltNetwork | no | string | The Ethereum network in which the user is created. Has to be one of the associated networks of the client. When not provided the client default network is used. |
* Note: If the dlt address is left empty we will automatically create one for storage purposes. If in the future you change your mind and want to change this configuration, we can allow the change of dlt address to new ones, controlled by you users, so that they can directly operate against the DLT.
As response, you will get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v1/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“companyName”: “null”
“email”: “johndoe@example.com”,
“firstName”: “John”,
“lastName”: “Doe”,
“mobilePhone”: “+34612345678”,
“status”: “PENDING”,
“userName”: “johndoe”
}
Where:
Parameter | Datatype | Description |
---|---|---|
id | string | The UUID of the created user. You will need it for future requests |
companyName | string | The company name of the user created. If it is a natural user it appears as null |
string | The value which was provided in the request | |
firstName | string | The value which was provided in the request. If it is a juridical user it appears as null |
lastName | string | The value which was provided in the request. If it is a juridical user it appears as null |
mobilePhone | string | The value which was provided in the request |
status | string | The status can be either PENDING_VERIFICATION , PENDING_NEW_VERIFICATION , VERIFIED , ACTIVATED or UNSUBSCRIBED . |
userName | string | The value which was provided in the request |
From this JSON it is important that you save the id of the user, in the above example: 91af1cb8-1caa-47d0-8ef8-2c11948baaba
. You will need the user ID for future requests.
When you create the new user, after its phone number is verified, an IoCash wallet will be automatically generated with the provided DLT address. To retrieve this generated wallet data, please refer to Get wallet
In order to update basic info of the users like first name, last name and/or username you have to call the following requests depending if the user to be updated is natural or juridical.
PATCH /api/v2/public/users/natural/{userId}
PATCH /api/v2/public/users/juridical/{userId}
In our example, the whole request will be PATCH /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/natural
With the following information provided as JSON:
{
“firstName”: “newFirstName”,
“lastName”: “newLastName”,
“userName”: “newUserName”
}
If you only want to update one of the fields you only have to send this one in the request.
You can always change the phone number of a user by calling the endpoint shown below. If your user has not yet verified a phone number before, so he is in status PENDING_VERIFICATION
, you don´t need any further operation. If your user already had a verified phne number, you will need to pass the verification process again for the new one. Until the new phone number is verified the user’s kyc level will be -1 and in status PENDING_NEW_VERIFICATION
and will not be able to operate. Then the kyc level will be the updated to the same one that the user had with the old phone number and his status will return to ACTIVATED
.
PATCH /api/v2/public/users/natural/{userId}/mobile-phone
PATCH /api/v2/public/users/juridical/{userId}/mobile-phone
In our example, the whole request will be PATCH /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/mobile-phone
With the following information provided as JSON:
{
“mobilePhone”: “newMobilePhone”
}
To delete a user you can make the following requests using the id of the user.
DELETE /api/v2/public/users/{userId}
In our example, the whole request would be DELETE /api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba”
}
},
“email”: “johndoe@example.com”,
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“mobilePhone”: “+34612345678”,
“status”: “UNSUBSCRIBED”,
“userName”: “johndoe”
}
To get the information of a natural or juridical user you can make the following requests using the id of the user.
GET /api/v2/public/users/natural/{userId}
GET /api/v2/public/users/juridical/{userId}
In our example, the whole request would be GET /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba”
},
“compliance”: {
“href”: “/api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/compliance”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“email”: “johndoe@example.com”,
“firstName”: “John”,
“lastName”: “Doe”,
“mobilePhone”: “+34612345678”,
“status”: “ACTIVATED”,
“userName”: “johndoe”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | User id |
string | User email | |
firstName | string | User first name |
lastName | string | User last name |
mobilePhone | string | User mobile phone |
status | string | User status can be either PENDING_VERIFICATION , VERIFIED , ACTIVATED or UNSUBSCRIBED . |
userName | string | User username |
To get all the compliance information of a natural user you can make the following requests using the id of the user.
GET /api/v2/public/users/natural/{userId}/compliance
In our example, the whole request would be GET /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/compliance
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/compliance”
},
“external-iban”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/external-iban”
},
“external-iban-file”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/external-iban-file”
},
“kyc-file”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/kyc-file”
},
“income-tax”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/income-tax”
},
“income-tax-file”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/income-tax-file”
},
“identity”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/identity”
},
“identity-file-front”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/identity-file?side=front”
},
“identity-file-back”: {
“href”: “/api/v2/public/users/natural/94ab12a8-3c85-4a48-81fd-53ace452e2b5/identity-file?side=back”
}
},
“externalIban”: “ES8720809529708295591647”,
“firstName”: “firstName”,
“homeAddress”: {
“countryCode”: “ES”,
“province”: “Madrid”,
“city”: “Madrid”,
“address”: “Calle Pez”,
“postalCode”: “28080”
},
“identity”: {
“nationality”: “ES”,
“identityType”: “DNI”,
“identityNumber”: “98665605K”,
“birthDate”: “2019-01-01”
},
“incomeLevel”: “A”,
“kycLevel”: 0,
“kycStatus”: “ASSIGNED”
“lastName”: “lastName”,
“mobilePhone”: “+608465555”,
“occupationCode”: “0011”
}
Parameter | Datatype | Description |
---|---|---|
externalIban | string | User external iban |
firstName | string | User first name |
homeAddress | object | HOME ADDRESS object |
idenitty | object | IDENTITY object |
incomeLevel | string | User income level |
kycLevel | integer | User kyc level |
kycStatus | string | User kyc status. can be either NOT_DEFINED , PENDING , PENDING_DLT or ASSIGNED . |
lastName | string | User last name |
mobilePhone | string | User mobile phone |
occupationCode | string | User occupation code |
Parameter | Datatype | Description |
---|---|---|
countryCode | string | Two-letter country code based on ISO 3166. |
province | string | Home address country province. |
city | string | Home address city. |
address | string | Home address. Can include street, number and so on. |
postalCode | string | Home address postal code. |
Parameter | Datatype | Description |
---|---|---|
nationality | string | Two-letter country code based on ISO 3166. |
identityType | string | Can be DNI or PAS for passport. |
identityNumber | string | Identity card or passport number. |
birthDate | date | ISO 8601 date without time. |
If you want to get the list of all the users in your system, you can make the following requests:
GET /api/v2/public/users/
will give you as response a JSON array with the information of the common fields for all the juridical and natural users existing in your system. The response will include for each user a Hateoas link to get the specific information for its type of user.
Additionnally, you can also retrieve all the natural users you by using:
GET /api/v2/public/users/natural
and for getting the juridicals:
GET api/v2/public/users/juridical
.
These three calls can be paged. This is specially usefull when you have to retrieve a big amount of elements.
By default, the size of the page is 20 elements, and you can put a maximum size of 2000 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.
Example:
GET api/v2/public/users?page=0&size=25&sort=createdAt,asc
.
If you want to try any of these functionalities yourself and learn more about them, please go to the API catalogue
In order to operate in ioCash, users have to be KYCed - pass identity verification processes. Following what is stipulated in the Electronic Money License, there are different levels of KYC that define the operation limits users have. The operation limits for each level of KYC are shown in the tablebelow.
Both natural and juridical users can use the HTTP requests to reach KYC 0. However all the other HTTP requests described below for the rest of KYC levels (1, 2 and 3) are specific for natural users. For transitioning juridical users to higher KYC levels we follow a manual process. Please contact our support team to to be guided through this process.
KYC level is the minimum level that a user needs to be able to operate in the platform. In order to reach KYC level 0, users have to verify their telephone number.
In order to do so they have to do two calls to our API: one requesting a One Time Password (OTP) and another one verifying it. When the first request is made, the OTP code has an expiration time of 10 minutes, after that time the code is not valid and the first request has to be made again.
To request the OTP:
POST /api/v1/public/users/{userId}/request-otp
In our example, the whole request would be POST /api/v1/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/request-otp
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v1/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/validate-otp”
}
},
“expirationTime”: “2019-07-31T10:36:02.499Z”,
“status”: “PEN”,
“type”: “T”,
“verificationId”: “4bFaa68nSGi9pRTogcZE”
}
Parameter | Datatype | Description |
---|---|---|
expirationTime | date | Date when the code will be expired |
status | string | Status of the code. It can be PEN for pending, VER for verified, CAD for expired or ERR for error. |
type | string | Type of the verification code. It can be T for telephone or E for email. In this case it will always take the T value. |
verificationId | string | Internal system id for the code |
Once the request succeeds, an sms will be directly sent to the user with the OTP. The user will have to send us back this OTP using the following request to verify that he/she is in possession of his/her mobile phone.
POST /api/v1/public/users/{userId}/validate-otp
In our example, the whole request would be POST /api/v1/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/validate-otp
With the following information provided as JSON:
{
“otp”: “1111”
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
otp | Yes | string | Code sent to the user via sms. |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v1/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba”
}
},
“expirationTime”: “2019-07-31T10:36:02.499Z”,
“status”: “VER”,
“type”: “T”,
“verificationId”: “4bFaa68nSGi9pRTogcZE”
“verificationTime”: “2019-07-31T10:36:02.575Z”
}
Where:
Parameter | Datatype | Description |
---|---|---|
expirationTime | date | Date when the code will be expired |
status | string | Status of the code. It can be PEN for pending, VER for verified, CAD for expired or ERR for error. |
type | string | Type of the verification code. It can be T for telephone or E for email. In this case it will always take the T value. |
verificationId | string | Internal system id for the code |
verificationTime | Date | Date when the verification was done. |
We have opened the possibility to use fictional phone numbers in PRE environment to allow you to make more and simpler tests as well as the possibility to create automatic tests. Every phone number that has the prefix +690 and has a valid format will be automatically verified with the code “99999”.
Numbers with prefix +690 usually have the following format: “+690 3xxxxxx”. Take into account that repeated numbers that already exist in the system will result in error. Some examples are: +6903720832 or +6903201921
To reach KYC level 1, users have to verify their identity. They have to first provide some data about their identity card and then verify it with a video.
To pass the identity data, you have to use the following request:
POST /api/v2/public/users/natural/{userId}/identity
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/identity
With the following information provided as JSON:
{
“nationality”: “ES”,
“identityType”: “DNI”,
“identityNumber”: “92659479T”,
“birthDate”: “13-08-1985”
“issueDate”: “12-08-2010”,
“expiryDate”: “13-08-2020”
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
nationality | Yes | string | Two-letter country code based on ISO 3166. |
identityType | Yes | string | Can be DNI or PAS for passport. |
identityNumber | Yes | string | Identity card or passport number. |
birthDate | No | date | ISO 8601 date without time. |
issueDate | No | date | Identity card or passport issue date. ISO 8601 date without time. |
expiryDate | No | date | Identity card or passport expiry date. ISO 8601 date without time. |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/identity”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“nationality”: “ES”,
“identityType”: “DNI”,
“identityNumber”: “92659479T”,
“birthDate”: “13-08-2021”
“issueDate”: “12-08-2010”,
“expiryDate”: “13-08-2021”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | User id. |
nationality | string | User identity nationalty. |
identityType | string | User identity type. |
identityNumber | string | User identity number. |
birthDate | date | User birth date. |
issueDate | date | User identity card or passport issue date. |
expiryDate | date | User identity card or passport expiry date. |
PUT method can be used to update the information once it is filled for the first time.
Next step is to verify the identity with a video verification process. To do so you have to do the following request to to obtain the url that will direct them to the video process.
POST /api/v2/public/users/natural/{userId}/verify-identity
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/verify-identity
With the following information provided as JSON:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e”
}
},
“successUrl”: “https://io.cash",
“failureUrl”: “https://io.cash"
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
successUrl | No | string | Callback url if the verification goes success |
failureUrl | No | string | Callback url if the verification goes wrong |
And as response, we would get the following JSON object:
{
“url”: “https://identificacion.zonadeprueba.es?token=sfVMSgLPASauZQvoQ7NAxvDjXwbd3X1nwMVm32QLV7znMZWziCrp2KYHwfooUHQV9Y1wAbN9so3KGb5fLM2fz2nNmCpKRgRwek7b3WV6FcJb&lang=es"
}
Parameter | Datatype | Description |
---|---|---|
url | string | Url to perform the identity verification process via video. |
Once the video process is completed, if the introduced user identity data matches the identity card or passport data captured with the video, the user will be directly transited to KYC level 1. The transition of KYC level can take up to 1 minute.
We have opened the possibility to fictionally verify IDs in PRE environment to allow you to make more and simpler tests as well as the possibility to create automatic tests. This will allow you to climb to KYC 1 without the need of having a real ID card or passport. To do so, first you have to pass the data of an invented ID card or passport (have in mind that the ID number has to be a valid one). Then, you have to call a new endpoint that we have created to fake the validation. This endpoint only works in PRE.
POST /api/v2/public/users/natural/{userId}/simulate-identity-verification
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/simulate-identity-verification
With the following information provided as JSON:
{
“issueDate”: “2010-12-08”,
“expiryDate”: “2020-13-08”
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
issueDate | Yes | date | Identity card or passport issue date. ISO 8601 date without time. |
expiryDate | Yes | date | Identity card or passport expiry date. ISO 8601 date without time. |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/identity”
},
“user”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e”
}
}
}
You can also check the status of the id verification by retrieving its information.
GET /api/v2/public/users/natural/{userId}/identity
In our example, the whole request would be GET /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/identity
If as response you get that the status of the ID is in VERIFIED
, it means that the verification process has been successful. Otherwise, you can do two things: either continue calling our API doing polling, or you can subscribe to the KycLevelSetToUser
event of our smart contract that it is emitted when the user changes KYC level. If after 5 minutes, the status of the ID has not changed or the event has not been released, it means that there was a problem on the verification process and the user has to repeat it again.
In addition, when the identity of the user is verified by one of our expert verificators, the user will pass to level KYC 2, if all the rest of the information is completed (see next subsection).
Once verified, you can download the identity file. To do so, you have to do the following request:
GET /api/v2/public/users/natural/{userId}/identity-file/?side
The request parameter side
can be front or back to get the corresponding image of the ID.
In our example, the whole request would be GET /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/identity-file/?side=front
. The document will only be available if the user is in KYC level 1 or higher.
And as response, we would get the file
{
“file”: “{file}”,
“name”: “{userName}-identity-file-{side}.jpg”
}
Parameter | Datatype | Description |
---|---|---|
file | File | Identity file |
name | String | Identity document name |
In order to reach KYC level 2, apart of having the idenitity video verified by one of our experts verificators, users have to provide us the following information: home address, occupation, income level and external account IBAN bumber and proof file. To do so, we have enabled several API endpoints:
The home address is formed by several fields that have to be passed using the following request:
POST /api/v2/public/users/natural/{userId}/home-address
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/home-address
With the following information provided as JSON:
{
“countryCode”: “ES”,
“province”: “Madrid”,
“city”: “Pozuelo de Alarcón”,
“address”: “Parque Científico y Tecnológico UPM Campus de Montegancedo s/n”,
“postalCode”: “28223”
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
countryCode | Yes | string | Two-letter country code based on ISO 3166. |
province | Yes | string | Home address country province. |
city | Yes | string | Home address city. |
address | Yes | string | Home address. Can include street, number and so on. |
postalCode | Yes | string | Home address postal code. |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/home-address”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“countryCode”: “ES”,
“province”: “Madrid”,
“city”: “Pozuelo de Alarcón”,
“address”: “Parque Científico y Tecnológico UPM Campus de Montegancedo s/n”,
“postalCode”: “28223”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | User id |
countryCode | String | Home address country |
province | String | Home address province |
city | String | Home address city |
address | String | Home address |
postalCode | String | Home address postal code |
PUT method can be used to update the information once it is filled for the first time.
Users have to add their occupation code, based on the the following list of the goverment of Spain: Occupation codes.
POST /api/v2/public/users/natural/{userId}/occupation
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/occupation
With the following information provided as JSON:
{
“occupationCode”: “1211”,
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
occupationCode | Yes | string | Valid occupation code. |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/occupation”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“occupationCode”: “1211”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | User id |
occupationCode | String | User occupation code |
PUT method can be used to update the information once it is filled for the first time.
Possible levels are A, B, C or D.
POST /api/v2/public/users/natural/{userId}/financial-information
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/financial-information
With the following information provided as JSON:
{
“incomeLevel”: “A”
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
incomeLevel | Yes | string | Code of the different income levels ranges: A: less than 100,000 € B: between 100,001 and 600,000 € C: between 600,001 and 1,200,000 € D: above 1,200,000 € |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/financial-information”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“incomeLevel”: “A”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | User id |
incomeLevel | String | User income level |
PUT method can be used to update the information once it is filled for the first time.
To reach KYC 2, users also need to prove that they own an external bank account. For this, 2 API calls are needed, one to provide the bank account IBAN and the other one to upload a document that proves the ownership of the account (e.g. bank recepit).
POST /api/v2/public/users/natural/{userId}/external-iban
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/external-iban
With the following information provided as JSON:
{
“externalIban”: “ES9621001464407281768591”,
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
externalIban | Yes | string | Valid IBAN number. |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/external-iban”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“externalIban”: “ES9621001464407281768591”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | Document id |
externalIban | String | User external account IBAN. |
PUT method can be used to update the information once it is filled for the first time.
For uploading the file that proves that the user owns the bank account with the submitted IBAN you have to do the following request:
POST /api/v2/public/users/natural/{userId}/external-iban-file
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/external-iban-file
The request should be a multipart request with a part called “file”.
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
file | Yes | Multipart request file part | The file should not exceed 50mb size. Supported file formats are png, jpg, jpeg and pdf. |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/external-iban-file”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“fileVersion”: “Jbz2jvozyXXvHrTAm06x2wb0kxVg04Yl”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | User id |
fileVersion | String | File version. |
PUT method can be used to update file once it has been uploaded for the first time.
After all information has been validated, the user KYC level is changed to 2.
To retrieve the information of the external bank account of a natural or juridical user you can make the following request using the id of the user.
GET /api/v2/public/users/{userId}/external-iban
In our example, the whole request would be GET /api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/external-iban
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/external-iban”
},
“external-iban-file”: {
“href”: “/api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/external-iban-file”
}
},
“documentId”: “a0df712d-5d9e-4084-a76b-8c5acd8760e1”,
“externalIban”: “ES5014651142948144176299”,
“status”: “FILES_PENDING”,
“userId”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“issueDate”: “2019-09-05T09:46:31.750Z”,
“expiryDate”: “2021-02-05T09:46:31.750Z”
“createdAt”: “2020-02-05T09:46:31.750Z”,
“updatedAt”: “2020-02-05T09:46:31.750Z”,
“fileId”: “82af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“fileStatus”: “SUBMITTED”,
“fileVersion”: “cNfGf19R1tX07EPQYYHBcruRMHqsagQ0”,
“fileCreatedAt”: “2020-02-05T09:46:31.750Z”,
“fileUpdatedAt”: “2020-02-05T09:46:31.750Z”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | Iban document internal id |
externalIban | String | Iban number |
status | String | Iban document status |
To download the file that proves the ownership of the external back account of a natural or juridical user you have to do the following request:
GET /api/v2/public/users/{userId}/external-iban-file
In our example, the whole request would be GET /api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/external-iban-file
And as response, we would get the file
{
“file”: “{file}”,
“name”: “{file-name}”
}
Parameter | Datatype | Description |
---|---|---|
file | File | Iban file |
name | String | Iban file name |
In order to reach KYC level 3, users have to send us their last year income tax document, and sign a KYC terms document that is automatically created by our Electronic Money Entity when the user reaches KYC level 2. The KYC document contains a summary of the personal information introduced to reach level 2. With the signature of the document, the user confirms that all this data is correct. For these functionalities we have enabled several API endpoints:
To download and see the KYC document the client has to do the following request:
GET /api/v2/public/users/natural/{userId}/kyc-file
In our example, the whole request would be GET /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/kyc-file
. The document will only be available if the user is in KYC level 2 or higher.
And as response, we would get the file
{
“file”: “{file}”,
“name”: “kyc.pdf”
}
Parameter | Datatype | Description |
---|---|---|
file | File | Kyc file |
name | String | Kyc document name |
To sign the KYC document, the user has to request a signature code that will be sent to her mobile phone via SMS. Then, she will have to send back the code via API to confirm her signature.
To request the signature code use the following request:
POST /api/v2/public/users/natural/{userId}/request-kyc-terms-signature
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/request-kyc-terms-signature
As response, you would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/kyc-file”
}
},
“signatureId”: “ewiWXPgrnq8aZ9sVd4xd”,
“status”: “PENDING”,
“type”: “SMS”
}
Parameter | Datatype | Description |
---|---|---|
signatureId | String | Identification for the signature that will be needed for the confirmation request |
status | String | Signature status |
type | String | Signature type |
To confirm the KYC document signature:
POST /api/v2/public/users/natural/{userId}/sign-kyc-terms
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/sign-kyc-terms
With the following information provided as JSON:
{
“signCode”: “3tM3WD”,
“signatureId”: “ewiWXPgrnq8aZ9sVd4xd”
}
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
signCode | Yes | string | Signature code that the user received via SMS |
signatureId | Yes | string | Must be the same as the signatureId received in the request signature response |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/kyc-file”
}
},
“signatureDate”: “2019-09-05T09:46:31.750Z”,
“signatureId”: “ewiWXPgrnq8aZ9sVd4xd”,
“status”: “SIGNED”,
“type”: “SMS”
}
Parameter | Datatype | Description |
---|---|---|
signatureDate | Date | Document sign date |
signatureId | string | Must be the same as the signatureId received in the request signature response |
status | String | Signature status |
type | String | Signature type |
To reach KYC 3, users also have to provide their last year income tax. For doing so, they will have to upload the file by using the following request:
POST /api/v2/public/users/natural/{userId}/income-tax-file
In our example, the whole request would be POST /api/v2/public/users/natural/91af1cb8-1caa-47d0-8ef8-2c11948baaba/income-tax-file
The request should be a multipart request with a part called “file”.
Parameter | Mandatory | Datatype | Description |
---|---|---|---|
file | Yes | Multipart request file part | The file should not exceed 50mb size. Supported file formats are png, jpg, jpeg and pdf. |
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/natural/da013bce-08da-41b1-843b-af3db683480e/income-tax-file”
}
},
“id”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“fileVersion”: “Jbz2jvozyXXvHrTAm06x2wb0kxVg04Yl”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | User id |
fileVersion | String | File version. |
The PUT
method can be used to update the file after it has been uploaded for a first time.
To get the income tax document information of a natural or juridical user you can make the following requests using the id of the user.
GET /api/v2/public/users/{userId}/income-tax
In our example, the whole request would be GET /api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/income-tax
And as response, we would get the following JSON object:
{
“_links”: {
“self”: {
“href”: “/api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/income-tax”
}
},
“documentId”: “a0df712d-5d9e-4084-a76b-8c5acd8760e1”,
“status”: “FILES_PENDING”,
“userId”: “91af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“issueDate”: “2019-09-05T09:46:31.750Z”,
“expiryDate”: “2021-02-05T09:46:31.750Z”
“createdAt”: “2020-02-05T09:46:31.750Z”,
“updatedAt”: “2020-02-05T09:46:31.750Z”,
“fileId”: “82af1cb8-1caa-47d0-8ef8-2c11948baaba”,
“fileStatus”: “SUBMITTED”,
“fileCreatedAt”: “2020-02-05T09:46:31.750Z”,
“fileUpdatedAt”: “2020-02-05T09:46:31.750Z”
}
Parameter | Datatype | Description |
---|---|---|
id | UUID | Income tax document id |
status | String | Income tax document status |
To download the income tax file of a natural or juridical user you have to do the following request:
GET /api/v2/public/users/{userId}/income-tax-file
In our example, the whole request would be GET /api/v2/public/users/91af1cb8-1caa-47d0-8ef8-2c11948baaba/income-tax-file
And as response, we would get the file
{
“file”: “{file}”,
“name”: “{file-name}”
}
Parameter | Datatype | Description |
---|---|---|
file | File | Income tax file |
name | String | Income tax file name |