Widget-less Credentials creation

Site structure

The sites from which Syncfy can obtain information are organized as follows:

For an Organization its nature is always specified (Type of Organization), and each Organization groups one or more sites, for example:

Organization BBVA Bancomer
Type of Organization Bank
Sites
  • BBVA Bancomer Personal
  • BBVA Bancomer Empresas
  • BBVA Bancomer NetCash
  • BBVA Bancomer NetCash Llave Inteligente|

The endpoints are listed below so that the user can obtain the different catalogs linked to the sites, the catalogs are constantly updated. You need to add a session token (? Token = TOKEN) or the api key (? Api_key = API_KEY) in the URL.

Organization Object

Field Type Description
id_site_organization String Organization ID. It will be found on the sites it groups together.
id_site_organization_type String Organization type ID.
id_country String ID of the country where the organization belongs.
name String Organization name’s
avatar String Organization Avatar
small_cover String Small Cover of the Organization
cover String Organization Cover
Both Avatar, as Small Cover and Cover of the organization contain a string that will help to obtain the images of the site to be able to show them to the user, it is only necessary to concatenate it to the base https://s.syncfy.com

Site Object

Field Type Description
id_site String Site ID.
id_site_organization String ID of the Organization to which it belongs.
id_site_organization_type String ID of the type of the Organization to which it belongs.
is_business Lógico Flag that indicates if the site supports Business connections
is_personal Lógico Flag that indicates if the site supports Personal connections
name String Name of the site
credentials Arreglo Arrangement of objects that describe each of the elements to send in the creation of the credentials. The object is described below in the Authentication Element table.

Authentication Element

Element that will be part of the request to create the credential.

Field Type Description
name String Element name
type String Element type, can be: text, password or select. If any site requires it, another type will be added.
label String Label that appears in the site portal, it must be displayed to the user to make sense of the value that must be sent.
required Booleano Flag that indicates if the element is required
username Booleano Flag that indicates if the element is username.
token Booleano Flag that indicates if the element expects a token from the user.
validation String OPTIONAL. Expression given by the site to validate user input before launching the connection.
options Arreglo OPTIONAL, for elements of type select, an array of objects with the following structure is specified: { "label": "ETIQUETA", "value": "01" }
The developer must build a with the options delivered by the element so that the user can indicate a valid option.

Petition to build credentials

It is recommended to make a request in the following way:

curl "https://api.syncfy.com/v1/credentials" \
-d 'PARAMS \
-H "Authorization: TOKEN token=TOKEN" \
-H "Content-Type: application/json" \
-X POST

Note: Adapt the request according to your development environment.

The REQUEST PARAMETERS is an object, it includes the ID of the Site to which the credentials will be connected, as well as an object that defines each of the authentication elements with the values ​​provided by the user. Example:

Examples of Parameters for Credential Creation

Banorte Personal Site Credentials id_site : 56cf5728784806f72b8b456e:
[
      {
         “name”:“username”,
         “type”: “text”,
         “label”: “Tarjeta”,
         “required”: true,
         “username”: true,
         “token”: false,
         “validation”: null
       },
       {
         “password” : “12345678”,
         “name”:“password”,
         “type”: “password”,
         “label”: “Contraseña”,
         “required”: true,
         “username”: false,
         “token”: false,
         “validation”: null
       }
]

Authentication elements:
{
       “id_site”: “56cf5728784806f72b8b456e”,
       “credentials”: {
                     “username” : “Usuario123”,
                     “password” : “12345678”,
       }
}

The name of the keys of the credentials object is defined by the name property of the authentication element. The type is used for the input format, for example for the type password an input is recommended that obfuscates user input. The label is the legend that will be shown to the user.

Creating a credential with the POST /credentials request generates a connection to the site. The data for connection monitoring is delivered in the request response

HTTP POST / credentials response

Field Type Description
id_credential String ID of the created credential
username String Obfuscated username
ws String Websocket address to monitor credential status in real time
status String URL to monitor the status of the credential using an HTTP GET request
twofa String URL to send the value of the TWO-FAs requested by the connection. For sending it will build an HTTP POST request
{
    "id_credential": "5c65e723228fe75bdd120435”,
    "username": "t**t",
    "ws": "wss://api.syncfy.com/v1/status/5c66f159228fe753ab7c9e2e",
    "status": "https://api.syncfy.com/v1/jobs/5c66f159228fe753ab7c9e2e/status",
    "twofa": "https://api.syncfy.com/v1/jobs/5c66f159228fe753ab7c9e2e/twofa"
}

