Outgoing Payment Field Mapping

ISO20022 pain.001.001.03 - Customer Credit Transfer Initiation

This document defines the mapping between ProBill database fields and ISO20022 XML structure for outgoing payments (utbetalningar).

1. GROUP HEADER (GrpHdr) - File Level

ProBill Source	ISO20022 XML Path	Required	Data Type	Notes
@FileID parameter	GrpHdr/MsgId	REQUIRED	String(35)	Unique message identifier for the file
SYSDATETIME()	GrpHdr/CreDtTm	REQUIRED	DateTime	ISO8601 format: YYYY-MM-DDTHH:MM:SS
COUNT all transactions	GrpHdr/NbOfTxs	REQUIRED	Integer	Total number of payment transactions in file
SUM(Amount) all transactions	GrpHdr/CtrlSum	REQUIRED	Decimal	Total of all transaction amounts (control sum)
Swedbank: \ PaymentAccount.SwedbankAgreementID \ \ Nordea: \ PaymentAccount.NordeaSignerID	GrpHdr/InitgPty/Id/OrgId/Othr/Id	REQUIRED	String(35)	Bank-specific initiating party identifier
Swedbank: 'BANK' \ Nordea: 'CUST'	GrpHdr/InitgPty/Id/OrgId/Othr/SchmeNm/Cd	REQUIRED	String(4)	Identification scheme code

2. PAYMENT INFORMATION (PmtInf) - Batch Level

ProBill Source	ISO20022 XML Path	Required	Data Type	Notes
@FileID parameter	PmtInf/PmtInfId	REQUIRED	String(35)	Payment information identifier
Based on PayoutTypeID: \ • 'TRF' = Transfers (1,3,4) \ • 'CHK' = Money orders (2)	PmtInf/PmtMtd	REQUIRED	String(3)	Payment method code
COUNT in batch	PmtInf/NbOfTxs	REQUIRED	Integer	Number of transactions in this payment batch
SUM(Amount) in batch	PmtInf/CtrlSum	REQUIRED	Decimal	Control sum for this payment batch
Literal: 'NORM'	PmtInf/PmtTpInf/InstrPrty	REQUIRED	String(4)	Instruction priority (Normal)
Literal: 'MPNS'	PmtInf/PmtTpInf/SvcLvl/Prtry	REQUIRED	String(35)	Proprietary service level (mandatory for BG/PG)
Literal: 'SUPP'	PmtInf/PmtTpInf/CtgyPurp/Cd	REQUIRED	String(4)	Category purpose code (Supplier payment)
CONVERT(VARCHAR(12), SYSDATETIME(), 23)	PmtInf/ReqdExctnDt	REQUIRED	Date	Requested execution date: YYYY-MM-DD
PaymentAccount.CustomerNumber	PmtInf/Dbtr/Nm	REQUIRED	String(140)	Debtor name (company/organization name)
Literal: 'SE'	PmtInf/Dbtr/PstlAdr/Ctry	REQUIRED	String(2)	Debtor country code (ISO 3166-1 alpha-2)
Nordea: \ PaymentAccount.NordeaOrgID \ Fallback: \ PaymentAccount.PayoutOrgID	PmtInf/Dbtr/Id/OrgId/Othr/Id	REQUIRED	String(35)	Debtor organization number
Literal: 'BANK'	PmtInf/Dbtr/Id/OrgId/Othr/SchmeNm/Cd	REQUIRED	String(4)	Organization ID scheme code
REPLACE(PaymentAccount.IBAN, ' ', '')	PmtInf/DbtrAcct/Id/IBAN	CONDITIONAL	String(34)	REQUIRED if using IBAN \ Mutually exclusive with Othr/Id
Swedbank: \ REPLACE(PaymentAccount.OutBankgiroNumber, '-', '') \ Nordea/Others: \ REPLACE(PaymentAccount.OutPlusgiroNumber, '-', '')	PmtInf/DbtrAcct/Id/Othr/Id	CONDITIONAL	String(34)	REQUIRED if not using IBAN \ Account number (cleaned)
'BBAN' (if not BG)	PmtInf/DbtrAcct/Id/Othr/SchmeNm/Cd	CONDITIONAL	String(4)	When using Othr/Id with BBAN format
'BGNR' (if Bankgiro)	PmtInf/DbtrAcct/Id/Othr/SchmeNm/Prtry	CONDITIONAL	String(35)	When using Bankgiro as debtor account
Currency.ExternalID \ Default: 'SEK'	PmtInf/DbtrAcct/Ccy	REQUIRED	String(3)	Debtor account currency (ISO 4217)
PaymentAccount.BIC	PmtInf/DbtrAgt/FinInstnId/BIC	REQUIRED	String(11)	Bank Identifier Code (SWIFT)
Literal: 'SE'	PmtInf/DbtrAgt/FinInstnId/PstlAdr/Ctry	REQUIRED	String(2)	Bank country code

