pain001

README

golang Swiss ISO 20022 Pain.001 payment order library

Remark: This code is extracted from another project of mine and fulfills our (Genossenschaft Solutionsbüro) daily needs of automated payment order generation. It does not implement the whole specification of the Swiss standard. Further there is no safety net whatsoever. This comes without warranty of any kind. As this is about your money, think first.

Usage

A simple example which should illustrate the way of working with the library. For more information about some data format (like date, country-codes or currency-codes) please refer to the documentation or the offical implementation guidelines.

// Define the debitor (aka originator) of the transactions.
debitor := Debitor {
	Name:     "George Goodman",
	Street:   "Fnord Street",
	StreetNr: 5,
	Postcode: 2323,
	Place:    "Fnord Town",
	Country:  "FN",
	IBAN:     "FN56 1483 6012 4456 8800 0",
	BIC:      "EXP1234"
}

// Each Order can contain one or more transaction to different creditors (receivers of the money).
transactions := []Transaction{
	{
		Name:      "Joe Moon",
		Street:    "Muldon Street",
		StreetNr:  17,
		Postcode:  1717,
		Place:     "Steet Town",
		Country:   "FN",
		IBAN:      "FN56 0483 5012 3456 7800 9",
		Reference: "statuary",
		Amount:    "17.17",
		Currency:  "CFN",
	}
}

// Combine all parts into the actual bank order.
order := Order{
	ExecuteOn:    "2020-01-02",
	Debitor:      debitor,
	Transactions: transactions,
}

// Get the XML payment order and save it to the file.
xml, err := order.PaymentOrder()
if err != nil {
	log.Fatal(err)
}
if err := ioutil.WriteFile("payment-order.xml", xml, 0644); err != nil {
	log.Fatal(err)
}

Sample Output

Example of a output file:

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="http://www.six-interbank-clearing.com/de/pain.001.001.03.ch.02.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.six-interbank-clearing.com/de/pain.001.001.03.ch.02.xsd  pain.001.001.03.ch.02.xsd">
   <CstmrCdtTrfInitn>
      <GrpHdr>
         <MsgId>016dfe3b-6c81-428c</MsgId>
         <CreDtTm>2020-07-16T19:59:25</CreDtTm>
         <NbOfTxs>1</NbOfTxs>
         <CtrlSum>17.17</CtrlSum>
         <InitgPty>
            <Nm>George Goodman</Nm>
         </InitgPty>
      </GrpHdr>
      <PmtInf>
         <PmtInfId>PMTINFID-01</PmtInfId>
         <PmtMtd>TRF</PmtMtd>
         <BtchBookg>true</BtchBookg>
         <ReqdExctnDt>2020-01-02</ReqdExctnDt>
         <Dbtr>
            <Nm>George Goodman</Nm>
            <PstlAdr>
               <StrtNm>Fnord Street</StrtNm>
               <BldgNb>23</BldgNb>
               <PstCd>2323</PstCd>
               <TwnNm>Fnord Town</TwnNm>
               <Ctry>FN</Ctry>
            </PstlAdr>
         </Dbtr>
         <DbtrAcct>
            <Id>
               <IBAN>FN5614836012445688000</IBAN>
            </Id>
         </DbtrAcct>
         <DbtrAgt>
            <FinInstnId>
               <BIC>EXP1234</BIC>
            </FinInstnId>
         </DbtrAgt>
         <CdtTrfTxInf>
            <PmtId>
               <InstrId>INSTRID-01-1</InstrId>
               <EndToEndId>ENDTOENDID-1</EndToEndId>
            </PmtId>
            <PmtTpInf>
               <LclInstrm>
                  <Prtry>CH03</Prtry>
               </LclInstrm>
            </PmtTpInf>
            <Amt>
               <InstdAmt Ccy="CFN">17.17</InstdAmt>
            </Amt>
            <Cdtr>
               <Nm>Joe Moon</Nm>
               <PstlAdr>
                  <StrtNm>Muldon Street</StrtNm>
                  <BldgNb>17</BldgNb>
                  <PstCd>1717</PstCd>
                  <TwnNm>Steet Town</TwnNm>
                  <Ctry>FN</Ctry>
               </PstlAdr>
            </Cdtr>
            <CdtrAcct>
               <Id>
                  <IBAN>FN5604835012345678009</IBAN>
               </Id>
            </CdtrAcct>
            <RmtInf>
               <Ustrd>statuary</Ustrd>
            </RmtInf>
         </CdtTrfTxInf>
      </PmtInf>
   </CstmrCdtTrfInitn>
