Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/salesking/sepa_king

Ruby gem for creating SEPA XML files
https://github.com/salesking/sepa_king

banking fintech iban payment ruby rubygems sepa xml

Last synced: 6 days ago
JSON representation

Ruby gem for creating SEPA XML files

Host: GitHub
URL: https://github.com/salesking/sepa_king
Owner: salesking
License: mit
Created: 2013-08-10T05:48:23.000Z (over 11 years ago)
Default Branch: master
Last Pushed: 2024-06-04T07:08:40.000Z (7 months ago)
Last Synced: 2024-12-13T11:10:29.689Z (13 days ago)
Topics: banking, fintech, iban, payment, ruby, rubygems, sepa, xml
Language: Ruby
Homepage:
Size: 402 KB
Stars: 150
Watchers: 15
Forks: 119
Open Issues: 12
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt

Awesome Lists containing this project

awesome-ruby-toolbox - sepa_king - Implemention of pain.001.002.03 and pain.008.002.02 (ISO 20022) (E-Commerce and Payments / Payments)

README

# Ruby gem for creating SEPA XML files

[![Build Status](https://github.com/salesking/sepa_king/workflows/Test/badge.svg?branch=master)](https://github.com/salesking/sepa_king/actions)
[![Code Climate](https://codeclimate.com/github/salesking/sepa_king/badges/gpa.svg)](https://codeclimate.com/github/salesking/sepa_king)
[![Coverage Status](https://coveralls.io/repos/salesking/sepa_king/badge.svg?branch=master)](https://coveralls.io/r/salesking/sepa_king?branch=master)
[![Gem Version](https://badge.fury.io/rb/sepa_king.svg)](http://badge.fury.io/rb/sepa_king)

We love building payment applications! So after developing the [DTAUS library for Ruby](https://github.com/salesking/king_dtaus) 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 **Pa**yment **In**itiation.

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

```ruby
# 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")

```ruby
# 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:

```ruby
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:
* [lib/sepa_king/validator.rb](https://github.com/salesking/sepa_king/blob/master/lib/sepa_king/validator.rb)
* [lib/sepa_king/transaction/direct_debit_transaction.rb](https://github.com/salesking/sepa_king/blob/master/lib/sepa_king/transaction/direct_debit_transaction.rb)

## Changelog

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

## Contributors

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

## Resources

* https://www.ebics.de/de/datenformate
* SalesKing: http://salesking.eu

## License

Released under the MIT license