This checklist aims to assist you in validating that your implementation of the Syncfy Open Data API for connecting to banks and the SAT is comprehensive and aligned with best practices. The goal is to prevent errors in your integration, provide robust technical support, and ensure a superior experience for your end users.
1. User Management
Ensure that user management is correctly implemented in the integration:
Create a user for each entity/user/client.
Have an identifier that allows linking the Syncfy user with the user in your system using the id_external.
Store the “id_user” identifier assigned by Syncfy.
2. Information Storage
Ensure correct information storage:
Have a database to store necessary transactional information.
Store the credential identifier once it has been successfully synchronized for the first time.
Store identifiers assigned by Syncfy.
Avoid overflow errors by assigning sufficient characters for each field to be stored.
3. Use of Webhooks
As best practices, make use of webhooks, considering:
Configure the webhook URL in the Syncfy dashboard to receive webhook events.
Subscribe to the necessary events according to the product used.
Use the credentials.refresh event to consume new and/or updated information.
Note: Different webhook URLs must be configured for both Sandbox and Production.
4. Error Handling
Ensure that the integration can store the error rid presented (this rid helps track the problem more efficiently).
In case the widget isn’t used, ensure displaying a correct message to the user according to the presented error code, considering different status codes: Status Codes.
5. Widget Integration
Integrating the Syncfy widget into the service implementation is highly recommended as it saves time in implementation, updates if any site changes its access types, and is transparent to the user. When using the widget, ensure that the widget configuration is appropriate for your needs:
Lock widget navigation if necessary.
Configure the widget to display only sites from the desired country.
Extend the widget timeout if credentials have a large volume of transactional information.
Use widget methods and events according to the needs in your system.
Enable the widget only for credential updates or creation (Pulls) and not for queries to API endpoints.
Test with Sandbox all possible access types using ACME Bank. This ensures there are no issues in the frontend of your system that prevent the widget from functioning correctly.
If using the setEntrypointCredential method, provide the option for the user to enable the widget to update their access credentials as needed (for Open Banking, it’s common for third-party sites to change passwords).
6. Widget-less Integration
If not using the widget in your implementation, ensure that:
The implementation is adaptable if a site makes a change in its login (new field, credential name change, integration of twofa).
Detect and handle each state the credential can be in during synchronization ( Status Codes ).
The process can receive more than one code 410 and, therefore, can send more than 1 twofa if the site requires it.
Be aware that BBVA Net Cash Llave Inteligente and Santander Empresas sites are only supported through the Syncfy widget.
7. Credential Synchronization (User Pulls)
When a pull is performed, all accounts and transactions that the user has in their portal with the entered credentials are extracted. Ensure to perform the necessary pulls:
Avoid pulling to synchronize each account from the same credential; one pull is sufficient to obtain all accounts.
Consider that there is a rate limit of 5 minutes between each successful pull from the same credential.
If an execution throws an error, check the error based on the Status Codes before attempting again.
Perform a pull only for credential creation or transactional information update and not for queries in the API (See: Differences between a Pull and an API Call).
Allow the user to pull whenever they deem it necessary according to their use case, considering the rate limit.
8. API Changes
Is the implementation adaptable if Syncfy makes any changes as mentioned?
Different character count for a string.
New fields within the “extra” field.
Integration of new endpoints.
9. Security
Ensure that the implementation has no vulnerabilities.
The API Key isn’t exposed or visible in the code.
The API Key isn’t sent as a parameter in the request URL.
Use the session token to authenticate browser requests instead of the API Key.