Pin Code

We work with pin code at two levels: user and profile. Both work in relatively the same way, the only difference is that one applies to the user level and the other to the user profile level.

info

The PIN code must be a numeric string with a maximum length of 4 characters or null. E.g.: '1234', '4589', '1111', null.

caution

Soon the property name pinCode will not be accepted as a valid property. Please in your requests change the property name for pin.

danger

Examples of invalid pin codes: 'abvs', 'abc', '-201', '#2ab', '111111', 'null', empty string

User Level

For the user level, we have three endpoints:

Update User Pin

The purpose of this is to set a pin code for the user. We accept null as value to unset the pin in the user level, in others words if you have a pin set to the user and wants to unset it, just send null as value. Once you set a pin for the user, you should see a property called isPinSet set to true via the get user. If the pin code is not set to the user, the value will be false.

Validate User Pin

This is to verify that the pin code already set, is the valid and correct pin code. This endpoint can validate both levels of pin code (user level and profile level). To get this you just have to send the property validateType in the request body, setting the value that you want to validate: user or profile. If it is not sent, the user is the default value.

Retrieve Pin Code

The purpose of this endpoint is to retrieve the PIN code that is set, in case a user has forgotten it, by inputting user credentials. It can retrieve both types of pin code (user & profile).

• At the user level, your request must provide a valid Bearer token and the required properties, which in this case is just the password that the user uses to login.

• At the profile level, your request must provide a valid Bearer token, password, pinType property set to profile. The profileId can be provided in order to retrieve a pin for a specific profile.

The profileId is not a mandatory property. If it is not present in the request, we will try to find the profile referring to the Bearer token (mandatory in the request). The precedence will then be: profileId if provided; if not, the profile related to the Bearer token.

caution

• In case of bad credentials, you will get a 401 Unauthorized with error message in the body of the response.

• If you provide a profile id that doesn't exist, you will get a 404 Not Found with error message in the body of the response.

• If you try to retrieve a pin for a user or profile that doesn't have a pin set, you will get a 400 Bad Request with error message in the body of the response.

Profile Level

For better understanding about profiles, check this article.

At the profile level, we don't have specific endpoints defined for pin code. The pin code here is just required when the property isPinRequired is set to true, in this case we will check for the same rules mentioned in the beginning of this article. The only difference is if the property isPinRequired is set to true, we don't accept null as a valid value; because if the pin code is required, you have to set a value for pin. To unset value for pin in profile level, update the profile sending isPinRequired set to false and pin set to null.