3. CREDIT TRANSFER TRANSACTION (CdtTrfTxInf) - Per Payment

3.1 Payment Identification & Amount

ProBill Source	ISO20022 XML Path	Required	Data Type	Notes
LedgerPayout.ID	CdtTrfTxInf/PmtId/EndToEndId	REQUIRED	String(35)	Unique transaction identifier for tracking
Currency.ExternalID	CdtTrfTxInf/Amt/InstdAmt/@Ccy	REQUIRED	String(3)	Currency attribute (e.g., "SEK", "EUR")
ISNULL(LedgerPayout.CurrencyAmount, LedgerPayout.Amount)	CdtTrfTxInf/Amt/InstdAmt	REQUIRED	Decimal(18,2)	Instructed amount (use CurrencyAmount if foreign currency)

3.2 Creditor Agent (Recipient Bank)

ProBill Source	ISO20022 XML Path	Required	Data Type	Notes
Based on PayoutTypeID: \ • 'SESBA' if PG/BG/Bank with clearing	CdtTrfTxInf/CdtrAgt/FinInstnId/ClrSysMmbId/ClrSysId/Cd	CONDITIONAL	String(5)	Swedish Banking Association clearing system
Based on PayoutTypeID: \ • '9900' = Bankgiro (4) \ • '9960' = Plusgiro (3) \ • 4-digit = Bank clearing (1) \ • NULL = Money order (2)	CdtTrfTxInf/CdtrAgt/FinInstnId/ClrSysMmbId/MmbId	CONDITIONAL	String(35)	Clearing member ID \ Extracted via FnPrGetClearingsNrFromAccountNr()

3.3 Creditor (Recipient)

ProBill Source	ISO20022 XML Path	Required	Data Type	Notes
{{COALESCE( \ CustomerContactInformation.Name, \ Customer.DispName1 \ )}}	CdtTrfTxInf/Cdtr/Nm	REQUIRED	String(140)	Creditor/recipient name
{{ISNULL( \ CustomerContactInformation.Address, \ Customer.DispAddress \ )}}	CdtTrfTxInf/Cdtr/PstlAdr/StrtNm	CONDITIONAL	String(70)	REQUIRED for money orders (TypeID=2 only)
{{REPLACE( \ ISNULL( \ CustomerContactInformation.Zipcode, \ Customer.Zipcode \ ), ' ', '' \ )}}	CdtTrfTxInf/Cdtr/PstlAdr/PstCd	CONDITIONAL	String(16)	REQUIRED for money orders (TypeID=2 only) \ Spaces removed
{{ISNULL( \ CustomerContactInformation.City, \ Customer.City \ )}}	CdtTrfTxInf/Cdtr/PstlAdr/TwnNm	CONDITIONAL	String(35)	REQUIRED for money orders (TypeID=2 only)
{{COALESCE( \ Country.IsoCode, \ 'SE' \ )}}	CdtTrfTxInf/Cdtr/PstlAdr/Ctry	REQUIRED	String(2)	Creditor country code

3.4 Creditor Account (Recipient Account)

