> ## 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, ERPs, and other external systems to Matcher and ingest their transaction data.

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 four source types. Each represents a category of data origin:

| Type      | Description                    | Typical use                                   |
| --------- | ------------------------------ | --------------------------------------------- |
| `LEDGER`  | General ledger accounts        | Internal accounting systems                   |
| `BANK`    | Bank statements                | External bank feeds                           |
| `GATEWAY` | Payment processor transactions | Payment gateways                              |
| `CUSTOM`  | Custom integrations            | ERPs, card networks, or any other data source |

## Ingestion methods

***

Transaction data is ingested through file upload:

| Method          | Use Case                    | Formats        |
| --------------- | --------------------------- | -------------- |
| **File Upload** | Manual CSV/JSON/XML uploads | CSV, JSON, XML |

## 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.

<Tip>API Reference: [Upload transaction file](/en/reference/matcher/upload-transaction-file)</Tip>

## Bank connections

***

### Standard Bank format

Most banks provide CSV or MT940 formatted statements:

```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"
  }
}
```

### Mt940/mt942 format

For SWIFT-formatted bank statements:

```json theme={null}
{
  "name": "International Bank SWIFT",
  "type": "BANK",
  "config": {
    "statement_format": "MT940",
    "swift_bic": "CHASUS33",
    "parse_options": {
      "date_format": "YYMMDD",
      "amount_decimal_indicator": ","
    }
  }
}
```

<Tip>API Reference: [Create source](/en/reference/matcher/create-source)</Tip>

## 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            | Type    | Description           |
| ---------------- | ------- | --------------------- |
| `transaction_id` | String  | Unique ID from source |
| `amount`         | Decimal | Transaction amount    |
| `currency`       | String  | ISO 4217 code         |
| `date`           | Date    | Transaction date      |

### Recommended fields

| Field          | Type   | Description       |
| -------------- | ------ | ----------------- |
| `reference`    | String | Payment reference |
| `counterparty` | String | Other party name  |
| `type`         | String | credit/debit      |
| `posting_date` | Date   | Settlement date   |

### Field mapping

Use a dedicated endpoint to manage field mappings, not the source's `config` object. Create field mappings for a source using:

```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 '{
   "sourceField": "trans_amount",
   "targetField": "amount"
 }'
```

Refer to [Field Mapping](/en/matcher/configuration/matcher-field-mapping) for details.

## Best practices

***

<AccordionGroup>
  <Accordion title="Validate files before uploading">
    Check that uploaded files contain the required fields (transaction\_id, amount, currency, date) before uploading. This prevents ingestion errors.
  </Accordion>

  <Accordion title="Use consistent file formats">
    Standardize on a single format (CSV, JSON, or XML) per source to simplify field mapping and reduce errors.
  </Accordion>

  <Accordion title="Secure credentials properly">
    Store all API keys and passwords in the vault. Never include credentials in configuration payloads.
  </Accordion>

  <Accordion title="Test with sample data first">
    Validate field mapping and data quality with sample files before uploading production data.
  </Accordion>
</AccordionGroup>

## Next steps

***

<CardGroup cols={2}>
  <Card title="Field Mapping" icon="arrows-left-right" href="/en/matcher/configuration/matcher-field-mapping">
    Configure how source fields map to Matcher.
  </Card>

  <Card title="Uploading Files" icon="upload" href="/en/matcher/daily-reconciliation/matcher-uploading-files">
    Manual file upload procedures.
  </Card>
</CardGroup>