> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# External sources
> Connect banks, payment gateways like Stripe and Adyen, ERPs such as SAP or Oracle, and card networks to Matcher via LEDGER, BANK, GATEWAY, or CUSTOM types.
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](/en/matcher/integrations/matcher-discovery) extracts data from Fetcher connections into ingestion |
| **Aggregator webhooks** | [Open-Finance aggregators](/en/matcher/integrations/matcher-aggregator-connections) 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](/en/reference/matcher/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:
```json theme={null}
{
"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](/en/reference/matcher/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
```json theme={null}
{
"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](/en/matcher/configuration/matcher-field-mapping) to translate ERP-specific fields into Matcher's canonical format.
## Payment processor connections
***
### Stripe
```json theme={null}
{
"name": "Stripe Payments",
"type": "GATEWAY",
"config": {
"provider": "stripe"
}
}
```
### Adyen
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```bash cURL theme={null}
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](/en/matcher/configuration/matcher-field-mapping) for details.
## Best practices
***
Check that uploaded files contain columns for the required canonical fields (external\_id, amount, currency, date) before uploading. This prevents ingestion errors.
Standardize on a single format (CSV, JSON, or XML) per source to simplify field mapping and reduce errors.
Store all API keys and passwords in the vault. Never include credentials in configuration payloads.
Validate field mapping and data quality with sample files before uploading production data.
## Next steps
***
Configure how source fields map to Matcher.
Manual file upload procedures.