</Document>

Documentation

Overview

Package pain001 can generate Swiss ISO 20022 Pain.001 payment orders. This library does _not_ implement the whole specification. Use this at your own risk.

Index

• Constants
• type Address
• type Amount
• type CreditorTransferInformation
  • func NewCreditorTransferInformation(transaction Transaction, paymentNumber int) CreditorTransferInformation
• type CustomerCreditTransferInitiation
  • func NewCustomerCreditTransferInitiation(order Order) (CustomerCreditTransferInitiation, error)
• type Debitor
• type Document
  • func NewDocument(order Order) (Document, error)
• type GroupHeader
  • func NewGroupHeader(senderName string, numberOfTrans int, controlSum string) GroupHeader
• type Order
  • func (o Order) PaymentOrder() ([]byte, error)
• type PaymentInformation
  • func NewPaymentInformation(order Order) PaymentInformation
• type PostalAddress
• type Transaction

Constants

const DateTimeFormat = "2006-01-02T15:04:05"

DateTimeFormat represents the date and time format which is used in the standard.

Types

type Address

type Address struct {
	// Name of the organisation or person.
	Name string `xml:"Nm"`
	// Rest of the address
	PostalAddress PostalAddress `xml:"PstlAdr"`
}

Address represents a strict address structure.

type Amount

type Amount struct {
	Currency string `xml:"Ccy,attr"`
	Value    string `xml:",chardata"`
}

type CreditorTransferInformation

type CreditorTransferInformation struct {
	InstructionId string  `xml:"PmtId>InstrId"`
	EndToEndId    string  `xml:"PmtId>EndToEndId"`
	PaymentType   string  `xml:"PmtTpInf>LclInstrm>Prtry"`
	Amount        Amount  `xml:"Amt>InstdAmt"`
	Address       Address `xml:"Cdtr"`
	Iban          string  `xml:"CdtrAcct>Id>IBAN"`
	Reference     string  `xml:"RmtInf>Ustrd"`
}

CreditorTransferInformation represents one payment.

func NewCreditorTransferInformation

func NewCreditorTransferInformation(transaction Transaction, paymentNumber int) CreditorTransferInformation

NewCreditorTransferInformation returns a new CreditorTransferInformation. Needs to know, which number of payment it is.

type CustomerCreditTransferInitiation

type CustomerCreditTransferInitiation struct {
	XMLName            xml.Name           `xml:"CstmrCdtTrfInitn"`
	GroupHeader        GroupHeader        `xml:"GrpHdr"`
	PaymentInformation PaymentInformation `xml:"PmtInf"`
}

CustomerCreditTransferInitiation contains all the needed information.

func NewCustomerCreditTransferInitiation

func NewCustomerCreditTransferInitiation(order Order) (CustomerCreditTransferInitiation, error)

NewCustomerCreditTransferInitiation takes the name of the sender, the number of transactions and the sum of all transactions and returns a CustomerCreditTransferInitiation.

type Debitor

type Debitor struct {
	// Name of the debitor. Full name or company name.
	Name string
	// Street name of the debitor without the number.
	Street string
	// StreetNr is the street number of the debitor.
	StreetNr int
	// Postecode of the debitor.
	Postcode int
	// Place name of the debitor.
	Place string
	// Country code of the debitor (ex.: "CH").
	Country string
	// IBAN code of the debiting bank account.
	IBAN string
	// BIC code of the debitor's bank.
	BIC string
}

