The Generic Connector for Formance Connectivity provides a way to connect your Formance Stack with Payment Service Providers that are not natively supported by Formance.
In this tutorial, you will connect your Formance Stack to a mock PSP server that simulates a real Payment Service Provider. You will generate test data through the mock's admin panel and watch it flow into Formance through the Generic Connector.
The Generic Connector interacts with a Payment Service Provider by sending requests formatted according to the Generic Connector contract to an endpoint that you develop and provide. This endpoint acts as a middleware between Formance and the PSP.
Setup#
For this tutorial, you will use the Generic Connector Mock — a multi-tenant PSP simulator hosted at https://formance-generic-connector-mock.fly.dev. The mock implements the full Generic Connector contract (accounts, beneficiaries, transactions, payouts, transfers) and ships with a browser admin panel for seeding test data.
Choose a unique API key
The mock server is multi-tenant: each API key creates an isolated dataset. Choose a unique key that will be yours for this tutorial (e.g. my-company-test, your email, or a UUID).
Anyone using the same API key sees and modifies the same data. Pick something unique to avoid collisions.
Seed test data through the admin panel
Open the mock admin panel in your browser and enter your API key in the header field.
From there you can:
- Create internal accounts and beneficiaries using the New button.
- Generate transactions (payins, payouts, transfers) using the Generate button.
- Simulate payment lifecycle transitions (disputes, refunds, captures) using the action buttons on each row.
Create a few accounts and beneficiaries, then generate some transactions so the Generic Connector has data to poll.
Install the Generic Connector
Create a generic-connector.json file with your API key and the mock endpoint:
{
"name": "generic-tutorial",
"apiKey": "YOUR_UNIQUE_API_KEY",
"endpoint": "https://formance-generic-connector-mock.fly.dev",
"pollingPeriod": "20m"
}Replace YOUR_UNIQUE_API_KEY with the same key you used in the admin panel.
Then install the connector on your stack:
fctl payments connectors install generic generic-connector.jsonYou should see output similar to:
You are about to install connector 'generic'.
Do you want to continue [Y/n]y
SUCCESS generic: connector 'eyJQcm92aWRlciI6IkdFTkVSSUMiLCJSZWZlcmVuY2UiOiI2NzI5YjI5NS00MGZmLTQzOWQtOTU1NS1mNTYwN2M2MzAzODUifQ' installed!Explore the data#
Open the Formance console:
fctl uiNavigate to the Connectivity page. You should see the accounts, beneficiaries, and transactions you created in the mock admin panel flowing into Formance.
If you don't see any data yet, wait for the next polling cycle (based on the pollingPeriod you configured) or click the Refresh status button.
Generate more data#
You can return to the mock admin panel at any time to:
- Generate additional transactions to test incremental polling.
- Transition transaction statuses (e.g. move a payment from
PENDINGtoSUCCEEDED, trigger aDISPUTE, issue aREFUND) to observe how status changes propagate into Formance. - Create new accounts and beneficiaries.
The Generic Connector picks up any new or updated data on the next polling cycle.
Use a short pollingPeriod (e.g. 20m, the connector's minimum) during testing so changes appear quickly in Formance. For production, a longer period like 40m or 2h reduces load on your integration service.