sepa cbi xml generator documentation · 2021. 1. 30. · each transfer request can include...

SEPA CBI XML generatorDocumentation

Release 0.1.0

Emanuele Pucciarelli

Sep 11, 2017

Contents

1 Introduction 3

2 Quick start 5

3 Usage 7

4 The IdHolder class 9

5 The Payment class 11

6 EACT-compliant remittance information 15

7 Indices and tables 17

i

SEPA CBI XML generator Documentation, Release 0.1.0

Contents:

Contents 1


2 Contents

CHAPTER 1

Introduction

The sepacbi module generates SEPA Credit Transfer requests in the XML format standardized by CBI and acceptedby Italian banks.

It is also capable of generating request streams in the legacy CBI-BON-001 fixed-length record legacy format, butonly for domestic credit transfers.

The module does not currently support other requests (such as Direct Debit), nor does it support status changes.

The development of this module is funded by Linkspirit.

3

http://www.linkspirit.it/


4 Chapter 1. Introduction

CHAPTER 2

Quick start

Each transfer request can include unlimited transactions and is prepared through the Payment class.

Debtors and creditors are instances of the IdHolder class.

Here is the generation of a very simple credit transfer request:

from sepacbi import IdHolder, Payment

payer = IdHolder(name='Sample Business S.P.A.', cf='12312312311', cuc='0123456A')

payment = Payment(debtor=payer, account='IT 39P 06040 15400 000000138416')payment.add_transaction(

creditor=IdHolder(name='John Smith'), account='IT83D 07601 01000 000010741106→˓',

amount=50.12, rmtinfo='Expense reimbursement')

You will the obtain the generated XML request by invoking:

payment.xml_text()

5


6 Chapter 2. Quick start

CHAPTER 3

Usage

The module exports the IdHolder, Payment and Transaction classes. They are the building blocks for theSEPA credit transfer (SCT) requests.

Each of these classes’ constructors takes optional keyword arguments. You can supply the attributes either via theconstructors, or by setting them on the instances. In other words:

payment = Payment(account='ITxxxx')

and:

payment = Payment()payment.account = 'ITxxxx'

accomplish the same thing.

The module also exports the Document, Invoice, CreditNote, DebitNote, Text classes that can be used tobuild the unstructured remittance information field according to the EACT standard.

7


8 Chapter 3. Usage

CHAPTER 4

The IdHolder class

class IdHolderAn instance of the IdHolder class represents a single person. (By “person” we mean a natural person, ajuridical person or another such entity.) It can be used as an initiator (the entity who requests the credit transfer),as the debtor for the request (whose account will be debited), or the creditor for a single transaction.

nameThe name of the person.

addressA tuple of one or two strings representing the postal address for the person.

cfThe Italian “codice fiscale” for the person (government-issued tax code). Either cf or code must be used,but not both, for the same person.

codeAnother code for the person – usually a government-assigned one, but not the Italian “codice fiscale”.Used for non-Italian persons. Do not use along with cf for the same person.

countryThe two-letter ISO code for the person’s country of residence.

cucThe CBI-issued CUC for the person. This is only used when the person is the initiator of a transfer,otherwise it is ignored.

The CUC is usually communicated by the bank to the customer who wants to issue SEPA credit transferrequests.

sia_codeThe unique identifier assigned by CBI (“Codice SIA”). It is needed when issuing transfer orders in the CBItext format.

9


10 Chapter 4. The IdHolder class

CHAPTER 5

The Payment class

class PaymentAn instance of the Payment class represents a single credit transfer request, which may include one or moretransactions.

Its attributes can be specified as keyword arguments to the constructor, or they can be set at any time beforeadding transactions.

debtorThe IdHolder instance of the holder of the debted account.

accountThe IBAN of the debted bank account.

initiator(optional) The IdHolder instance of the entity who is requesting the credit transfer. If it is missing, it isassumed to be the debtor.

envelope(optional) Whether the request should be wrapped in a CbiBdyPaymentRequest XML tag. The de-fault is False.

req_id(optional) A unique ID for the credit transfer. If it is missing, it is autogenerated.

batch(optional) A boolean value indicating whether batch booking is desired for this request, i.e. if it is desiredthat a single cumulative line appears on the bank statement for the whole request. If it is set to False, thebank is requested to expose the individual transactions on the bank statement.

If it is missing, this depends on the agreements between the bank and the customer.

high_priority(optional) A boolean value indicating whether high priority (urgency) is desired for the whole request. Theinterpretation depends on the agreements between the bank and the customer.

11


execution_date(optional) The requested execution date for the transfer. If it is missing, the default is the same day onwhich the request is generated.

abi(optional) The ABI code of the bank acting as the debtor’s agent. If it is missing, it is taken from thedebtor’s IBAN, but in this case it has to be an Italian IBAN.

ultimate_debtor(optional) The IdHolder instance of the entity who is the ultimate debtor (not necessarily the holder ofthe debted account) for the request.

charges_account(optional) The IBAN of the account on which the transfer charges should be debted.