ProBill Source	ISO20022 XML Path	Required	Data Type	Notes
Money order (TypeID=2): \ Literal: 'NOTPROVIDED' \ \ Others: \ {{FnPrCleanPayoutAccountNumber( \ COALESCE( \ BillLocation.PayoutAccount, \ Customer.PayoutAccount, \ LedgerPayout.AccountNumber \ ) \ )}}	CdtTrfTxInf/CdtrAcct/Id/Othr/Id	REQUIRED	String(34)	Recipient account number \ Cleaned of dashes, spaces, special chars \ Money orders use literal 'NOTPROVIDED'
'BBAN' if Bank (1) or PG (3)	CdtTrfTxInf/CdtrAcct/Id/Othr/SchmeNm/Cd	CONDITIONAL	String(4)	Account scheme code for BBAN format
'BGNR' if Bankgiro (4)	CdtTrfTxInf/CdtrAcct/Id/Othr/SchmeNm/Prtry	CONDITIONAL	String(35)	Proprietary scheme for Bankgiro

3.5 Remittance Information (Payment Reference)

Structured Remittance (for Plusgiro/Bankgiro)

ProBill Source	ISO20022 XML Path	Required	Data Type	Notes
Swedbank: \ 'CINV' (if invoice exists) \ \ Nordea: \ 'SCOR' (if invoice exists)	Swedbank: \ CdtTrfTxInf/RmtInf/Strd/RfrdDocInf/Tp/CdOrPrtry/Cd \ \ Nordea: \ CdtTrfTxInf/RmtInf/Strd/CdtrRefInf/Tp/CdOrPrtry/Cd	OPTIONAL	String(4)	Document type code (if invoice reference provided)
{{COALESCE( \ CAST(Invoice.InvoiceNumber AS VARCHAR(100)), \ CAST(Invoice2.InvoiceNumber AS VARCHAR(100)), \ CAST(Payment.ReferenceID AS VARCHAR(100)) \ )}}	Swedbank: \ CdtTrfTxInf/RmtInf/Strd/RfrdDocInf/Nb \ \ Nordea: \ CdtTrfTxInf/RmtInf/Strd/CdtrRefInf/Ref	OPTIONAL	String(25/35)	Invoice/reference number \ Swedbank: max 25 chars \ Nordea: max 35 chars
Currency.ExternalID	CdtTrfTxInf/RmtInf/Strd/RfrdDocAmt/RmtdAmt/@Ccy	OPTIONAL	String(3)	Currency attribute for remitted amount
{{ISNULL( \ LedgerPayout.CurrencyAmount, \ LedgerPayout.Amount \ )}}	CdtTrfTxInf/RmtInf/Strd/RfrdDocAmt/RmtdAmt	OPTIONAL	Decimal(18,2)	Remitted document amount

Unstructured Remittance (for Bank accounts)

ProBill Source	ISO20022 XML Path	Required	Data Type	Notes
{{COALESCE( \ CAST(Invoice.InvoiceNumber AS VARCHAR(100)), \ CAST(Invoice2.InvoiceNumber AS VARCHAR(100)), \ CAST(Payment.ReferenceID AS VARCHAR(100)) \ )}}	CdtTrfTxInf/RmtInf/Ustrd	OPTIONAL	String(140)	Unstructured remittance information \ Shown only for bank account transfers

4. PayoutTypeID Logic & Account Format Rules

Payment Type Mapping

Account Number Cleaning Function

-- FnPrCleanPayoutAccountNumber removes:
• Dashes (-)
• Spaces ( )
• Slashes (/, \)
• Dots (.)
• Special characters

Result: Pure numeric string for Swedish accounts

Clearing Number Extraction

-- FnPrGetClearingsNrFromAccountNr extracts:
For Bank Accounts (TypeID=1):
  • First 4 digits of account number
  • Used in CdtrAgt/FinInstnId/ClrSysMmbId/MmbId

For Plusgiro (TypeID=3):
  • Returns fixed value: '9960'

For Bankgiro (TypeID=4):
  • Returns fixed value: '9900'

For Money Orders (TypeID=2):
  • Returns NULL (not applicable)

5. Bank-Specific Variations

Swedbank Implementation

Key Differences:

