• Stars
    star
    150
  • Rank 247,323 (Top 5 %)
  • Language
    Ruby
  • License
    MIT License
  • Created about 11 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Ruby gem for creating SEPA XML files

Ruby gem for creating SEPA XML files

Build Status Code Climate Coverage Status Gem Version

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 v3.3 (2019-11-17).

BTW: pain is a shortcut for Payment Initiation.

Requirements

  • Ruby 2.7 or newer
  • ActiveModel 4.2 or newer (including 7.0)

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
  # Number with two decimal digit
  amount:                    39.99,

  # OPTIONAL: Currency, EUR by default (ISO 4217 standard)
  # String, 3 char
  currency:                  'EUR',

  # 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'
  )

  # OPTIONAL: Specify the country & address of the debtor (REQUIRED for SEPA debits outside of EU. The individually required fields depend on the target country)
  debtor_address: SEPA::DebtorAddress.new(
    country_code:        'CH',
    # Not required if individual fields are used
    address_line1:       'Mustergasse 123a',
    address_line2:       '1234 Musterstadt'
    # Not required if address_line1 and address_line2 are used
    street_name:         'Mustergasse',
    building_number:     '123a',
    post_code:           '1234',
    town_name:           'Musterstadt'
  )
)
sdd.add_transaction ...

# Last: create XML string
xml_string = sdd.to_xml                    # Use schema pain.008.001.02
xml_string = sdd.to_xml('pain.008.002.02') # Use 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
  # Number with two decimal digit
  amount:                 102.50,

  # OPTIONAL: Currency, EUR by default (ISO 4217 standard)
  # String, 3 char
  currency:               'EUR',

  # 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'

  # OPTIONAL: Unstructured information to indicate the purpose of the payment
  # String, max. 4 char
  category_purpose:         'SALA',

  # OPTIONAL: Specify the country & address of the creditor (REQUIRED for SEPA debits outside of EU. The individually required fields depend on the target country)
  creditor_address: SEPA::CreditorAddress.new(
    country_code:        'CH',
    # Not required if individual fields are used
    address_line1:       'Mustergasse 123a',
    address_line2:       '1234 Musterstadt'
    # Not required if address_line1 and address_line2 are used
    street_name:         'Mustergasse',
    building_number:     '123a',
    post_code:           '1234',
    town_name:           'Musterstadt'
  )
)
sct.add_transaction ...

# Last: create XML string
xml_string = sct.to_xml                    # Use schema pain.001.001.03
xml_string = sct.to_xml('pain.001.002.03') # Use 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

License

Released under the MIT license

Copyright (c) 2013-2022 Georg Leciejewski (SalesKing), Georg Ledermann (https://github.com/ledermann)

More Repositories

1

json-schema-browser

API Explorer to browse JSON Schema based API's
HTML
39
star
2

king_dtaus

DTAUS & DTAZV with Ruby, finally simplifies the handling of german bank transfer format: datenträgeraustauschverfahren
Ruby
32
star
3

king_tour

Create easy on-page tutorials with javascript & html
JavaScript
29
star
4

sk_api_schema

SalesKing API JSON schema
Ruby
28
star
5

json_schema_tools

Tools for building and handling a JSON Schema powered API's
Ruby
27
star
6

json_schema_builder

Build JSON Schema for ActiveRecord models
Ruby
22
star
7

sk-api

OUTDATED & DEPRECATED use our new SDK at https://github.com/salesking/sk_sdk
Ruby
9
star
8

sk_sdk

SalesKing SDK for creating apps and using the API
Ruby
8
star
9

dynamic-favicon

Create dynamic favicon's with javascript and canvas
JavaScript
7
star
10

king_soa

SOA for your apps - call methods in your cloud
Ruby
7
star
11

jquery-dragout

jQuery Plugin to dragout files from your browser
4
star
12

salesking_php_sdk

PHP Rock'n Roll with SalesKing API
PHP
3
star
13

king_views

A buch of helpers to clean up your haml views and forms.
Ruby
3
star
14

contact-importer

Import Contact csv data into SalesKing
Ruby
3
star
15

king_slide_tabs

jQuery plugin for slide in/out tabs from the browsers edges containing help, feedback forms, ..
JavaScript
2
star
16

sk_app_examples

SalesKing oAuth Example Apps
Ruby
2
star
17

king_hmac

HMAC Authentification
Ruby
2
star
18

king_placeholder

Parse placeholders in strings
Ruby
2
star
19

salesking_python_sdk

Python SDK for Salesking, Your Invoicing Billing Accounting CRM
Python
1
star
20

sk_calc

SalesKing calculations for document and item totals
Ruby
1
star
21

wordpress_salesking_inquiry

Wordpress Plugin with contact form for creating leads, orders in SalesKing
PHP
1
star