Skip to main content

​
Prerequisites

Before you begin, you need to have a Plaid account. Make sure you have a Plaid API key and secret, with the least amount of permissions required to access the functionality of the Plaid Connector you plan to use.
Make sure to create an API key dedicated to Formance. Doing so will improve your auditability and security and will allow you to revoke access to Formance at any time if needed.
  • Connectivity module version 3.1.0 or higher
  • Plaid dashboard access with permissions to configure redirect URIs
Plaid has specific requirements for API credentials and redirect URL configuration. Ensure you have the necessary permissions before proceeding.

​
Installation

fctl payments connectors install plaid config.json
With config.json containing: 
{
  "clientID": "string",
  "clientSecret": "string",
  "isSandbox": true,
  "name": "string",
  "pollingPeriod": "30m"
}

​
Configuration parameters

ParameterDescriptionLocation in Plaid Dashboard
clientIDApplication client identifierDevelopers > Keys
clientSecretApplication client secretDevelopers > Keys
isSandboxEnvironment setting (true for sandbox, false for production)Based on your environment

​
Plaid-specific requirements

​
Redirect URL configuration

Plaid has strict redirect URL requirements. The URL provided in the create-link endpoint must be registered exactly in your Plaid dashboard under Developers > API > Allowed Redirect URIs. Query parameters are not allowed - it must be an exact match.
To configure redirect URLs:
  1. Navigate to Developers > API > Allowed Redirect URIs in your Plaid dashboard
  2. Add your redirect URL without any query parameters
  3. Ensure the URL matches exactly what you’ll use in the create-link endpoint

​
PSU forwarding requirements

When forwarding a Payment Service User (PSU) to Plaid, the following information is required:
  • Name: User’s full name
  • Contact details: Email and phone number
  • Address: Complete address from an allowed country
The applicationName parameter in create-link requests must match the client name configured in your Plaid dashboard (visible in the top left corner of the dashboard).

​
Testing with Plaid

For testing purposes, Plaid provides sandbox test credentials. Refer to the Plaid Sandbox Test Credentials documentation for available test accounts and credentials.

​
Troubleshooting

​
Invalid redirect URL

Problem: Users encounter redirect URL errors during the authentication flow. Solution:
  1. Verify the redirect URL is registered exactly in Plaid dashboard under Developers > API > Allowed Redirect URIs
  2. Ensure no query parameters are included in the registered URL
  3. Check that the URL used in create-link matches the registered URL exactly

​
PSU forwarding fails

Problem: Payment Service User forwarding to Plaid fails. Solution: Verify that the PSU contains all required fields:
  • Complete name information
  • Valid contact details (email and phone)
  • Address from a country supported by Plaid

​
Application name mismatch

Problem: Create-link requests fail due to application name issues. Solution: Ensure the applicationName parameter matches the client name shown in the top left corner of your Plaid dashboard.