Generic Connector Mock

Type

Count

Asset / Currency

Country

Account Holder Name

Initial Balance

Amount in smallest currency unit

🎯 What is this?

This is a multi-tenant PSP (Payment Service Provider) mock server for testing Formance's Generic Connector. It simulates a real payment provider API, allowing you to:

Create and manage accounts (internal wallets & external beneficiaries)
Generate transactions (payins, payouts, transfers)
Test payment workflows with realistic state transitions
Validate your Formance connector integration

🔑 Multi-Tenancy (API Key)

Each API key creates an isolated dataset. Think of it as a separate sandbox:

Authorization: Bearer your-api-key

Different API keys = different data views
Data is completely isolated between keys
Use different keys to simulate multiple merchants
Empty API key requests are rejected (401)

💡 Tip: Enter your API key in the header to see/create data for that tenant.

📦 Data Model

🏦

Internal Accounts Your merchant wallets

👤

Beneficiaries External recipients

💳

Transactions PayIn, PayOut, Transfer

💸

Payouts Outbound payments

🔄

Transfers Internal movements

🚀 Getting Started

1

Set your API key

Enter any unique key in the header field (e.g., my-test-merchant)

2

Create accounts

Click 🏦 New → create Internal Accounts and Beneficiaries

3

Generate transactions

Click 💳 Generate to create test PayIn/PayOut/Transfer data

4

Install on Formance

Click ⚡ Install → configure your connector → use fctl or cURL to install

5

Test state transitions

Use action buttons to simulate payment lifecycle events (disputes, refunds, adjustments)

⚡ Installing on Formance

Click the ⚡ Install button to configure your Generic Connector:

A

Configure connector settings

Set name, polling period, and target Formance Stack (Organization + Stack + Region)

B

Choose installation method

fctl: Download JSON config → run fctl payments connectors install generic config.json

cURL: Copy the cURL command to directly call the Payments API

C

Verify connection

Formance will poll the mock server and sync accounts + transactions

💡 Local dev: Use host.docker.internal if Formance runs in Docker. Set polling to 10s for quick testing.

📝 Creating Accounts

Use 🏦 New to create:

Internal Account	Merchant wallets that hold funds
Beneficiary	External accounts for payouts
Bank Account	Settlement bank details

💳 Generating Transactions

Use 💳 Generate to create test transactions:

PAYIN	Funds coming in (external → internal)
PAYOUT	Funds going out (internal → external)
TRANSFER	Internal movements (internal → internal)

💡 When generating PAYOUT/TRANSFER transactions, corresponding payout/transfer records are automatically created for consistency.

🎮 Testing State Transitions

Use the action buttons on each row to test state changes:

Succeed Fail Dispute Refund Adjust Amount

Each entity follows specific state machines detailed in the State Machines tab.

💸 Payout State Machine

Simple linear flow for outbound payments

PENDING

→

PROCESSING

→

SUCCEEDED

PENDING ↓

FAILED CANCELLED EXPIRED

PROCESSING ↓

FAILED

🔄 Transfer State Machine

Identical to payouts - simple linear flow

PENDING

→

PROCESSING

→

SUCCEEDED

PENDING ↓

FAILED CANCELLED EXPIRED

PROCESSING ↓

FAILED

💳 Transaction State Machine

Complex flow with disputes, refunds, and payment adjustments

PENDING

→

PROCESSING

→

SUCCEEDED

Authorization Flow (Card Payments)

AUTHORISATION

→

CAPTURE

→

SUCCEEDED

Post-Success Flows

SUCCEEDED

→

DISPUTE

→

DISPUTE_WON

or

DISPUTE_LOST

SUCCEEDED

→

REFUNDED

→

REFUND_REVERSED

or

REFUNDED_FAILURE

SUCCEEDED

→

AMOUNT_ADJUSTMENT

Terminal States

FAILED CANCELLED EXPIRED DISPUTE_LOST CAPTURE_FAILED

🔗 Payment Adjustments

Linked transactions that modify a parent payment

When certain state transitions occur, adjustment transactions are automatically created and linked to the original transaction via relatedTransactionID. All adjustments include an adjustmentType in metadata:

Refund	PAYOUT / REFUNDED with `adjustmentType: REFUND`
Chargeback	PAYOUT / DISPUTE_LOST with `adjustmentType: CHARGEBACK`
Refund Failure	PAYIN / SUCCEEDED with `adjustmentType: REFUND_CANCELLATION`
Refund Reversal	PAYIN / SUCCEEDED with `adjustmentType: REFUND_REVERSAL`
Amount Adjustment	PAYIN (+) or PAYOUT (-) with `adjustmentType: AMOUNT_ADJUSTMENT`

💡 Click the 🔗 button on any parent transaction to view all linked adjustments.

📋 State Transition Summary

From State	Allowed Transitions	Creates Adjustment?
PENDING	PROCESSING, AUTHORISATION, SUCCEEDED, FAILED, CANCELLED, EXPIRED	—
PROCESSING	SUCCEEDED, FAILED, CANCELLED, EXPIRED	—
AUTHORISATION	CAPTURE, CAPTURE_FAILED	—
CAPTURE	SUCCEEDED	—
SUCCEEDED	DISPUTE, REFUNDED, AMOUNT_ADJUSTEMENT	✓ Refund, Amount Adj
DISPUTE	DISPUTE_WON, DISPUTE_LOST	✓ Dispute Lost
DISPUTE_WON	REFUNDED	✓ Refund
REFUNDED	REFUND_REVERSED, REFUNDED_FAILURE	✓ Reversal, Cancellation

Generic Connector Mock

Details

Create New

Generate Transactions

⚡ Install on Formance

📖 User Guide

🎯 What is this?

🔑 Multi-Tenancy (API Key)

📦 Data Model

🚀 Getting Started

⚡ Installing on Formance

📝 Creating Accounts

💳 Generating Transactions

🎮 Testing State Transitions

💸 Payout State Machine

🔄 Transfer State Machine

💳 Transaction State Machine

🔗 Payment Adjustments

📋 State Transition Summary

🔗 Payment Adjustments

± Amount Adjustment