Connection status monitoring

The following table describes the coded steps that a connection can take.

Code Name Description
Job information
100 Register The API registers a new process (through a REST request)
101 Starting The process information was obtained to start operating
102 Running The process is running (login successful)
103 TokenReceived The process received the token
Success connection
200 Finish The connection has been successful. Data has been extracted
201 Pending The connection has been successful. We have partially extracted information but data will still be extracted in background processes.
202 NoTransactions The connection has been successful. However, no transactions were found.
203 PartialTransactions The connection has been successful. However, more than one account does not have transactions.
204 Incomplete The connection has been successful. However, the data downloaded is incompleted.
206 NoAccounts The connection has been successful. However, there were no accounts linked to the given credentials.
User errors
401 Unauthorized The value of one of the given Authentication Fields was not accepted by the institution. Please verify the information and try again.
403 Invalidtoken The given token value introduced was not accepted by the institution or the expiration time was reached.
405 Locked The account is locked
406 Conflict The institution does not allow to have more than one user logged in.
408 UserAction User intervention is required on the site
409 WrongSite The process managed to identify that the credentials belong to a different site within the same Organization
User interaction required
410 WaitingTwofa The process is waiting for TWO-FA from the user.
411 TwofaTimeout Time exceeded by the user to enter TWO-FA
Errors
500 Error Bank requires attention (Sync error)
501 Unavailable The third party site is temporarily out of service.
504 ScriptTimeout Sync timeout
509 UndergoingMaintenance The site is under maintenance by Sync

Through the HTTP GET /status request it is possible to obtain the flow by credential

curl "https://api.syncfy.com/v1/jobs/5c66f159228fe753ab7c9e2e/status"\
-H "Authorization: TOKEN token=TOKEN" \
-H "Content-Type: application/json" \
-H "X-Http-Method-Override: GET" \
-X POST

Sample response:

[
    {
        "code": 100
    },
    {
        "code": 101
    },
    {
        "code": 410,
        "address": "https://api.syncfy.com/v1/jobs/5c66f159228fe753ab7c9e2e/twofa",
        "twofa": [
             {
                 "name": "token",
                 "type": "text",
                 "label": "Enter any number sequence as a token"
             }
        ]
    },
    {
        "code": 103
    },
    {
        "code": 102
    },
    {
        "code": 200
    }
]

Below are the most common flows of a connection:

Flow of a connection that does not require TWO-FA

Flow of a connection that requires TWO-FA

Flow of a connection that has an error with user data

Two-factor Authentication Management

The developer should be monitoring each of the changes in the /status response array and process the code, send a message to the user as the case may be. When the code is 410, it must ask the user for the second step of authentication, the details are provided in the same status response. The stage with code 410 has an object similar to the following:

{
    "code": 410,
    "address": "https://api.syncfy.com/v1/jobs/5c66f159228fe753ab7c9e2e/twofa",
    "twofa": [
        {
            "name": "token",
            "type": "text",
            "label": "Enter any number sequence as a token"
        }
    ]
}

Status

Name Type Description
code Number State code
address String URL where the two-factor value will be sent through an HTTP POST request
twofa Array An array of objects that describe each of the two-factor elements. The field attributes are:
(mandatory) name: This is the name with which the two-factor value will be sent
(mandatory) type: Two-factor type, can be text, password, options. When it is options, an options property is expected.
(mandatory) label : Two-factor site tag
(opcional) imgBase64File : StringBase64 of the image with the captcha or QRCode to be validated by the user.
(optional) imgURL : URL of the image with the captcha or QRCode to be validated by the user when he is public on the site.
(otpional) options : Fix with imgBase64File to display an array of images to the user so that they can select one.

HTTP POST /twofa request to send two-factor

curl "https://api.syncfy.com/v1/jobs/5c66f159228fe753ab7c9e2e/status"\
-d '{"twofa":{"token":"123456"}}' \
-H "Authorization: TOKEN token=TOKEN" \
-H "Content-Type: application/json" \
-X POST

The twofa object parameters must send each of the values ​​that the user provides with the name specified in name.