Requirements and Best Practices

We have a number of implementation requirements to ensure the security of our network and your consumers' financial data.

Requirements

• A consent UX in your app

  • Your consumer should consent to the access and use of their data from the original data provider. The consent flow leverages OAuth 2.0 authorization. For more information, see:

    • Authorization request

    • Authorization code grant type

    • Refresh token grant type

• OIDC token use with secure, encrypted storage

• Redirect URIs

  • The callback resource in your application where we will send the consumer and authorization code after successful authentication

• Secure, encrypted storage for your app’s client_id, client_secret and all tokens

  • The client_secret should never be hard-coded into your application's source code.

Best practices

• One Hub account. Your company should maintain one Data Recipient Hub team account. The first team member to join the Hub should send invitations to the remaining members of the team. See: Data Recipient User Manual.

• Token revocation. Provide a link for the consumer to revoke permission for use of their provider's accounts.

• Transactions. Transaction calls should follow data minimization best practices. For each call, specify date ranges and utilize pagination to handle the data. Your app should track the date-time of the last transaction request. In subsequent calls, to receive only new transactions, use a date range after the date-time of the last call.

• Pagination. Build a pagination component into your app, allowing it to receive one page at a time.

• Outages. When major service disruptions occur that impact the network, such as an event that causes you to invalidate all tokens or forces re-authentication, please notify us by signing into the Data Recipient Hub and visiting the Support Center.

• Errors.

  • For 500-level HTTP errors, we recommend implementing three (3) retries to help your app deal with short-lived, transient failures. The waiting time between retries should increase exponentially with each retry attempt.

• Versioning. Breaking changes are limited to major API versions. To reduce the need for large, breaking-change updates, we continue to improve clusters by releasing minor updates on a continual basis. These minor updates are non-breaking, backward-compatible improvements. When migrating to a new API release, please plan for these minor version updates and implement in a way to allow for these non-breaking changes.

• Requests.

  • Send the FDX-API-Actor-Type header with all endpoint calls to indicate if the request is part of a batch process or a real-time, consumer interaction. See: Headers.

  • When using a batch or bulk process, we recommend implementing your app to handle HTTP status 429, error code 1207. If receiving this response, send bulk requests at a slower rate.

• Responses.

  • Track the header returned with each API request. See: Headers.

  • Your app should handle 206 HTTP Partial Responses.

FDX

Our API is based on Financial Data Exchange (FDX) specifications. The following FDX guidance is recommended while using the API:

• Utilize the FDX API, security, and user experience specifications.

• Follow FDX version recommendations for API deprecation.

Recipients need not be members of FDX to integrate; however, FDX provides a variety of membership options. It also provides fee-free access to API specifications by accepting the intellectual property agreement.

Changelog