• Uses SwedbankAgreementID for InitgPty identification
• Requires OutBankgiroNumber field in PaymentAccount
• Creates separate <PmtInf> segments for TRF and CHK methods:
  • PmtInfId = @FileID for TRF transactions
  • PmtInfId = @FileID + 1 for CHK transactions (money orders)
• Uses 'CINV' code in structured remittance (RfrdDocInf/Tp/CdOrPrtry/Cd)
• Reference number in RfrdDocInf/Nb (max 25 characters)

Required Configuration:

PaymentAccount.SwedbankAgreementID  -- NOT NULL
PaymentAccount.OutBankgiroNumber    -- NOT NULL
PaymentAccount.BIC                  -- NOT NULL
PaymentAccount.PayoutOrgID          -- NOT NULL

Nordea Implementation

Key Differences:

• Uses NordeaSignerID for InitgPty identification
• Prefers IBAN format for DbtrAcct/Id/IBAN
• Falls back to OutPlusgiroNumber/OutBankgiroNumber if no IBAN
• Uses 'SCOR' code in structured remittance (CdtrRefInf/Tp/CdOrPrtry/Cd)
• Reference number in CdtrRefInf/Ref (max 35 characters)
• Single <PmtInf> segment for all payment methods
• Optional secure envelope wrapping via spPrSecureEnvelope

Required Configuration:

PaymentAccount.NordeaSignerID       -- NOT NULL
PaymentAccount.NordeaSenderID       -- NOT NULL (if using secure envelope)
PaymentAccount.BIC                  -- NOT NULL
PaymentAccount.IBAN                 -- Preferred, or fallback to PG/BG
PaymentAccount.NordeaOrgID          -- Preferred, or fallback to PayoutOrgID

6. Validation Rules & Business Logic

Amount Validation

✓ Amount must be > 0
✓ Use CurrencyAmount if LedgerPayout.CurrencyID is set
✓ CtrlSum must match SUM of all transaction amounts
✓ NbOfTxs must match COUNT of all transactions

Date Handling

• ReqdExctnDt calculated with weekend adjustment:
  - Friday → Monday (+3 days)
  - Saturday → Monday (+2 days)
  - Sunday → Monday (+1 day)
  - Weekday → Next day (+N days based on AppSetting 'PayoutPlacementDateDays')

Account Number Rules

Swedish Format Requirements:
• Bank: 4-digit clearing + 7-12 digit account
• Plusgiro: 1-8 digits (may include control digit)
• Bankgiro: 7-8 digits (format: XXXX-XXXX)
• All cleaned before export (no formatting chars)

Currency Handling

Domestic (SEK):
  • CurrencyID = 4 (or NULL defaults to SEK)
  • Amount field used directly
  • Currency/@Ccy = 'SEK'

Foreign Currency:
  • CurrencyID set to non-SEK currency
  • CurrencyAmount must be populated
  • Use CurrencyAmount for Amt/InstdAmt
  • Currency/@Ccy = Currency.ExternalID (e.g., 'EUR', 'USD')

Address Requirements for Money Orders

All three fields REQUIRED when PayoutTypeID = 2:
  ✓ Cdtr/PstlAdr/StrtNm   (Street address)
  ✓ Cdtr/PstlAdr/PstCd    (Postal code, no spaces)
  ✓ Cdtr/PstlAdr/TwnNm    (Town/city name)

Missing any field → Payment rejected/error logged

Reference Number Rules

Structured Remittance (PG/BG):
  • Swedbank: Max 25 characters in RfrdDocInf/Nb
  • Nordea: Max 35 characters in CdtrRefInf/Ref
  • Used for invoice numbers or payment references

Unstructured Remittance (Bank accounts):
  • Max 140 characters in Ustrd
  • Typically shows first 12 chars in practice
  • Used when PayoutTypeID NOT IN (3, 4)

7. Error Handling & Status Tracking

LedgerPayout Status Flow

StatusID = 0  →  Ej behandlad (Not processed)
           ↓
StatusID = 1  →  Utbetalning skickad (Payment sent to bank)
           ↓
