User operations




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.


kyc-levels

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.

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