External sources

External sources provide transaction data from systems outside your organization. This guide covers how to connect banks, payment gateways, and other external systems to Matcher.

Supported source types

Matcher supports five source types. Each represents a category of data origin:

Type	Description	Typical use
`LEDGER`	Internal ledger	Internal accounting systems (including Midaz)
`BANK`	Bank statement feed	External bank feeds
`GATEWAY`	Payment gateway	Payment processors (Stripe, Adyen, PayPal)
`CUSTOM`	Bespoke feed	ERPs, card networks, or any other data source
`FETCHER`	Discovery-engine pull	Aggregator connections pulled automatically

Ingestion methods

Transaction data reaches Matcher through several paths:

Method	Use Case
File upload	Manual uploads (CSV, JSON, XML, OFX, camt.053, CNAB, acquirer EDIs)
Transport fetch	Matcher pulls files from a configured transport (for example SFTP) and ingests them
Discovery extraction	Discovery extracts data from Fetcher connections into ingestion
Aggregator webhooks	Open-Finance aggregators signal new data, pulled asynchronously

File-based ingestion

The most common method for bank statements and ERP exports.

Manual upload

Use the file upload endpoint to import transaction files manually.

API Reference: Upload transaction file

Bank connections

Standard Bank format

Most banks provide statements in a format Matcher parses natively — CSV, OFX, camt.053, or the Brazilian CNAB layouts:

{
  "name": "Chase Business Account",
  "type": "BANK",
  "config": {
    "bank_name": "Chase",
    "account_number": "****1234",
    "currency": "USD",
    "statement_format": "CSV",
    "timezone": "America/New_York"
  }
}

The config object is free-form descriptive metadata — Matcher stores it but does not interpret keys like bank_name or statement_format. Parsing behavior is driven by the declared format dialect and the pinned configuration keys (error-rate policy, duplicate policy, blank_external_id, and camt.053 options), not by these labels.

API Reference: Create source

ERP and custom connections

Use the CUSTOM source type for ERP systems (SAP, Oracle, NetSuite, etc.) and any other data source that doesn’t fit the BANK, LEDGER, or GATEWAY categories.

Example: ERP source

{
  "name": "SAP S/4HANA",
  "type": "CUSTOM",
  "config": {
    "erp_type": "SAP",
    "company_codes": ["1000", "2000"]
  }
}

Export transaction data from your ERP and upload it through Matcher’s file upload endpoint. Use field mapping to translate ERP-specific fields into Matcher’s canonical format.

Payment processor connections

Stripe

{
  "name": "Stripe Payments",
  "type": "GATEWAY",
  "config": {
    "provider": "stripe"
  }
}

Adyen

{
  "name": "Adyen Settlements",
  "type": "GATEWAY",
  "config": {
    "provider": "adyen",
    "merchant_account": "CompanyECOM"
  }
}

Export settlement reports from your payment processor and upload them through Matcher’s file upload endpoint.

Card networks

For card network settlement files (Visa, Mastercard, Elo), use the CUSTOM source type:

{
  "name": "Visa Settlement",
  "type": "CUSTOM",
  "config": {
    "network": "VISA",
    "file_format": "TC33"
  }
}

Connection security

Credential storage

All credentials should be stored securely in an encrypted vault and referenced by ID in source configurations.

Ip allowlisting

Configure IP allowlisting at the infrastructure level (load balancer, API gateway, or firewall) to restrict which IPs can push data to Matcher. Source entities do not have a settings.security configuration. Manage IP restrictions outside the application.

Webhook signatures

Matcher signs outbound webhook payloads with HMAC-SHA256. For inbound data, verify signatures at the infrastructure level before data reaches Matcher. Source entities do not have a settings.webhook configuration.

Data format requirements

Required fields

Every transaction must include: Field maps use a closed canonical vocabulary: the mapping keys are fixed, and the values name the source’s raw column. These canonical keys are required:

Canonical key	Type	Description
`external_id`	String	Source-system transaction identifier
`amount`	Decimal	Transaction amount
`currency`	String	ISO 4217 code
`date`	Date	Transaction date

Optional fields

Canonical key	Type	Description
`description`	String	Reference/description text (feeds the transaction’s description column)
`fee_amount`	Decimal	Fee slot: source column carrying the fee amount
`fee_currency`	String	Fee slot: source column carrying the fee currency

No other keys are accepted—keys outside this vocabulary are rejected.

Field mapping

Manage field maps with the dedicated endpoint (not the source’s config object). The request body is a single mapping object of { canonicalKey: sourceColumnName } pairs:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "TXN_ID",
     "amount": "trans_amount",
     "currency": "CCY",
     "date": "POST_DATE",
     "description": "memo",
     "fee_amount": "mdr_fee",
     "fee_currency": "fee_ccy"
   }
 }'

Refer to Field Mapping for details.

Best practices

Validate files before uploading

Check that uploaded files contain columns for the required canonical fields (external_id, amount, currency, date) before uploading. This prevents ingestion errors.

Use consistent file formats

Standardize on a single format (CSV, JSON, or XML) per source to simplify field mapping and reduce errors.

Secure credentials properly

Store all API keys and passwords in the vault. Never include credentials in configuration payloads.

Test with sample data first

Validate field mapping and data quality with sample files before uploading production data.

Overview

Guides

Matcher UI

MCP Server

Operations

External sources

Supported source types

Ingestion methods

File-based ingestion

Manual upload

Bank connections

Standard Bank format

ERP and custom connections

Example: ERP source

Payment processor connections

Stripe

Adyen

Card networks

Connection security

Credential storage

Ip allowlisting

Webhook signatures

Data format requirements

Required fields

Optional fields

Field mapping

Best practices

Next steps

Field Mapping

Uploading Files

​Supported source types

​Ingestion methods

​File-based ingestion

​Manual upload

​Bank connections

​Standard Bank format

​ERP and custom connections

​Example: ERP source

​Payment processor connections

​Stripe

​Adyen

​Card networks

​Connection security

​Credential storage

​Ip allowlisting

​Webhook signatures

​Data format requirements

​Required fields

​Optional fields

​Field mapping

​Best practices

​Next steps

Field Mapping

Uploading Files

Supported source types

Ingestion methods

File-based ingestion

Manual upload

Bank connections

Standard Bank format

ERP and custom connections

Example: ERP source

Payment processor connections

Stripe

Adyen

Card networks

Connection security

Credential storage

Ip allowlisting

Webhook signatures

Data format requirements

Required fields

Optional fields

Field mapping

Best practices

Next steps