Bank Integration Service - Zynergy Requirements

This document outlines what data Zynergy needs from 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.

1. Payment Formats

Zynergy processes the following 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)

2. What Zynergy Needs

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

2.1 File-Level Fields

These fields identify the file and enable duplicate detection:

2.2 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

2.3 Suggested Fields

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

2.4 Extensions (Format-Specific Data)

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

• Not required for core payment processing
• Useful for troubleshooting, auditing, and display purposes
• Variable across formats (most fields only exist in 1-3 formats)

How Extensions Work

The service returns format-specific data in an extensions object at both header and transaction levels. Consuming systems can:

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

This approach keeps the core schema stable while allowing format-specific richness.

Example Extension Fields

3. Proposed 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"
      }
    }
  ]
}