Ruby gem for creating SEPA XML files (with CH-DD extension)

Fork by Garaio

Why this Fork?

Beginning with 2018 the Swiss Postfinance Organization will switch from their DTA Format to the ISO20022 Standard.

Sadly they have changed the ISO20022 Standard to have a Swiss specific core which diverges from the SEPA Standard.

This Fork is to give SepaKing the ability to generate PaymentInitiation File (pain.008.001.02.ch.03) according to the Swiss CH-DD Norm.

Upstream

The goal is to have this changes pushed upstream once we feel that they are mature enough to be pushed into SepaKing.

Introduction

We love building payment applications! So after developing the DTAUS library for Ruby we move on with SEPA.

Features

This gem implements the following two messages out of the ISO 20022 standard:

Credit Transfer Initiation (pain.001.003.03, pain.001.002.03 and pain.001.001.03)
Direct Debit Initiation (pain.008.003.02, pain.008.002.02 and pain.008.001.02)

It handles the Specification of Data Formats v2.7 (2013-11-04).

BTW: pain is a shortcut for Payment Initiation.

Requirements

Ruby 2.0.0 or newer
ActiveModel 3.0 or newer

Installation

gem install sepa_king

Usage

How to create the XML for Direct Debit Initiation (in German: "Lastschriften")

# First: Create the main object
sdd = SEPA::DirectDebit.new(
  # Name of the initiating party and creditor, in German: "Auftraggeber"
  # String, max. 70 char
  name:       'Gläubiger GmbH',

  # OPTIONAL: Business Identifier Code (SWIFT-Code) of the creditor
  # String, 8 or 11 char
  bic:        'BANKDEFFXXX',

  # International Bank Account Number of the creditor
  # String, max. 34 chars
  iban:       'DE87200500001234567890',

  # Creditor Identifier, in German: Gläubiger-Identifikationsnummer
  # String, max. 35 chars
  creditor_identifier: 'DE98ZZZ09999999999'
)

# Second: Add transactions
sdd.add_transaction(
  # Name of the debtor, in German: "Zahlungspflichtiger"
  # String, max. 70 char
  name:                      'Zahlemann & Söhne GbR',

  # OPTIONAL: Business Identifier Code (SWIFT-Code) of the debtor's account
  # String, 8 or 11 char
  bic:                       'SPUEDE2UXXX',

  # International Bank Account Number of the debtor's account
  # String, max. 34 chars
  iban:                      'DE21500500009876543210',

  # Amount in EUR
  # Number with two decimal digit
  amount:                    39.99,

  # OPTIONAL: Instruction Identification, will not be submitted to the debtor
  # String, max. 35 char
  instruction:               '12345',

  # OPTIONAL: End-To-End-Identification, will be submitted to the debtor
  # String, max. 35 char
  reference:                 'XYZ/2013-08-ABO/6789',

  # OPTIONAL: Unstructured remittance information, in German "Verwendungszweck"
  # String, max. 140 char
  remittance_information:    'Vielen Dank für Ihren Einkauf!',

  # Mandate identifikation, in German "Mandatsreferenz"
  # String, max. 35 char
  mandate_id:                'K-02-2011-12345',

  # Mandate Date of signature, in German "Datum, zu dem das Mandat unterschrieben wurde"
  # Date
  mandate_date_of_signature: Date.new(2011,1,25),

  # Local instrument, in German "Lastschriftart"
  # One of these strings:
  #   'CORE' ("Basis-Lastschrift")
  #   'COR1' ("Basis-Lastschrift mit verkürzter Vorlagefrist")
  #   'B2B' ("Firmen-Lastschrift")
  local_instrument: 'CORE',

  # Sequence type
  # One of these strings:
  #   'FRST' ("Erst-Lastschrift")
  #   'RCUR' ("Folge-Lastschrift")
  #   'OOFF' ("Einmalige Lastschrift")
  #   'FNAL' ("Letztmalige Lastschrift")
  sequence_type: 'OOFF',

  # OPTIONAL: Requested collection date, in German "Fälligkeitsdatum der Lastschrift"
  # Date
  requested_date: Date.new(2013,9,5),

  # OPTIONAL: Enables or disables batch booking, in German "Sammelbuchung / Einzelbuchung"
  # True or False
  batch_booking: true

  # OPTIONAL: Use a different creditor account
  # CreditorAccount
  creditor_account: SEPA::CreditorAccount.new(
    name:                'Creditor Inc.',
    bic:                 'RABONL2U',
    iban:                'NL08RABO0135742099',
    creditor_identifier: 'NL53ZZZ091734220000'
  )
)
sdd.add_transaction ...

