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.
| Catalogue | Endpoint |
|---|---|
| Types of Organizations | https://api.syncfy.com/v1/catalogues/site_organization_types |
| Countries | https://api.syncfy.com/v1/catalogues/countries |
| Organizations | https://api.syncfy.com/v1/catalogues/site_organizations |
| Sites | https://api.syncfy.com/v1/catalogues/sites |
| Sites grouped by Organizations | https://api.syncfy.com/v1/catalogues/organizations/sites |
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 |
HTTP GET Request to /status
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
}
]
Websocket
It is also possible to set up a websocket to monitor the connection status.
To create the websocket is necessary to use the url provided in the field “ws” in the response of the POST to /v1/credentials.
Via HTTP GET to:
"ws": "wss://api.syncfy.com/v1/status/5c66f159228fe753ab7c9e2e"
The websocket messages are quite similar to the messages in GET to /status, this is the way that our Syncfy Widget works.
Messages:
{"code":100}
{"code":101}
{"code":410,"address":"https:\/\/sync.paybook.com\/v1\/jobs\/648ccd07a5e16209404ee996\/twofa","twofa":[{"name":"token","type":"text","label":"Ingrese 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
Note: It’s important to consider that some sites require more than one two-factor authentication, so it’s necessary to implement logic that supports more than one 410 code.
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.