Skip to main content
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:
TypeDescriptionTypical use
LEDGERGeneral ledger accountsInternal accounting systems
BANKBank statementsExternal bank feeds
GATEWAYPayment processor transactionsPayment gateways
CUSTOMCustom integrationsERPs, card networks, or any other data source

​
Ingestion methods

Transaction data is ingested through file upload:
MethodUse CaseFormats
File UploadManual CSV/JSON/XML uploadsCSV, 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.
API Reference: Upload transaction file

​
Bank connections

​
Standard Bank format

Most banks provide CSV or MT940 formatted statements: 
{
  "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: 
{
  "name": "International Bank SWIFT",
  "type": "BANK",
  "config": {
    "statement_format": "MT940",
    "swift_bic": "CHASUS33",
    "parse_options": {
      "date_format": "YYMMDD",
      "amount_decimal_indicator": ","
    }
  }
}
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:
FieldTypeDescription
transaction_idStringUnique ID from source
amountDecimalTransaction amount
currencyStringISO 4217 code
dateDateTransaction date
FieldTypeDescription
referenceStringPayment reference
counterpartyStringOther party name
typeStringcredit/debit
posting_dateDateSettlement date

​
Field mapping

Use a dedicated endpoint to manage field mappings, not the source’s config object. Create field mappings for a source using:
cURL
curl -X POST "https://api.matcher.example.com/v1/config/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 for details.

​
Best practices

Check that uploaded files contain the required fields (transaction_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

Field Mapping

Configure how source fields map to Matcher.

Uploading Files

Manual file upload procedures.