# Last: create XML string
xml_string = sdd.to_xml # Use latest schema pain.008.003.02
xml_string = sdd.to_xml('pain.008.002.02') # Use former schema pain.008.002.02

How to create the XML for Credit Transfer Initiation (in German: "Überweisungen")

# First: Create the main object
sct = SEPA::CreditTransfer.new(
  # Name of the initiating party and debtor, in German: "Auftraggeber"
  # String, max. 70 char
  name: 'Schuldner GmbH',

  # OPTIONAL: Business Identifier Code (SWIFT-Code) of the debtor
  # String, 8 or 11 char
  bic:  'BANKDEFFXXX',

  # International Bank Account Number of the debtor
  # String, max. 34 chars
  iban: 'DE87200500001234567890'
)

# Second: Add transactions
sct.add_transaction(
  # Name of the creditor, in German: "Zahlungsempfänger"
  # String, max. 70 char
  name:                   'Telekomiker AG',

  # OPTIONAL: Business Identifier Code (SWIFT-Code) of the creditor's account
  # String, 8 or 11 char
  bic:                    'PBNKDEFF370',

  # International Bank Account Number of the creditor's account
  # String, max. 34 chars
  iban:                   'DE37112589611964645802',

  # Amount in EUR
  # Number with two decimal digit
  amount:                 102.50,

  # OPTIONAL: Instruction Identification, will not be submitted to the creditor
  # String, max. 35 char
  instruction:               '12345',

  # OPTIONAL: End-To-End-Identification, will be submitted to the creditor
  # String, max. 35 char
  reference:              'XYZ-1234/123',

  # OPTIONAL: Unstructured remittance information, in German "Verwendungszweck"
  # String, max. 140 char
  remittance_information: 'Rechnung vom 22.08.2013',

  # OPTIONAL: Requested execution date, in German "Ausführungstermin"
  # Date
  requested_date: Date.new(2013,9,5),

  # OPTIONAL: Enables or disables batch booking, in German "Sammelbuchung / Einzelbuchung"
  # True or False
  batch_booking: true,

  # OPTIONAL: Urgent Payment
  # One of these strings:
  #   'SEPA' ("SEPA-Zahlung")
  #   'URGP' ("Taggleiche Eilüberweisung")
  service_level: 'URGP'
)
sct.add_transaction ...

# Last: create XML string
xml_string = sct.to_xml # Use latest schema pain.001.003.03
xml_string = sct.to_xml('pain.001.002.03') # Use former schema pain.001.002.03

Validations

You can rely on our internal validations, raising errors when needed, during message creation. To validate your models holding SEPA related information (e.g. BIC, IBAN, mandate_id) you can use our validator classes or rely on some constants.

Examples:

class BankAccount < ActiveRecord::Base
  # IBAN validation, by default it validates the attribute named "iban"
  validates_with SEPA::IBANValidator, field_name: :iban_the_terrible

  # BIC validation, by default it validates the attribute named "bic"
  validates_with SEPA::BICValidator, field_name: :bank_bic
end

class Payment < ActiveRecord::Base
  validates_inclusion_of :sepa_sequence_type, in: SEPA::DirectDebitTransaction::SEQUENCE_TYPES

  # Mandate ID validation, by default it validates the attribute named "mandate_id"
  validates_with SEPA::MandateIdentifierValidator, field_name: :mandate_id
end

Beware: The SEPA::IBANValidator is strict - e.g. it does not allow any spaces in the IBAN.

Also see:

Changelog

https://github.com/salesking/sepa_king/releases

Contributors

https://github.com/salesking/sepa_king/graphs/contributors

Resources

http://www.ebics.de/index.php?id=77
SalesKing: http://salesking.eu

License

Released under the MIT license

Garaio-REM/sepa_king