Zynergy Payment Requirements

This document outlines the data requirements for a Bank Integration Service 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.

...

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:

• 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

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)