External sources

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

Supported source types

Banks: Daily statements, real-time feeds, and historical exports from financial institutions.
ERPs: SAP, Oracle, NetSuite, Microsoft Dynamics, and other enterprise systems.
Payment Processors: Stripe, Adyen, PayPal, Square, and payment gateway transactions.
Card Networks: Visa, Mastercard, Elo, and Amex settlement files.

Ingestion methods

External data can be ingested through multiple channels:

Method	Use Case	Real-time
File Upload	Manual CSV/JSON/XML uploads	No
SFTP Pull	Scheduled file retrieval	No
API Integration	Direct API connection	Yes
Fetcher Service	Automated data collection	Configurable
Webhook Push	External system pushes data	Yes

File-based ingestion

The most common method for bank statements and ERP exports.

Manual upload

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "context_id=ctx_abc123" \
 -F "source_id=src_bank456" \
 -F "file=@bank_statement_january.csv"

Response

{
  "job_id": "job_imp_001",
  "status": "QUEUED",
  "source_id": "src_bank456",
  "file_name": "bank_statement_january.csv",
  "file_size_bytes": 15420,
  "created_at": "2024-01-20T10:00:00Z"
}

SFTP pull configuration

Configure Matcher to pull files from an SFTP server:

cURL

curl -X POST "https://api.matcher.example.com/v1/sources/src_bank456/sftp" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "host": "sftp.bank.example.com",
   "port": 22,
   "username": "matcher_service",
   "auth_type": "ssh_key",
   "ssh_key_id": "key_001",
   "remote_path": "/outbound/statements/",
   "file_pattern": "statement_*.csv",
   "schedule": {
     "frequency": "daily",
     "time": "06:00",
     "timezone": "America/New_York"
   },
   "archive_after_import": true
 }'

Response

{
  "id": "sftp_001",
  "source_id": "src_bank456",
  "host": "sftp.bank.example.com",
  "status": "ACTIVE",
  "schedule": {
    "frequency": "daily",
    "time": "06:00",
    "timezone": "America/New_York",
    "next_run": "2024-01-21T06:00:00-05:00"
  },
  "last_run": {
    "timestamp": "2024-01-20T06:00:00-05:00",
    "status": "SUCCESS",
    "files_processed": 1
  }
}

SFTP authentication options

Auth Type	Configuration
`password`	`"password": "encrypted_password"`
`ssh_key`	`"ssh_key_id": "key_001"` (stored in vault)
`certificate`	`"certificate_id": "cert_001"`

Bank connections

Standard Bank format

Most banks provide CSV or MT940 formatted statements:

{
  "name": "Chase Business Account",
  "type": "BANK",
  "direction": "EXTERNAL",
  "settings": {
    "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",
  "direction": "EXTERNAL",
  "settings": {
    "statement_format": "MT940",
    "swift_bic": "CHASUS33",
    "parse_options": {
      "date_format": "YYMMDD",
      "amount_decimal_indicator": ","
    }
  }
}

Open banking / psd2

For real-time bank connections via Open Banking APIs:

cURL

curl -X POST "https://api.matcher.example.com/v1/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Bank via Open Banking",
   "type": "BANK",
   "direction": "EXTERNAL",
   "connection_type": "OPEN_BANKING",
   "settings": {
     "provider": "plaid",
     "institution_id": "ins_001",
     "account_ids": [
       "acc_001",
       "acc_002"
     ],
     "sync_frequency": "hourly"
   }
 }'

Response

{
  "id": "src_ob_001",
  "name": "Bank via Open Banking",
  "type": "BANK",
  "connection_type": "OPEN_BANKING",
  "status": "PENDING_AUTHORIZATION",
  "authorization_url": "https://api.matcher.example.com/v1/sources/src_ob_001/authorize"
}

ERP connections

SAP integration