StatusID = 2  →  Utbetalning utförd (Payment completed)
OR
StatusID = 3  →  Utbetalning nekad (Payment rejected)

Validation Failures

When validation fails, payment is removed from batch and logged:

• ErrorData field populated with error description
• StatusID remains 0 (not processed)
• PrSys.ExtUpdate notified for client refresh
• Examples:
  - "Utbetalningstyp och Konto, utbetalning ej komplett uppsatt"
  - "Ingen BIC i PaymentAccount"
  - "Inget PlusGiro, BankGiro eller IBAN i PaymentAccount"

File Generation Tracking

LedgerPayout.FileID = @FileID  →  Links payment to export file
LedgerPayout.Handled = GETDATE()  →  Timestamp of export
LedgerEvent.StatusID updated based on PayoutAwaitResponse setting

8. Database Tables & Relationships

Primary Tables

LedgerPayout (Main payout record)

ID              INT             -- Used as EndToEndId in XML
LedgerEventID   INT             -- Link to accounting event
BillLocationID  INT             -- Link to billing location
CustomerID      INT             -- Link to customer
Amount          NUMERIC(18,2)   -- Base amount (SEK)
CurrencyAmount  NUMERIC(18,2)   -- Foreign currency amount
CurrencyID      SMALLINT        -- Foreign currency ID
TypeID          INT             -- PayoutTypeID (1-5)
StatusID        INT             -- Processing status
AccountNumber   NVARCHAR(40)    -- Recipient account
Name/CareOf/Address/Zipcode/City  -- Recipient address info
FileID          INT             -- Export file reference
TransactionDate DATE            -- Transaction/placement date

PaymentAccount (Sender configuration)

ID                      INT
CustomerNumber          NVARCHAR(80)    -- Company name (Dbtr/Nm)
BIC                     VARCHAR(11)     -- Bank BIC
IBAN                    VARCHAR(34)     -- Debtor IBAN
OutPlusgiroNumber       VARCHAR(20)     -- Outgoing Plusgiro
OutBankgiroNumber       VARCHAR(50)     -- Outgoing Bankgiro (NEW)
PayoutOrgID             VARCHAR(20)     -- Organization number
NordeaOrgID             VARCHAR(36)     -- Nordea org ID
NordeaSignerID          VARCHAR(50)     -- Nordea signer
NordeaSenderID          VARCHAR(50)     -- Nordea sender
SwedbankAgreementID     VARCHAR(35)     -- Swedbank agreement
CompanyGroupID          INT             -- Links to Company.GroupID

Customer / BillLocation (Recipient info)

-- Recipient details hierarchy:
1. CustomerContactInformation (ContactInformationTypeID=3)
   - Name, Address, Zipcode, City
2. Customer (fallback)
   - DispName1, DispAddress, Zipcode, City
3. BillLocation (account override)
   - PayoutAccount, PayoutTypeID

Key Relationships

LedgerPayout
  ├─> LedgerEvent (accounting)
  ├─> BillLocation (PayoutAccount override, PayoutTypeID)
  ├─> Customer (recipient info, PayoutAccount, PayoutTypeID)
  ├─> Currency (foreign currency)
  └─> Invoice (via LedgerEvent, for remittance info)

PaymentAccount
  └─> Company.GroupID (multi-company support)

9. Sample SQL Query for Data Extraction

-- Example: Extract data for payment batch export
SELECT
    -- Transaction ID
    lp.ID AS EndToEndId,

    -- Amount
    ISNULL(lp.CurrencyAmount, lp.Amount) AS Amount,
    ISNULL(cu.ExternalID, 'SEK') AS Currency,

    -- Recipient Info
    COALESCE(cci.Name, c.DispName1) AS CreditorName,
    COALESCE(bl.PayoutAccount, c.PayoutAccount, lp.AccountNumber) AS CreditorAccount,
    ISNULL(bl.PayoutTypeID, c.PayoutTypeID) AS PayoutTypeID,

    -- Recipient Address (for money orders)
    ISNULL(cci.Address, c.DispAddress) AS StreetName,
    REPLACE(ISNULL(cci.Zipcode, c.Zipcode), ' ', '') AS PostalCode,
    ISNULL(cci.City, c.City) AS TownName,
    COALESCE(co.IsoCode, 'SE') AS Country,

    -- Remittance Info
    COALESCE(i.InvoiceNumber, i2.InvoiceNumber, p.ReferenceID) AS Reference,

    -- Payment Account Info
    pa.CustomerNumber AS DebtorName,
    pa.BIC,
    pa.IBAN,
    pa.OutBankgiroNumber,
    pa.OutPlusgiroNumber,
    pa.PayoutOrgID

