SEPA CBI XML generator Documentation

Transcription

1 SEPA CBI XML generator Documentation Release Emanuele Pucciarelli July 06, 2014

2

3 Contents 1 Introduction 3 2 Quick start 5 3 Usage 7 4 The IdHolder class 9 5 The Payment class Adding transactions Obtaining the XML output EACT-compliant remittance information 15 7 Indices and tables 17 i

4 ii

5 SEPA CBI XML generator Documentation, Release Contents: Contents 1

6 SEPA CBI XML generator Documentation, Release Contents

7 CHAPTER 1 Introduction The sepacbi module 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 by Linkspirit. 3

8 SEPA CBI XML generator Documentation, Release Chapter 1. Introduction

9 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= , cuc= A ) payment = Payment(debtor=payer, account= IT 39P ) payment.add_transaction( creditor=idholder(name= John Smith ), account= IT83D , amount=50.12, rmtinfo= Expense reimbursement ) You will the obtain the generated XML request by invoking: payment.xml_text() 5

10 SEPA CBI XML generator Documentation, Release Chapter 2. Quick start

11 CHAPTER 3 Usage The module exports the IdHolder, Payment and Transaction classes. 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 the Document, Invoice, CreditNote, DebitNote, Text classes that can be used to build the unstructured remittance information field according to the EACT standard. 7

12 SEPA CBI XML generator Documentation, Release Chapter 3. Usage

13 CHAPTER 4 The IdHolder class class IdHolder An instance of the IdHolder class 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). Either cf or code must be used, but not both, for the same person. code Another 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. 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. 9

14 SEPA CBI XML generator Documentation, Release Chapter 4. The IdHolder class

15 CHAPTER 5 The Payment class class Payment An instance of the Payment class 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 The IdHolder instance of the holder of the debted account. account The 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 is assumed to be the debtor. envelope (optional) Whether the request should be wrapped in a CbiBdyPaymentRequest XML tag. The default 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 desired that a single cumulative line appears on the bank statement for the whole request. If it is set to False, 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. 11

16 SEPA CBI XML generator Documentation, Release ultimate_debtor (optional) The IdHolder instance 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 the add_transaction method of the Payment instance. Payment.add_transaction(**kwargs) (All arguments are keyword arguments.) creditor The IdHolder instance 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 a Decimal instance. 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 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 the ultimate 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 standard codes of type ExternalCategoryPurpose1Code. 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 website. purpose (optional) The purpose code for the transaction. It must be one of the ISO standard codes of type ExternalPurpose1Code. 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 12 Chapter 5. The Payment class

17 SEPA CBI XML generator Documentation, Release The complete list can be found on the External Code Sets page of the ISO website. docs (optional) A list or tuple of Document instances (or one of its subclasses). Their information is formatted according 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 autogenerated. 5.2 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 Obtaining the XML output 13

18 SEPA CBI XML generator Documentation, Release Chapter 5. The Payment class

19 CHAPTER 6 EACT-compliant remittance information The module provides the Document, Invoice, CreditNote, DebitNote and Text classes 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 the docs attribute of the Payment.add_transaction method. class Document An instance of Document represents a single commercial document for which the transaction is issued. Its subclasses Invoice, CreditNote and DebitNote are 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. 15

20 SEPA CBI XML generator Documentation, Release Chapter 6. EACT-compliant remittance information

21 CHAPTER 7 Indices and tables genindex modindex search 17