Aggregator connections

Aggregator connections let Matcher pull transaction data from Open-Finance data aggregators (Pluggy, Belvo). You create a connection with a sealed credential, link a reconciliation source to it, and mint a webhook token bound to the connection. The aggregator’s webhooks then drive inbound pulls. This guide covers the full lifecycle.

Credentials (clientId/secret) are inbound-only: Matcher seals them before persistence and never returns them in a response, a log, or an error. The tenant always comes from the JWT, never from the request body.

Create a connection

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "clientId": "...",
    "secret": "..."
  }'

Field values:

vendor: pluggy or belvo.
configName: unique (tenant-scoped) connection identity. A duplicate is a 409. The webhook token-mint endpoint binds a token to this name.
baseUrl: vendor API base URL, stored as the connection host.
accountRef: opaque vendor account reference (Pluggy itemId, Belvo link id) threaded onto the webhook pull. It is optional. Leave it out to connect the account through hosted consent.
clientId / secret: aggregator API credential, sealed and never emitted.

A successful create returns 201 with the secret-free connection descriptor:

{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "awaitingConsent": false
}

Link a reconciliation source

Matcher ingests the pulled data into the reconciliation source that names the connection. On exactly one source, set config.connection_config_name to the configName of the connection:

{
  "name": "Pluggy Main Account",
  "type": "BANK",
  "side": "RIGHT",
  "config": {
    "connection_config_name": "pluggy-main"
  }
}

API Reference: Create source

List, get, update, delete

# List (cursor-paginated, secret-free)
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections?limit=20" \
  -H "Authorization: Bearer $TOKEN"

# Get by opaque id
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

Each list row carries id, vendor, configName, baseUrl, accountRef, testable, and awaitingConsent.

Update

Edit an existing connection by id so a mistyped baseUrl is not permanent. The vendor is immutable. The credential is optional: supply both clientId and secret to rotate the sealed credential, or omit both to leave the stored secret intact. Supplying exactly one is a 400. The other fields are optional too: a field you leave out keeps its stored value.

curl -X PUT "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }'

A connection created without accountRef waits for consent: it shows "awaitingConsent": true. POST /v1/discovery/aggregator-connections/{id}/connect-token returns a token for the consent widget of the vendor. Send the item or link id that the widget returns as accountRef in the update call above. Discovery describes the full flow.

Delete

curl -X DELETE "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

Delete soft-deletes the connection (204), freeing its config name for reuse. A non-aggregator connection id returns 404 on any by-id operation. This surface never confirms the existence of a non-aggregator row.

Test a connection

Run a live connectivity check for an existing connection using its already-sealed credential, addressed by configName. Matcher reads the vendor from the stored connection. This call takes no credential and returns none.

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "configName": "pluggy-main" }'

{ "vendor": "pluggy", "configName": "pluggy-main", "healthy": true }

A credentials-don’t-work outcome is an expected test result surfaced as "healthy": false with a 200, not an error. A missing connection returns 404. Matcher cannot test Belvo connections, so a Belvo connection returns 422 (MTCH-0210). A connection that waits for consent returns 422 (MTCH-0211).

Connector types

List the connector types the engine registry has actually registered for this deployment, each tagged with a backend-derived category (database or rest). The list reflects the live registry. Only connectors registered at boot appear. It drives the connection form’s type-select.

curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"

{
  "types": [
    { "type": "POSTGRESQL", "category": "database" },
    { "type": "STRIPE", "category": "rest", "requiredFields": ["apiKey"] }
  ]
}

Each rest entry lists in requiredFields the credential fields that a REST connection of that type needs. This list excludes aggregator-vendor types (Pluggy/Belvo). The aggregator-connections surface above provisions them.

Mint a webhook token

Mint a webhook token bound to an existing aggregator connection. The response carries the raw token and its provider-facing webhook URL once. Matcher stores only the token’s SHA-256 hash.

curl -X POST "https://api.matcher.example.com/v1/discovery/webhooks/tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "connection_config_name": "pluggy-main"
  }'

{
  "token": "<raw-token-shown-once>",
  "webhook_url": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>",
  "vendor": "pluggy"
}

Configure the returned webhook_url in the aggregator’s dashboard. A missing target connection returns 404. Matcher verifies each vendor delivery by an HMAC-SHA256 signature of the raw body in X-Webhook-Signature, or by source IP. A delivery that fails verification receives 401.

Response codes

Status	Meaning
`200`	Get, list, test, or connector-types returned
`201`	Connection created, webhook token minted, or consent token minted
`204`	Connection soft-deleted
`400`	Partial credential pair, malformed credential, or invalid pagination cursor
`401`	Tenant could not be resolved
`404`	Connection not found (or not an aggregator)
`422`	Request fails validation, for example a missing field or a vendor other than `pluggy` or `belvo`
`422` (`MTCH-0210`)	Matcher cannot test this vendor (Belvo)
`422` (`MTCH-0211`)	The connection waits for consent, so no test ran
`422` (`MTCH-0212`)	The vendor did not issue a consent token
`422` (`MTCH-0213`)	Matcher has no consent flow for this vendor
`409`	Connection with that config name already exists

Overview

Guides

Console

MCP Server

Operations

Aggregator connections

Create a connection

Link a reconciliation source

List, get, update, delete

Update

Delete

Test a connection

Connector types

Mint a webhook token

Response codes

​Create a connection

​Link a reconciliation source

​List, get, update, delete

​Update

​Bind an account through hosted consent

​Delete

​Test a connection

​Connector types

​Mint a webhook token

​Response codes

Create a connection

Link a reconciliation source

List, get, update, delete

Update

Bind an account through hosted consent

Delete

Test a connection

Connector types

Mint a webhook token

Response codes