Bank Integration Service - Zynergy Requirements

This document outlines what data Zynergy needs from the data requirements for a Bank Integration Service and proposes a schema structure.

All payment formats currently supported by Zynergy were analyzed to ensure the proposed schema can accommodate them, with an extensions mechanism for format-specific data.

...

to support Zynergy's payment processing - both incoming payments (from banks to Zynergy) and outgoing payments (from Zynergy to banks).

...

Incoming Payments (Bank → Zynergy)

Zynergy receives payment files from banks to match against invoices and apply payments.

Supported Formats

Zynergy processes the following incoming payment file formats:

• BGMax
• TotalIn
• Inbetalningsservice OCR
• ISO 20022 camt.054 (Nordea, Swedbank)
• Autogiro
• OCR Giro
• Betalingsservice
• Leverandorservice
• EDI Light
• OCR Kortart71
• OFUXML (international transfers)

...

Data Hierarchy

The schema follows a three-level hierarchy: file (metadata and duplicate detection), headers (payment batches with shared properties), and transactions (individual payments).

...

File-Level Fields

These fields identify the file and enable duplicate detection:

...

Required Fields

These fields are essential for Zynergy to process and reconcile payments:

*Some formats support multiple references per transaction (e.g., split payments where one payment covers multiple invoices). Each reference includes its portion of the total amount. First element is the primary reference.

**Refunds could alternatively be indicated by a separate transaction type field.

Note: When multiple ISO 20022 source fields are listed, Zynergy's existing parsers resolve them as follows: - transactionId: Use EndToEndId (payer-provided), fall back to AcctSvcrRef (bank-assigned) if unavailable - references: Use RfrdDocInf.Nb for invoices/credit notes (CINV/CREN), or CdtrRefInf.Ref for structured OCR references (SCOR) - messages: Use Ustrd (unstructured free-text), fall back to AddtlRmtInf (additional remittance info) if unavailable

...

Suggested Fields

These fields are useful for validation, reconciliation, and international payments:

...

Extensions (Format-Specific Data)

Extensions provide a mechanism to preserve format-specific data that doesn't fit the common schema. This data is:

...

1. Ignore extensions entirely - Core processing works without them
2. Store extensions as-is - Preserve for display/audit without parsing
3. Extract specific fields - Use known extension fields when present

...

Example Extension Fields

...

Example Schema

Core fields always present, format-specific data isolated in extensions.

{
  "file": {
    "uniqueId": "a1b2c3d4e5f6...",
    "timestamp": "2024-01-15T10:30:00Z",
    "format": "ISO20022_CAMT054",
    "provider": "Nordea"
  },
  "headers": [
    {
      "paymentDate": "2024-01-15",
      "currency": "SEK",
      "receivingAccount": "5555-1234567",
      "transactionCount": 2,
      "totalAmount": 14000.00,
      "transactions": [
        {
          "transactionId": "TXN-2024-001",
          "amount": 10500.00,
          "references": [{ "reference": "7340012345678", "amount": 10500.00 }],
          "messages": ["Invoice 12345"],
          "payer": {
            "id": "SE5501011234",
            "name": "Acme Corporation AB",
            "address": "Storgatan 1, Stockholm",
            "country": "SE",
            "bankAccount": "1234-5678901"
          },
          "extensions": {
            "discountCode": "0"
          }
        },
        {
          "transactionId": "TXN-2024-002",
          "amount": 3500.00,
          "references": [
            { "reference": "9912345678901", "amount": 2000.00 },
            { "reference": "9912345678902", "amount": 1500.00 }
          ],
          "messages": [],
          "payer": {
            "id": "SE6601025678",
            "name": null,
            "address": null,
            "country": null,
            "bankAccount": null
          },
          "extensions": {}
        }
      ],
      "extensions": {
        "accountStatementRef": "STMT-2024-001"
      }
    }
  ]
}

...

Outgoing Payments (Zynergy → Bank)

Zynergy generates outgoing payment files that instruct banks to transfer funds from company accounts to creditors (suppliers, customers receiving refunds, etc.).

Supported Formats

• ISO 20022 pain.001.001.03 - SEPA Credit Transfer Initiation
• Nordea Corporate Access
• Danske Bank
• Swedbank

Data Hierarchy

The schema follows a three-level hierarchy: file/header (metadata for the entire export), payment information (batches grouped by date/account), and transactions (individual credit transfers).

Header Level

Payment Information Level

Transaction Level

Conditional Fields

Fields required based on account type or payment method:

For IBAN Accounts

For Check Payments

For Swedish Clearing (BBAN/Bankgiro)