{
  "name": "SAP S/4HANA",
  "type": "ERP",
  "direction": "INTERNAL",
  "connection_type": "API",
  "settings": {
    "erp_type": "SAP",
    "base_url": "https://sap.company.com/sap/opu/odata/sap/",
    "auth": {
      "type": "oauth2",
      "client_id": "matcher-integration",
      "token_url": "https://sap.company.com/oauth/token"
    },
    "entities": [
      "JournalEntry",
      "AccountingDocument"
    ],
    "company_codes": [
      "1000",
      "2000"
    ],
    "sync_frequency": "daily"
  }
}

Oracle integration

{
  "name": "Oracle Financials",
  "type": "ERP",
  "direction": "INTERNAL",
  "connection_type": "API",
  "settings": {
    "erp_type": "ORACLE",
    "base_url": "https://oracle.company.com/fscmRestApi/resources/",
    "auth": {
      "type": "basic",
      "username": "integration_user"
    },
    "ledger_id": "300000001",
    "legal_entity": "Company Inc"
  }
}

Generic ERP file export

For ERPs without direct API integration:

{
  "name": "Legacy ERP Export",
  "type": "ERP",
  "direction": "INTERNAL",
  "connection_type": "FILE",
  "settings": {
    "file_format": "CSV",
    "delimiter": "|",
    "encoding": "UTF-8",
    "date_format": "YYYYMMDD",
    "amount_format": {
      "decimal_separator": ".",
      "thousands_separator": ",",
      "scale": 2
    }
  }
}

Payment processor connections

Stripe integration

cURL

curl -X POST "https://api.matcher.example.com/v1/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Stripe Payments",
   "type": "PAYMENT_GATEWAY",
   "direction": "EXTERNAL",
   "connection_type": "API",
   "settings": {
     "provider": "stripe",
     "api_key_id": "secret_stripe_001",
     "sync_objects": [
       "charges",
       "payouts",
       "refunds"
     ],
     "sync_frequency": "hourly",
     "lookback_days": 7
   }
 }'

Response

{
  "id": "src_stripe_001",
  "name": "Stripe Payments",
  "type": "PAYMENT_GATEWAY",
  "connection_type": "API",
  "status": "CONNECTED",
  "settings": {
    "provider": "stripe",
    "sync_objects": [
      "charges",
      "payouts",
      "refunds"
    ],
    "sync_frequency": "hourly"
  },
  "connection_status": {
    "connected": true,
    "account_name": "Company Inc",
    "last_sync": "2024-01-20T10:00:00Z"
  }
}

Adyen integration

{
  "name": "Adyen Settlements",
  "type": "PAYMENT_GATEWAY",
  "direction": "EXTERNAL",
  "connection_type": "API",
  "settings": {
    "provider": "adyen",
    "merchant_account": "CompanyECOM",
    "api_key_id": "secret_adyen_001",
    "report_types": [
      "settlement_detail",
      "payment_accounting"
    ],
    "sync_frequency": "daily"
  }
}

PayPal integration

{
  "name": "PayPal Business",
  "type": "PAYMENT_GATEWAY",
  "direction": "EXTERNAL",
  "connection_type": "API",
  "settings": {
    "provider": "paypal",
    "client_id": "paypal_client_id",
    "client_secret_id": "secret_paypal_001",
    "environment": "live",
    "sync_objects": [
      "transactions",
      "payouts"
    ],
    "sync_frequency": "hourly"
  }
}

Card network settlement files

Visa settlement

{
  "name": "Visa Settlement",
  "type": "CARD_NETWORK",
  "direction": "EXTERNAL",
  "settings": {
    "network": "VISA",
    "file_format": "TC33",
    "member_id": "12345678",
    "settlement_currency": "USD"
  }
}

Mastercard settlement

{
  "name": "Mastercard IPM",
  "type": "CARD_NETWORK",
  "direction": "EXTERNAL",
  "settings": {
    "network": "MASTERCARD",
    "file_format": "IPM",
    "ica": "12345",
    "settlement_currency": "USD"
  }
}

Fetcher service integration

The Fetcher service automates data collection from connected sources.

Enable fetcher for a source