FROM
    dbo.LedgerPayout lp
    INNER JOIN dbo.LedgerEvent le ON le.ID = lp.LedgerEventID
    INNER JOIN dbo.BillLocation bl ON bl.ID = lp.BillLocationID
    INNER JOIN dbo.V_RepCustomer c ON c.ID = lp.CustomerID
    INNER JOIN dbo.PaymentAccount pa ON pa.ID = @PaymentAccountID
    LEFT JOIN dbo.Currency cu ON cu.ID = lp.CurrencyID
    LEFT JOIN dbo.CustomerContactInformation cci ON cci.CustomerID = c.ID
        AND cci.ContactInformationTypeID = 3 AND cci.IsDeleted = 0
    LEFT JOIN dbo.Country co ON co.ID = ISNULL(cci.CountryID, c.CountryID)
    LEFT JOIN dbo.Payment p ON p.ID = le.PaymentID
    LEFT JOIN dbo.Invoice i ON i.ID = le.ReferencedInvoiceID
    LEFT JOIN dbo.Invoice i2 ON i2.ID = p.InvoiceID

WHERE
    lp.StatusID = 0  -- Not processed
    AND le.StatusID = 4  -- Approved for payout
    AND lp.TypeID != 5  -- Exclude Autogiro
    AND ISNULL(lp.CurrencyID, 4) = @CurrencyID

ORDER BY lp.ID

10. Configuration Checklist

Before First Export

PaymentAccount Setup (per company/bank)

• CustomerNumber populated
• BIC code configured
• Organization number (PayoutOrgID) set
• Bank-specific IDs configured (SwedbankAgreementID or NordeaSignerID)
• At least one account number set (IBAN, OutPlusgiroNumber, or OutBankgiroNumber)

System Settings (PrSys.AppSetting)

• PayoutPlacementDateDays = Days ahead for placement (default: 0)
• PayoutAwaitResponse = Wait for bank confirmation? (0/1)
• EventForDeleteAndPayout = Create offsetting ledger events? (0/1)

Customer/BillLocation Data Quality

• PayoutTypeID set correctly (1-5)
• PayoutAccount populated when PayoutTypeID requires it
• Both fields set together (PayoutTypeID + PayoutAccount)
• Address complete for money order recipients (TypeID=2)

Currency Configuration

• Currency.ExternalID uses ISO 4217 codes (SEK, EUR, USD, etc.)
• CurrencyAmount populated when using foreign currency
• Default currency ID = 4 (SEK) in your installation

11. Reference Information

ISO20022 Message Standards

• pain.001.001.03 - Customer Credit Transfer Initiation
• Namespace: urn:iso:std:iso:20022:tech:xsd:pain.001.001.03
• Schema validation recommended before bank submission

Swedish Payment System Codes

• SESBA - Swedish Bankers' Association clearing system
• 9900 - Standard clearing code for all Bankgiro numbers
• 9960 - Standard clearing code for all Plusgiro numbers
• BBAN - Basic Bank Account Number (domestic format)
• BGNR - Bankgiro Number (proprietary Swedish format)

Contact & Support

For questions about implementation or field mapping, reference:

• ProBill stored procedure: dbo.spPrPayoutCreate
• Swedbank variant: dbo.spPrPayoutCreate_Swedbank
• Helper functions: dbo.FnPrCleanPayoutAccountNumber, dbo.FnPrGetClearingsNrFromAccountNr

Document Version: 1.0
Last Updated: 2026-01-30
Based on: ProBillDB version 2.0.4751.0+