Adding transactions

Individual transactions are specified by invoking the add_transaction method of the Payment instance.

Payment.add_transaction(**kwargs)(All arguments are keyword arguments.)

creditorThe IdHolder instance of the holder of the credited account.

accountThe IBAN of the credited account.

amountThe credited amount, in Euros. It can be an integer, a float, a string or a Decimal instance.

bic(optional) The BIC code of the bank of the credited account. This is only needed if the IBAN has a foreigncountry code (i.e. not starting with IT or SM). Otherwise it is ignored.

rmtinfo(optional) The remittance information (causale). Only needed if docs is missing.

ultimate_debtor(optional) The IdHolder instance of the ultimate debtor for this transaction. It is only allowed if theultimate debtor is not specified for the request.

ultimate_creditor(optional) The IdHolder instance of the ultimate creditor for this transaction.

category(optional) The category code for the transaction. It must be one of the ISO 20022 standard codes of typeExternalCategoryPurpose1Code.

If it is not specified, the default SUPP is used, defined as “Transaction is related to a payment to a supplier”.Other frequently used codes are:

•SALA, for the payment of salaries

•TAXS, for the payment of taxes

The complete list can be found on the External Code Sets page of the ISO 20022 website.

purpose(optional) The purpose code for the transaction. It must be one of the ISO 20022 standard codes of typeExternalPurpose1Code.

12 Chapter 5. The Payment class

http://www.iso20022.org/external_code_list.page


If it is not specified, the default SUPP is used. Other frequently used codes are:

•SALA, for the payment of salaries

•ADVA, for the payment of advance fees

•TAXS, for the payment of taxes

The complete list can be found on the External Code Sets page of the ISO 20022 website.

docs(optional) A list or tuple of Document instances (or one of its subclasses). Their information is formattedaccording to the EACT Standard for Unstructured Remittance Information.

eeid(optional) The end-to-end ID that uniquely identifies the transaction in the request. If missing, it is auto-generated.

Obtaining the XML output

Payment.xml_text()Return a string containing the XML rendering of the credit transfer request.

Payment.xml()Return lxml‘s XML structure for the credit transfer request.

Payment.cbi_text()Return a string containing a CBI text stream of records according to the CBI-BON-001 technical standard.

5.2. Obtaining the XML output 13

http://www.iso20022.org/external_code_list.page

http://www.europeanpaymentscouncil.eu/index.cfm/sepa-credit-transfer/eact-standard-for-unstructured-remittance-information/


14 Chapter 5. The Payment class

CHAPTER 6

EACT-compliant remittance information

The module provides the Document, Invoice, CreditNote, DebitNote and Text classes to help format theremittance information for a transaction.

This is done by specifying a tuple or list of one, or more, instances of these classes for the docs attribute of thePayment.add_transaction method.

class DocumentAn instance of Document represents a single commercial document for which the transaction is issued. Itssubclasses Invoice, CreditNote and DebitNote are used in exactly the same way; only the rendered tagchanges.

__init__(self, number, amount=None, date=None)

numberThe document number, as specified by its issuer.

amount(optional) The amount paid for this document in the transaction. Used for partial payments.

date(optional) The document’s date.

15


16 Chapter 6. EACT-compliant remittance information

CHAPTER 7

Indices and tables

• genindex

• modindex

• search

17


18 Chapter 7. Indices and tables

Index

Symbols__init__() (Document method), 15

Aadd_transaction() (Payment method), 12

Ccbi_text() (Payment method), 13

DDocument (built-in class), 15Document.amount (built-in variable), 15Document.date (built-in variable), 15Document.number (built-in variable), 15

IIdHolder (built-in class), 9IdHolder.address (built-in variable), 9IdHolder.cf (built-in variable), 9IdHolder.code (built-in variable), 9IdHolder.country (built-in variable), 9IdHolder.cuc (built-in variable), 9IdHolder.name (built-in variable), 9IdHolder.sia_code (built-in variable), 9

PPayment (built-in class), 11Payment.abi (built-in variable), 12Payment.account (built-in variable), 11, 12Payment.amount (built-in variable), 12Payment.batch (built-in variable), 11Payment.bic (built-in variable), 12Payment.category (built-in variable), 12Payment.charges_account (built-in variable), 12Payment.creditor (built-in variable), 12Payment.debtor (built-in variable), 11Payment.docs (built-in variable), 13Payment.eeid (built-in variable), 13Payment.envelope (built-in variable), 11

Payment.execution_date (built-in variable), 11Payment.high_priority (built-in variable), 11Payment.initiator (built-in variable), 11Payment.purpose (built-in variable), 12Payment.req_id (built-in variable), 11Payment.rmtinfo (built-in variable), 12Payment.ultimate_creditor (built-in variable), 12Payment.ultimate_debtor (built-in variable), 12

Xxml() (Payment method), 13xml_text() (Payment method), 13

19

sepa cbi xml generator documentation · 2021. 1. 30. · each transfer request can include...

Documents