curl -X PUT "https://api.matcher.example.com/v1/sources/src_stripe_001/fetcher" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "enabled": true,
   "schedule": {
     "frequency": "hourly",
     "start_time": "00:15"
   },
   "retry_policy": {
     "max_attempts": 3,
     "backoff_multiplier": 2
   },
   "alerts": {
     "on_failure": [
       "[email protected]"
     ],
     "on_no_data": [
       "[email protected]"
     ]
   }
 }'

Monitor fetcher jobs

curl -X GET "https://api.matcher.example.com/v1/sources/src_stripe_001/fetcher/jobs?limit=10" \
 -H "Authorization: Bearer $TOKEN"

Response

{
  "jobs": [
    {
      "id": "fetch_001",
      "status": "COMPLETED",
      "started_at": "2024-01-20T10:15:00Z",
      "completed_at": "2024-01-20T10:15:45Z",
      "records_fetched": 1250,
      "records_new": 125,
      "records_updated": 0
    }
  ]
}

Connection security

Credential storage

All credentials are stored securely in an encrypted vault:

# Store API key
curl -X POST "https://api.matcher.example.com/v1/secrets" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "stripe_api_key",
   "type": "api_key",
   "value": "sk_live_..."
 }'

Response

{
  "id": "secret_stripe_001",
  "name": "stripe_api_key",
  "type": "api_key",
  "created_at": "2024-01-15T10:00:00Z"
}

Ip allowlisting

Configure source IPs that can push data:

{
  "settings": {
    "security": {
      "allowed_ips": [
        "192.168.1.0/24",
        "10.0.0.5"
      ],
      "require_tls": true,
      "min_tls_version": "1.2"
    }
  }
}

Webhook signatures

For sources that push via webhook, verify signatures:

{
  "settings": {
    "webhook": {
      "signature_header": "X-Signature",
      "signature_algorithm": "HMAC-SHA256",
      "secret_id": "secret_webhook_001"
    }
  }
}

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

Configure how source fields map to Matcher:

{
  "settings": {
    "field_map_id": "fmap_bank_001"
  }
}

Refer to Field Mapping for details.

Best practices

Use scheduled ingestion for banks

Configure SFTP or API polling for bank statements rather than manual uploads. This ensures consistent, timely data availability.

Enable retry policies

Configure automatic retries for API-based sources. Transient failures are common; retries prevent manual intervention.

Monitor connection health

Set up alerts for connection failures and no-data scenarios. Proactive monitoring prevents reconciliation delays.

Use appropriate sync frequency

Match sync frequency to your reconciliation needs. Daily for bank statements; hourly for payment processors.

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 enabling automated ingestion.

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​Supported source types

​Ingestion methods

​File-based ingestion

​Manual upload

​Response

​SFTP pull configuration

​Response

​SFTP authentication options

​Bank connections

​Standard Bank format

​Mt940/mt942 format

​Open banking / psd2

​Response

​ERP connections

​SAP integration

​Oracle integration

​Generic ERP file export

​Payment processor connections

​Stripe integration

​Response

​Adyen integration

​PayPal integration

​Card network settlement files

​Visa settlement

​Mastercard settlement

​Fetcher service integration

​Enable fetcher for a source

​Monitor fetcher jobs

​Response

​Connection security

​Credential storage

​Response

​Ip allowlisting

​Webhook signatures

​Data format requirements

​Required fields

​Recommended fields

​Field mapping

​Best practices

​Next steps

Field Mapping

Uploading Files

Supported source types

Ingestion methods

File-based ingestion

Manual upload

Response

SFTP pull configuration

Response

SFTP authentication options

Bank connections

Standard Bank format

Mt940/mt942 format

Open banking / psd2

Response

ERP connections

SAP integration

Oracle integration

Generic ERP file export

Payment processor connections

Stripe integration

Response

Adyen integration

PayPal integration

Card network settlement files

Visa settlement

Mastercard settlement

Fetcher service integration

Enable fetcher for a source

Monitor fetcher jobs

Response

Connection security

Credential storage

Response

Ip allowlisting

Webhook signatures

Data format requirements

Required fields

Recommended fields

Field mapping

Best practices

Next steps