Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.formance.com/llms.txt

Use this file to discover all available pages before exploring further.

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 API specifications to an endpoint that you develop and provide. This endpoint acts as a middleware between Formance and the PSP.

​
Prerequisites

Before you begin, you need to have a sandbox stack running. If you don’t have one, you can create one by following the Getting started with Formance guide.

​
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 server implements the full Generic Connector API specification, including accounts, beneficiaries, transactions, payouts, and transfers.
1

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 will see and modify the same data. Pick something unique to avoid collisions.
2

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 here 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 internal accounts and beneficiaries, then generate some transactions so the Generic Connector has data to poll.
3

Install the Generic Connector

Create a generic-connector.json file with your API key and the mock endpoint:
generic-connector.json
{
  "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.json
You should see a similar output:
You are about to install connector 'generic'.
Do you want to continue [Y/n]y
 SUCCESS  generic: connector 'eyJQcm92aWRlciI6IkdFTkVSSUMiLCJSZWZlcmVuY2UiOiI2NzI5YjI5NS00MGZmLTQzOWQtOTU1NS1mNTYwN2M2MzAzODUifQ' installed!

​
Explore the data

Now that the connector is installed, open the Formance console: 
fctl ui
Navigate 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 PENDING to SUCCEEDED, trigger a DISPUTE, or issue a REFUND) to observe how status changes propagate into Formance
  • Create new accounts and beneficiaries
The Generic Connector will pick up any new or updated data on the next polling cycle.
Use a short pollingPeriod (e.g., "20m") during testing so changes appear quickly in Formance. For production, a longer period like "40m" or "2h" reduces load on your integration service.