User operations

Contents

Introduction
Operations
KYC transitions

Introduction

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.

Operations

Create a user

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:

HTTP Request

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”
}

Request body parameters

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
email	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:

HTTP Response parameters

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`
email	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

Update a user

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.

HTTP Request

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.

Update phone number

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.

HTTP Request

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”
}

Delete user

To delete a user you can make the following requests using the id of the user.

HTTP Request

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”
}

Get user info

To get the information of a natural or juridical user you can make the following requests using the id of the user.

HTTP Request

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”
}

Where:

HTTP Response parameters

Parameter	Datatype	Description
id	UUID	User id
email	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

Get user compliance info

To get all the compliance information of a natural user you can make the following requests using the id of the user.

HTTP Request

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”
}

Where:

HTTP Response parameters

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

HOME ADDRESS object

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.

IDENTITY object

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.

Get user list

If you want to get the list of all the users in your system, you can make the following requests:

HTTP Request

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

KYC transitions

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 0

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.

Phone number verification

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:

HTTP Request

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”
}

Where:

HTTP Response parameters

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.

HTTP Request

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”
}

Where:

Request body parameters

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:

HTTP Response parameters

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.

Fictional phone numbers for PRE environment

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

KYC level 1

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.

Pass identity data

To pass the identity data, you have to use the following request:

HTTP 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”
}

Where:

Request body parameters

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”
}

Where:

HTTP Response parameters

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.

Identity verification

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.

HTTP Request

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

Where:

Request body parameters

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

Where:

HTTP Response parameters

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.

Fictional ID verification for PRE environment

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.

HTTP Request

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”
}

Where:

Request body parameters

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”
    }
  }
}

Get identity data

You can also check the status of the id verification by retrieving its information.

HTTP Request

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).

Download identity file

Once verified, you can download the identity file. To do so, you have to do the following request:

HTTP 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”
}

Where:

HTTP Response parameters

Parameter	Datatype	Description
file	File	Identity file
name	String	Identity document name

KYC level 2

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:

Home address

The home address is formed by several fields that have to be passed using the following request:

HTTP 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”
}

Where:

Request body parameters

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”
}

Where:

HTTP Response parameters

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.

Occupation

Users have to add their occupation code, based on the the following list of the goverment of Spain: Occupation codes.

HTTP Request

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”,
}

Where:

Request body parameters

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”
}

Where:

HTTP Response parameters

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.

Income level

Possible levels are A, B, C or D.

HTTP Request

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”
}

Where:

Request body parameters

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”
}

Where:

HTTP Response parameters

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.

External bank account

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).

HTTP Request

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”,
}

Where:

Request body parameters

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”
}

Where:

HTTP Response parameters

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:

HTTP 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”.

Where:

Request body parameters

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”
}

Where:

HTTP Response parameters

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.

Get external bank account data

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.

HTTP Request

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”
}

Where:

HTTP Response parameters

Parameter	Datatype	Description
id	UUID	Iban document internal id
externalIban	String	Iban number
status	String	Iban document status

Download external bank account file

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:

HTTP 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}”
}

Where:

HTTP Response parameters

Parameter	Datatype	Description
file	File	Iban file
name	String	Iban file name

KYC level 3

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:

KYC document

To download and see the KYC document the client has to do the following request:

HTTP 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”
}

Where:

HTTP Response parameters

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:

HTTP 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”
}

Where:

HTTP Response parameters

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:

HTTP Request

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”
}

Where:

Request body parameters

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”
}

Where:

HTTP Response parameters

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

Income tax

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:

HTTP 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”.

Where:

Request body parameters

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”
}

Where:

HTTP Response parameters

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.

Get income tax data

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.

HTTP Request

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”
}

Where:

HTTP Response parameters

Parameter	Datatype	Description
id	UUID	Income tax document id
status	String	Income tax document status

Download income tax file

To download the income tax file of a natural or juridical user you have to do the following request:

HTTP 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}”
}

Where:

HTTP Response parameters

Parameter	Datatype	Description
file	File	Income tax file
name	String	Income tax file name