The Modulr connector polls a Modulr customer and surfaces UK/EU bank accounts, balances, beneficiaries, and transactions. It also initiates transfers between Modulr accounts and payouts to registered beneficiaries.
Prerequisites#
You need a Modulr customer and an API key + secret pair. Modulr signs every request with HMAC-SHA1; the connector builds the Authorization header automatically.
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.
Installation#
curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/modulr \
-H "Content-Type: application/json" \
-d @config.jsonConfiguration fields#
| Field | Type | Required | Default |
|---|---|---|---|
apiKey | string | Yes | |
apiSecret | string | Yes | |
endpoint | string | Yes | |
pageSize | integer | No | 25 |
pollingPeriod | string | No | 30m |
endpoint is https://api-sandbox.modulrfinance.com/api-sandbox for sandbox, https://api.modulrfinance.com/api-live for production.
Capabilities#
FETCH_ACCOUNTS— bank accounts viaGET /accounts.FETCH_BALANCES— available + reserved per account.FETCH_EXTERNAL_ACCOUNTS— beneficiaries viaGET /beneficiaries.FETCH_PAYMENTS— transactions, classified PAY-IN / PAYOUT / TRANSFER.CREATE_TRANSFER—POST /paymentsbetween two Modulr accounts on the same rail.CREATE_PAYOUT—POST /paymentsto a beneficiary (Faster Payments for GBP, SEPA for EUR).
CREATE_BANK_ACCOUNT is not implemented. Webhooks are not wired.
Account model#
Every Connectivity internal account is one Modulr account from GET /accounts. The reference is the account ID; name is the account name; defaultAsset is the account's currency (Modulr supports GBP and EUR). EXTERNAL accounts come from /beneficiaries. See Accounts for the cross-connector model.
Asset model#
GBP and EUR at the account level — GBP/2 / EUR/2. Amounts arrive as decimal strings; the connector applies major-to-minor scaling.
Status mapping#
Modulr status | Payment status |
|---|---|
SUBMITTED, VALIDATED, SCHEDULED, PROCESSING | PENDING |
PROCESSED, CONFIRMED | SUCCEEDED |
ER_INVALID, ER_EXTSYS, ER_GENERAL | FAILED |
CANCELLED, RECALLED | CANCELLED |
CREATE_TRANSFER and CREATE_PAYOUT schedule PollTransferStatus / PollPayoutStatus against /payments/{id} until terminal.
Metadata keys#
Under com.modulr.spec/:
- Account:
account_id,account_number,sort_code(UK),iban(EU),bic,customer_id. - External account:
beneficiary_id,account_number,sort_code,iban,bic,name. - Payment:
transaction_id,payment_id,reference,end_to_end_id,payment_method(PAYOUT/SEPA_CT/FPS_OUT/ …),direction.
Workflow tree#
FetchAccounts (periodic)
├── FetchBalances (FromPayload — no extra API call)
└── FetchPayments (periodic) — per account
FetchExternalAccounts (periodic)
CreateTransfer / CreatePayout (event-driven)
└── PollTransferStatus / PollPayoutStatus until terminalPagination and recovery#
0-indexed page + size (max 100). Watermarks persist in platform-managed State; restarts resume from the last committed page boundary.
Known gaps#
- Webhooks are not implemented — subscription provisioning is not wired.
- CHAPS (high-value GBP rail) is not exposed; outbound covers Faster Payments and SEPA only.
- Beneficiary creation through Connectivity is not wired; manage beneficiaries in the Modulr portal.