Debitor represents the payee (aka originator) of a transaction.

type Document

type Document struct {
	XMLName                          xml.Name `xml:"Document"`
	Xmlns                            string   `xml:"xmlns,attr"`
	XmlnsXid                         string   `xml:"xmlns:xsi,attr"`
	XsiSchemaLocation                string   `xml:"xsi:schemaLocation,attr"`
	CustomerCreditTransferInitiation CustomerCreditTransferInitiation
}

Document is the root structure of the payment statement.

func NewDocument

func NewDocument(order Order) (Document, error)

NewDocument returns a new document.

type GroupHeader

type GroupHeader struct {
	// Unique identification of the payment document. Bank system will reject two files with the same identifier.
	MessageIdentification string `xml:"MsgId"`
	// Date and time of the creation of the file.
	CreationDateTime string `xml:"CreDtTm"`
	// The number of total transactions in the document.
	NumbersOfTransactions int `xml:"NbOfTxs"`
	// Sum of all transactions
	ControlSum string `xml:"CtrlSum"`
	// The name of the organization/person which sends the money.
	Name string `xml:"InitgPty>Nm"`
}

GroupHeader represents a Group Header item.

func NewGroupHeader

func NewGroupHeader(senderName string, numberOfTrans int, controlSum string) GroupHeader

NewGroupHeader takes an convert.Sender object and the number of transitions as parameters and returns a GroupHeader.

type Order

type Order struct {
	// ExecuteOn states the date of execution in the `YYYY-MM-DD` format
	ExecuteOn string
	// Debitor the payee of the transactions.
	Debitor Debitor
	// Transactions the payments to be generated.
	Transactions []Transaction
}

Order represents one or more transactions of one debitor.

func (Order) PaymentOrder

func (o Order) PaymentOrder() ([]byte, error)

PaymentOrder returns the ISO 20022 Pain.001 XML represenation of the order.

type PaymentInformation

type PaymentInformation struct {
	PaymentInformationId        string                        `xml:"PmtInfId"`
	PaymentMethod               string                        `xml:"PmtMtd"`
	BatchBooking                bool                          `xml:"BtchBookg"`
	RequiredExecutionDate       string                        `xml:"ReqdExctnDt"`
	Debitor                     Address                       `xml:"Dbtr"`
	DebitorIban                 string                        `xml:"DbtrAcct>Id>IBAN"`
	DebitorBic                  string                        `xml:"DbtrAgt>FinInstnId>BIC"`
	CreditorTransferInformation []CreditorTransferInformation `xml:"CdtTrfTxInf"`
}

PaymentInformation contains most of the payment information. For more information please refer to the standard.

func NewPaymentInformation

func NewPaymentInformation(order Order) PaymentInformation

NewPaymentInformation takes an Order as an argument and returns a new PaymentInformation.

type PostalAddress

type PostalAddress struct {
	StreetName   string `xml:"StrtNm"`
	StreetNumber int    `xml:"BldgNb"`
	PostalCode   int    `xml:"PstCd"`
	TownName     string `xml:"TwnNm"`
	// Use two char abbreviation in upper case (ex.: CH, DE, FR)
	Country string `xml:"Ctry"`
}

PostalAddress contains all address information except for the name.

type Transaction

type Transaction struct {
	// Name full name or company name of the creditor.
	Name string
	// Street name of the creditor without the number.
	Street string
	// StreetNr is the street number of the creditor.
	StreetNr int
	// Postecode of the creditor.
	Postcode int
	// Place name of the creditor.
	Place string
	// Country code of the creditor (ex.: "CH").
	Country string
	// IBAN code of the creditors bank account.
	IBAN string
	// Reference is the comment/description the creditor will see upon receiving the transaction.
	Reference string
	// Amount is the amount of money to be transferred.
	Amount string
	// Currency of the transaction (ex: "CHF").
	Currency string
}

Transaction is one payment order from the debitor to the creditor (aka receiver of the money).