SEPA CBI XML generator Documentation

(1)

SEPA CBI XML generator

Documentation

Release 0.1.0

Emanuele Pucciarelli

(2)

(3)

Contents

1 Introduction 3

2 Quick start 5

3 Usage 7

4 TheIdHolderclass 9

5 ThePaymentclass 11

5.1 Adding transactions . . . 12 5.2 Obtaining the XML output . . . 13

6 EACT-compliant remittance information 15

7 Indices and tables 17

(4)

(5)

SEPA CBI XML generator Documentation, Release 0.1.0

Contents:

(6)

(7)

CHAPTER

1 Introduction

Thesepacbimodule generates SEPA Credit Transfer requests in the XML format standardized by CBI and accepted by Italian banks.

It is also capable of generating request streams in the legacy CBI-BON-001 fixed-length record legacy format, but only 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 byLinkspirit.

(8)

(9)

CHAPTER

2 Quick start

Each transfer request can include unlimited transactions and is prepared through thePaymentclass. Debtors and creditors are instances of theIdHolderclass.

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()

(10)

(11)

CHAPTER

3 Usage

The module exports theIdHolder,PaymentandTransactionclasses. They are the building blocks for the SEPA credit transfer (SCT) requests.

Each of these classes’ constructors takes optional keyword arguments. You can supply the attributes either via the constructors, 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 theDocument,Invoice,CreditNote,DebitNote,Textclasses that can be used to build the unstructured remittance information field according to the EACT standard.

(12)

(13)

CHAPTER

4 The

IdHolder

class

classIdHolder

An instance of the IdHolderclass represents a single person. (By “person” we mean a natural person, a juridical 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.

name

The name of the person. address

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

The Italian “codice fiscale” for the person (government-issued tax code). Eithercforcodemust be used, but not both, for the same person.

code

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

country

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

The 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 transfer requests.

sia_code

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

(14)

(15)

CHAPTER

5 The

Payment

class

classPayment

An instance of thePaymentclass represents a single credit transfer request, which may include one or more transactions.

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

debtor

TheIdHolderinstance of the holder of the debted account. account

The IBAN of the debted bank account. initiator

(optional)TheIdHolderinstance of the entity who is requesting the credit transfer. If it is missing, it is assumed to be thedebtor.

envelope

(optional)Whether the request should be wrapped in aCbiBdyPaymentRequestXML tag. The de-fault isFalse.

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 desired that a single cumulative line appears on the bank statement for the whole request. If it is set toFalse, the bank 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. The interpretation depends on the agreements between the bank and the customer.

execution_date

(optional)The requested execution date for the transfer. If it is missing, the default is the same day on which 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 the debtor’s IBAN, but in this case it has to be an Italian IBAN.

(16)

ultimate_debtor

(optional)TheIdHolderinstance of the entity who is the ultimate debtor (not necessarily the holder of the debted account) for the request.

charges_account

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

5.1 Adding transactions

Individual transactions are specified by invoking theadd_transactionmethod of thePaymentinstance. Payment.add_transaction(**kwargs)

(All arguments are keyword arguments.) creditor

TheIdHolderinstance of the holder of the credited account. account

The IBAN of the credited account. amount

The credited amount, in Euros. It can be an integer, a float, a string or aDecimalinstance. bic

(optional)The BIC code of the bank of the credited account. This is only needed if the IBAN has a foreign country code (i.e. not starting withITorSM). Otherwise it is ignored.

rmtinfo

(optional)The remittance information(causale). Only needed ifdocsis missing. ultimate_debtor

(optional)TheIdHolderinstance of the ultimate debtor for this transaction. It is only allowed if the ultimate debtor is not specified for the request.

ultimate_creditor

(optional)TheIdHolderinstance 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 type ExternalCategoryPurpose1Code.

If it is not specified, the defaultSUPPis 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 theExternal Code Setspage of the ISO 20022 website. purpose

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

If it is not specified, the defaultSUPPis 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

(17)

The complete list can be found on theExternal Code Setspage of the ISO 20022 website. docs

(optional)A list or tuple ofDocumentinstances (or one of its subclasses). Their information is formatted according to theEACT 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.

5.2 Obtaining the XML output

Payment.xml_text()

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

Returnlxml‘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.

(18)

(19)

CHAPTER

6 EACT-compliant remittance information

The module provides theDocument,Invoice,CreditNote,DebitNoteandTextclasses to help format the remittance information for a transaction.

This is done by specifying a tuple or list of one, or more, instances of these classes for thedocsattribute of the Payment.add_transactionmethod.

classDocument

An instance ofDocumentrepresents a single commercial document for which the transaction is issued. Its subclassesInvoice,CreditNoteandDebitNoteare used in exactly the same way; only the rendered tag changes.

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

number

The 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.

(20)

(21)

CHAPTER

7 Indices and tables

• genindex • modindex • search