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	Data that Discovery extracts from a connection

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 discovered 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",
  "side": "RIGHT",
  "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. Instead, Matcher acts on these reserved keys when you set them: dialect, fail_on_error_rate_percent, duplicate_policy, duplicate_key, blank_external_id, camt053, connection_id, and connection_config_name.

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",
  "side": "LEFT",
  "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",
  "side": "RIGHT",
  "config": {
    "provider": "stripe"
  }
}

Adyen

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

Export settlement reports from your payment processor and upload them through Matcher’s file upload endpoint. For Stripe, PagBank, and Pix BCB, Matcher can also extract the data through a REST connection.

Card networks

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

{
  "name": "Visa Settlement",
  "type": "CUSTOM",
  "side": "RIGHT",
  "config": {
    "network": "VISA"
  }
}

Connection security

Webhook signatures

Matcher verifies inbound aggregator webhooks with an HMAC-SHA256 signature or a source IP allowlist, as Aggregator connections describes. 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
`direction`	Object	Debit or credit indicator: `{column, debit, credit}`

Matcher accepts no other keys. Use direction when a file marks each row as debit or credit in a separate column. column names that column, and debit and credit are the values it holds. Matcher imports a debit row with a negative amount and a credit row with a positive one. When you map direction, the amount cells must carry no sign. A signed amount, an empty direction cell, or an unknown direction value rejects the row. Matcher applies direction to CSV, JSON, and XML input only.

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

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

Console

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

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

​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

Webhook signatures

Data format requirements

Required fields

Optional fields

Field mapping

Best practices

Next steps