Payments

A payment in Connectivity is a single-asset balance movement on a single account leg, surfaced by a connector after the upstream provider returns it. Deposits, withdrawals, internal transfers, settlement events, refunds, fee payments — they all land here. Exchange-flavoured flows that move two assets atomically (stablecoin redemption, FX swaps) live on Conversions, and trading orders against an order book live on Orders.

Payment model#

Listing payments#

Formance Console#

Open the Connectivity tab in the sidebar. The Payments view lists every payment synced from every installed connector with filters for connector, status, type, scheme, asset, and date range. Click a row for the full payment detail, including the adjustment history and the upstream raw payload.

API#

curl -X GET $FORMANCE_API_URL/api/payments/v3/payments

v3ListPayments accepts a $match query body for server-side filtering — significantly more efficient than fetching the full set and filtering client-side, especially against large connectors:

curl -s "$STACK/api/payments/v3/payments?pageSize=15" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"$match": {"connectorID": "'$CONNECTOR_ID'", "status": "SUCCEEDED"}}' | jq

A single payment by id:

curl -X GET $FORMANCE_API_URL/api/payments/v3/payments/<PAYMENT_ID>

The detail endpoint inlines adjustments and raw, neither of which appear in the list response.

Querying by reference or metadata#

v3GetPayment only accepts the platform-assigned id. To find a payment by the provider's reference, or by a com.<provider>.spec/ metadata key, use the list endpoint with a $match body:

By reference#

{
  "$match": {
    "reference": "tx_4f3a8e9d1c"
  }
}

By metadata key#

{
  "$match": {
    "metadata[com.routable.spec/payment_initiation_reference]": "payout-acmecorp-20260506-172725"
  }
}

Payment types#

The type field collapses the provider's lifecycle vocabulary into four buckets:

The per-connector reference pages (Stripe, Mangopay, Coinbase Prime, …) document the mapping from each provider's upstream event vocabulary to the four-type model.

Status mapping#

The status field collapses each provider's status enum into a uniform Connectivity vocabulary:

• PENDING — created, accepted, in-flight at the provider.
• SUCCEEDED — terminal success.
• FAILED — terminal failure.
• CANCELLED — user-cancelled or merchant-voided.
• EXPIRED — provider expired the payment before it settled.
• OTHER — provider-specific non-terminal status the connector chose not to collapse.
• UNKNOWN — provider returned a status the connector doesn't recognise.

The exact upstream-status → Connectivity-status mapping is documented on each connector's reference page. Coinbase Prime's table is in Coinbase Prime → Payments; the same pattern applies to every other connector.

Adjustments#

Every observed state change lands on the payment's adjustment list, including the new status, the timestamp, and (when the connector kept it) the raw upstream payload that triggered the change. Use it as the audit trail for back-office UIs and reconciliation runs.

Adjustments aren't inlined in v3ListPayments — fetch a payment by id with v3GetPayment to see them.

Payment reference enrichment#

Some connectors enrich payment metadata with PSP-specific reference fields they extract from upstream payloads — end-to-end IDs, mandate IDs, clearing-system references, creditor reference info, and similar. These land under the com.formance.connectors.<provider>. metadata namespace. The Banking Bridge connector applies this pattern most extensively. See Operations → Connector reliability for the cross-cutting behaviour.