Routable

The Routable connector polls a Routable workspace and surfaces its settings accounts, companies (counterparties), payables, and receivables to the Connectivity service. It also initiates outbound payables on Routable in response to Formance CreateTransfer and CreatePayout workflows.

Prerequisites#

You need a Routable account with an API key dedicated to Formance. Decide upfront which team member will own payables initiated through Formance — Routable requires an acting_team_member on every payable creation. You can either set this per-connector via config, or per-request via metadata; see Initiating payouts and transfers.

Installation#

curl -X POST $FORMANCE_API_URL/api/payments/connectors/routable \
  -H "Content-Type: application/json" \
  -d @config.json

Configuration fields#

The connector validates the API key at install time with a tiny GET /v1/settings/accounts?page=1&page_size=1 probe — a bad key surfaces as an install-time error rather than as a FETCH_ACCOUNTS failure later.

Capabilities#

The connector supports the following capabilities:

• FETCH_ACCOUNTS — internal settings accounts, polled via GET /v1/settings/accounts
• FETCH_BALANCES — settings-account available_amount, derived per-account via GET /v1/settings/accounts/{id}
• FETCH_EXTERNAL_ACCOUNTS — companies (counterparties), via GET /v1/companies
• FETCH_PAYMENTS — payables (outbound) and receivables (inbound), via GET /v1/payables and GET /v1/receivables
• CREATE_TRANSFER and CREATE_PAYOUT — both initiate POST /v1/payables (transfers are payables with the TRANSFER payment type)

Webhooks, bank-account creation, and reversals are not yet implemented — follow-up PRs upstream will add them.

Asset model#

Routable returns asset codes as ISO currency strings (USD, EUR, KWD). The connector formats them as Formance assets via go-libs/v3/currency.FormatAsset — USD/2, EUR/2, KWD/3, and so on. Unsupported currencies are skipped (logged) without dropping the rest of the page.

Amounts are decimal strings on Routable's side and are converted to integer minor units with half-up rounding before being written to Connectivity Payments.

Status mapping#

Routable's payable statuses collapse to the standard Connectivity Payment statuses:

Comparison is case-insensitive.

The payment scheme is mapped from Routable's delivery_method: ach_* → ACH, everything else → OTHER.

Metadata keys#

All Routable-specific fields are namespaced under com.routable.spec/. The full list lives in the connector's MAPPINGS.md; the highlights:

Account metadata (internal accounts)#

object, type, is_valid, currency_code, plus type_details.account_type, type_details.bank_name, type_details.account_number, type_details.routing_number.

External-account metadata (companies)#

object, type, status, country_code, is_vendor, is_customer, is_archived, external_id, business_name, display_name, plus the structured registered_address.* keys.

Payment metadata#

For payables (PAYOUT) and receivables (PAYIN): type, delivery_method, status, external_id, memo, reference. Two correlation aliases also land on every Payment we initiated:

• com.routable.spec/payment_initiation_reference — the originating PaymentInitiation reference (only present when Formance initiated the payable; payables created in Routable's UI don't carry it).
• com.routable.spec/payable_id — the Routable payable UUID (mirrors Payment.Reference).

See Correlating an initiation with the synced payment for how to use these.

Initiating payouts and transfers#

CreateTransfer and CreatePayout both translate the Formance PSPPaymentInitiation into a Routable POST /v1/payables. Most fields are derived from the structured initiation; a few Routable-specific knobs are exposed as initiation metadata:

The Formance PaymentInitiation.Reference is sent as the HTTP Idempotency-Key header — Routable returns the original payable on retries with the same key, which is the behaviour Formance's create-then-poll workflow relies on.

Async response handling#

Routable's POST /v1/payables answers in two shapes:

Once linked, subsequent status transitions (PENDING → PROCESSING → SUCCEEDED) are picked up by the periodic FETCH_PAYMENTS schedule rather than by re-polling.

Correlating an initiation with the synced payment#

When you initiate a payable through Formance, two distinct rows land:

• A PaymentInitiation keyed by the reference you supplied (e.g. payout-acmecorp-20260506-172725).
• A PSPPayment keyed by Routable's payable UUID (e.g. 652e0807-02ed-4546-848f-56babc66ec99).

They're linked at the engine level. To resolve one from the other:

Pagination and recovery#

Routable list endpoints are 1-indexed page+page_size (capped at 100). The connector checkpoints pagination state opaquely between cycles, so a worker crash mid-cycle resumes deterministically from the last persisted checkpoint — no row is double-billed or silently dropped.

The payments fetcher walks payables, then receivables, then advances its cycle watermark. The watermark stays immutable for the full duration of a cycle to avoid the page-2-tighter-than-page-1 race that would drop rows whose status_changed_at lands between page boundaries.

Routable's status_changed_at.gte filter is inclusive, so rows on the cycle boundary get re-emitted at every cycle start. The engine dedupes by PSPPayment.Reference, so this is wasted bandwidth but never a correctness problem.