Swedbank Gateway Service Description 7.0
advertisement
Swedbank Gateway service description Version 7.0 Contents Revision history................................................................................................................................................ 6 Definitions and abbreviations .......................................................................................................................... 9 Introduction ..................................................................................................................................................... 9 Swedbank Gateway specification ..................................................................................................................... 9 Sending request data to the bank .................................................................................................................... 10 PUT .............................................................................................................................................................. 10 Receiving responses from the bank ................................................................................................................. 10 GET .............................................................................................................................................................. 10 DELETE ......................................................................................................................................................... 11 Cryptography .................................................................................................................................................... 11 Client side certificates .................................................................................................................................. 11 Bank side certificates ................................................................................................................................... 12 CA and OCSP responder certificates ............................................................................................................ 13 Digital signatures and encryption usage in Swedbank Gateway ...................................................................... 13 Supported digital signature and encryption file formats ............................................................................. 13 BDOC............................................................................................................................................................ 13 CDOC ............................................................................................................................................................ 14 Error handling ................................................................................................................................................ 18 Example error message .................................................................................................................................... 18 Error codes used ............................................................................................................................................... 18 General error codes ..................................................................................................................................... 18 Payment error codes .................................................................................................................................... 19 Currency exchange error codes ................................................................................................................... 21 Troubleshooting ............................................................................................................................................... 22 Service – Communication test ........................................................................................................................ 23 Service description ........................................................................................................................................... 23 Example request XML ....................................................................................................................................... 23 Description of fields in request XML ................................................................................................................ 23 Example response XML .................................................................................................................................... 23 Description of fields in response XML .............................................................................................................. 23 Service – Account Balance .............................................................................................................................. 24 Service description ........................................................................................................................................... 24 Example request XML in ISO20022 camt.060.001.03 format .......................................................................... 24 Description of fields in request XML and response example in ISO20011 camt.052.001.02 format can be found in ISO MIG on SGW development toolbox download site http://dev.hansagateway.net/download. .. 25 Service – Payment .......................................................................................................................................... 26 Service description ........................................................................................................................................... 26 Supported formats ....................................................................................................................................... 26 Allowed characters and file encoding .......................................................................................................... 26 Limits and double acceptance condition ..................................................................................................... 27 Duplicity check ............................................................................................................................................. 28 Example request XMLin ISO20022 pain.001.001.03 format ............................................................................ 28 Description of fields in request XML can be found in ISO MIG on SGW development toolbox download site http://dev.hansagateway.net/download. ........................................................................................................ 30 Example response XML in ISO20022 pain.002.001.03 format ......................................................................... 30 Service – Account statement .......................................................................................................................... 34 Service description ........................................................................................................................................... 34 Example request XML in ISO20022 camt.053.001.02 format .......................................................................... 34 2 More detailed examples and description of fields in request and response XML can be found in ISO MIG on SGW development toolbox download site http://dev.hansagateway.net/download. ................................ 34 Latvian codes for Transaction/TypeCode .................................................................................................... 35 Estonian codes for Transaction/TypeCode .................................................................................................. 35 Lithuanian codes for Transaction/TypeCode ............................................................................................... 36 Service – Exchange rates ................................................................................................................................ 38 Service description ........................................................................................................................................... 38 Example request XML ....................................................................................................................................... 38 Description of fields in request XML ................................................................................................................ 38 Example response XML .................................................................................................................................... 38 Description of fields in response XML .............................................................................................................. 39 Service – Currency exchange .......................................................................................................................... 40 Service description ........................................................................................................................................... 40 Example request XML ....................................................................................................................................... 40 Description of fields in request XML ................................................................................................................ 40 Example response XML .................................................................................................................................... 41 Description of fields in response XML .............................................................................................................. 41 Service – Alert on transactions ....................................................................................................................... 42 Service description ........................................................................................................................................... 42 Example request XML ....................................................................................................................................... 42 Example response XML camt.054.001.02 ........................................................................................................ 42 Service – Periodic statement .......................................................................................................................... 43 Service description ........................................................................................................................................... 43 Example request XML ....................................................................................................................................... 43 Example response XML .................................................................................................................................... 43 Service – Sending e-invoices ........................................................................................................................... 44 Service description ........................................................................................................................................... 44 Example request XML (einvoice-request.xml) .............................................................................................. 44 Description of fields in request XML ................................................................................................................ 44 Estonian e-invoice version 1.11 ........................................................................................................................ 44 Example response XML (success, EE) ........................................................................................................... 45 Example response XML (errors on file level, EE) .......................................................................................... 45 Example response XML (errors on invoices level, EE) .................................................................................. 45 Latvian e-invoice version 1.0 ............................................................................................................................ 45 Example response XML (success, LV) ........................................................................................................... 46 Example response XML (errors on file level, LV) .......................................................................................... 46 Example response XML (errors on invoices level, LV) .................................................................................. 46 Lithuanian e-invoice version 1.1....................................................................................................................... 46 Description of fields in response XML .............................................................................................................. 47 Error codes ....................................................................................................................................................... 48 Validations performed upon E-invoice receipt in Estonia ................................................................................ 50 Validations performed upon E-invoice receipt in Latvia .................................................................................. 51 Validations performed upon E-invoice receipt in Lithuania ............................................................................. 52 General e-invoice file exchange process .......................................................................................................... 53 Einvoice and e-invoice SOA/APA cancelling via Credit Invoice ........................................................................ 55 E-Invoice Standing Order Agreement (EE) / E-Invoice Automated Payment Agreement (LV/LT) .................... 56 Service – Single E-Invoice application ............................................................................................................. 57 Service description ........................................................................................................................................... 57 Example request XML ....................................................................................................................................... 57 Example response XML, EE ............................................................................................................................... 57 Example response XML, LV............................................................................................................................... 57 Example response XML, LT ............................................................................................................................... 58 3 Description of fields in response XML can be found in concrete country e-invoice technical descriptions. ... 58 Service – E-Invoice Standing Order (EE) / Automated Payment (LV, LT) agreement management .................. 59 Service description ........................................................................................................................................... 59 Example request XML (SOAreport-request.xml, EE) ........................................................................................ 59 Example request XML (APAreport-request.xml, LV) ........................................................................................ 59 Example request XML (APAreport-request.xml, LT)......................................................................................... 60 Description of fields in request XML ................................................................................................................ 60 Example request XML (SOAreport.xml, EE, ADD) ............................................................................................. 60 Example request XML (SOAreport.xml, EE, UPD) ............................................................................................. 60 Example request XML (SOAreport.xml, EE, DEL) .............................................................................................. 61 Example request XML (APAreport.xml, LV, ADD) ............................................................................................. 61 Example request XML (APAreport.xml, LV, UPD) ............................................................................................. 61 Example request XML (APAreport.xml, LV, DEL) .............................................................................................. 62 Example request XML (APAreport.xml, LT, ADD) ............................................................................................. 62 Example request XML (APAreport.xml, LT, UPD) ............................................................................................. 63 Example request XML (APAreport.xml, LT, DEL) .............................................................................................. 63 Description of fields in request XML ................................................................................................................ 63 Example response XML (success, EE) ............................................................................................................... 65 Example response XML (success, LV) ............................................................................................................... 66 Example response XML (success, LT) ............................................................................................................... 66 Example response XML (invalid file, EE) ........................................................................................................... 66 Example response XML (invalid file, LV) ........................................................................................................... 66 Example response XML (invalid file, LT) ........................................................................................................... 66 Example response XML (agreement based errors, EE) .................................................................................... 66 Example response XML (agreement based errors, LV) .................................................................................... 67 Example response XML (agreement based errors, LT) ..................................................................................... 67 Description of fields in response XML .............................................................................................................. 67 SOA/APA management service error codes ..................................................................................................... 68 Service – Periodic report of E-Invoice Standing Order (EE)/ Automated Payment (LV, LT) changes ............... 69 Service description ........................................................................................................................................... 69 Example request XML ....................................................................................................................................... 69 Example response XML .................................................................................................................................... 69 Service – E-Invoice Standing Order (EE) / Automated Payment (LV, LT) agreement payment report .............. 70 Service description ........................................................................................................................................... 70 Example request XML ....................................................................................................................................... 70 Example response XML, EE ............................................................................................................................... 70 Example response XML, LV............................................................................................................................... 70 Example response XML, LT ............................................................................................................................... 71 Description of fields in response XML .............................................................................................................. 71 E-invoice Standing Order/Automated Payment Payment status codes ........................................................... 72 Service – E-Invoices for customer ................................................................................................................... 73 Service description ........................................................................................................................................... 73 Example request XML ....................................................................................................................................... 73 Example response XML .................................................................................................................................... 73 Service – POS report delivery ......................................................................................................................... 74 Service description ........................................................................................................................................... 74 Example request XML ....................................................................................................................................... 74 Example response XML .................................................................................................................................... 74 Example 1: Transaction based report ............................................................................................................... 74 Example 2: Batch based report ........................................................................................................................ 76 4 Figures Figure 1: BDOC container. .............................................................................................................................. 14 Figure 2: Overview of sending requests and receiving responses from the bank ............................................ 15 Figure 3: Signing, encrypting and sending messages to the bank.................................................................... 16 Figure 4: Receiving, decrypting and verifying messages from the bank .......................................................... 17 Figure 5: Swedbank validations performed upon E-invoice receipt in Estonia ................................................ 50 Figure 6: Swedbank validations performed upon E-invoice receipt in Latvia .................................................. 51 Figure 7: Swedbank validations performed upon E-invoice receipt in Lithuania ............................................. 52 Figure 8: General e-invoice file exchange process layout in Estonia ............................................................... 53 Figure 9: General e-invoice file exchange process layout in Latvia ................................................................. 53 Figure 10: General e-invoice file exchange process layout in Lithuania .......................................................... 54 5 Revision history Version Changes Date 2.9 Changed EE domestic payment fields: BeneficiaryName (length 70) Changed Foreign payment fields: BeneficiaryName (length 70) BeneficiaryAddress (length 70+optional) Details (length 140) Cost (comment) BalanceOfPaymentsCountry (comment) Changed LV domestic payment fields: BeneficiaryName (length 70) BeneficiaryBankCode (mandatory) Added new error codes Added more information to service specification EE payment document number (length) Foregin payment tag: BeneficiaryIBAN – removed Added additional information about Active MQ in paragraph Service specification > More about message exchange and ACK: XML validation demand in paragraph HGW Exceptions and errors Lithuanian fields (OrderingParty/IBAN, OrderingParty/Name, Assignee/IBAN, Assignee/Name) are set to optional Re-Branding - Product name change HansaGateway Swedbank Gateway HGW SGW Incoming file name and request id must be unique Removed sample client information 05.12.2008 07.07.2009 3.2 LT payment tag change: Assignee/IBAN =>Assignee/Account LT payment tag change: OrderingParty/IBAN =>Ordering/Account Foreign payment <cost> rule fix Major changes in communication protocol. Dropping Active MQ and starting to use HTTP protocol. All communication parameters are changed. Added info about HTTP protocol at the pg 6. Added additional tag for LV in statements and alert - tag BIC Added info about troubleshooting 3.3 Schema fixing 30.03.2010 3.4 Added beneficiary ID to Lithuanian local payments 30.08.2010 3.5 Removed EE domestic payment priority “U” not valid after 01.01.2011; foreign payment “BalanceOfPaymentsCode” is mandatory as from 50,000 EUR equivalent for EE Changed xsd validation addresses inside examples to http://swedbankgateway.net/... Added Process Flow diagrams for message exchange and certificate usage. Corrected terminology referring to certificates. Revised and expanded Swedbank Gateway specification description. Revised error handling and error codes. Changed document style. Added a table of figures. Added bank response message header X-Gateway-Message functionality. 03.01.2011 2.10 2.11 2.12 2.13 2.14 2.15 3.0 3.1 3.6 4.0 4.1 11.12.2008 07.01.2009 27.01.2009 04.03.2009 13.05.2009 14.09.2009 09.11.2009 18.01.2010 01.03.2012 24.04.2012 10.10.2012 6 4.2 5.0 5.1 5.2 Added information about CA and OCSP certificates. Added overview about OCSP service. Updated troubleshooting information with X-Gateway-Message header. Added reference to ISO20022 support and implementation guideline in Payment service. Added information regarding double-acceptance condition in Payment service. Added information regarding Alert filters. Added information regarding Account Balance service response XML field Transaction/TypeCode possible values and their meaning. Corrected values for XML fields: Agreement/Utility, Agreement/Discount, Payment/Description Corrected Service – Direct debit payer agreement changes root-tag: from <DirectDebitAgreements> to <DirectDebitAgreementChange> Added sample XML for POS reports – transaction based report and batch based report. Added Foreign payment service change: DocumentNumber max length changed to AN (1 – 10) Added information about additional supported signing tokens: Latvian IDcard, Lithuanian crypto stick Giesecke & Devrient (G&D) Added information regarding FidaVista 1.01 format support for following services: Payment, Account Statement, Periodic statement, Alert on transaction Added information about new e-invoice services – version 1.11 support, SOA management, periodic SOA report, SOA payment report, single e-invoice application sending Disclaimer regarding client side certificate (Subject: O=Swedbank AS) usage General message requirement: no comments to be included before the header tags (format, service). General incoming message file size limitation 15MB DDOC, increased to 60MB starting from 21.11.2013. E-invoice recalling service description E-invoice SOA payment report service description changed E-Invoice Standing Order agreement management service updated – signature container must have 2 files, SOAreport.xml and SOAreport-request.xml Update to e-invoice error codes ISO20022 pain.001.001.03 and pain.001.002.03 implementation guideline reference ISO20022 camt.053.001.02, camt.052.001.02, camt.054.001.02 and camt.060.001.03 implementation guideline reference. The Account statement request period range can be up to 90 days from now on. Notification regarding different number of transactions per statement page depending on the requested statement format. Currency LVL removed as of 01.01.2014 Allowed characters check in interbank Domestic Payments and in European Payments in EE and LV starting from 01.02.2014 due to SEPA clearing requirements Urgent domestic payment in Estonia available from 01.02.2014. Payment service and Currency Exchange service updated with file encoding, duplicity check, limits check (limit not reduced for intra-company payment) and double acceptance condition rules. 11.12.2012 28.06.2013 20.11.2013 13.03.2014 7 Balance service updated with ISO20022 support E-invoice validation and XSD changes – IBAN and SellerRegNr mandatory as of 01.02.2014 E-invoice validation schema changes for abstract e-invoice. E-invoice SellerParty.Name and PaymentInformation.PayToName can now have a 75% deviation from exact account owner name. 6.0 6.1 7.0 Parallel support for alternative digital signature container BDOC introduced 05.12.2014 for message exchange in the channel. E-invoice and Automated Payment related services in Latvia added List of channel error codes has been updated List of Gateway service native error codes has been updated 16.07.2015 Direct Debit product related services have been removed – discontinuation of product as of 01.01.2016 due to SEPA regulation. Product is replaced by e-invoice services DDOC format support enddate 01.05.2016 outlined Drawings for message exchange have been updated to BDOC Alert native xml sample adjusted to current state - CDATA removed SK certificate profile website link updated RC certificates weblinks updated E-Invoice errorcode 106 added Supported Signing certificates support extended to Estonian e-resident Digi ID E-invoice and Automated Payment related services in Lithuania added 15.07.2016 List of channel error codes has been updated Estonian E-invoice validation schema was updated with BIC code verification Direct Debit error codes removed Unique agreement number (agreementId) parameter usage in message exchange Examples replacement with ISO20022 formats Removed DDOC Alerts service added remark of usage BDOC container without signature Starting date for 2 bank certificates usage has been set 8 Definitions and abbreviations IS – Information System ERP – Enterprise Resource Planning ETSI – European Telecommunication Standards Institute DDOC – term DDOC is used through the text to denote both XAdES profile and a container format for digitally signed files with extension .ddoc. BDOC – term BDOC is used through the text to denote both XAdES profile and a container format for digitally signed files with extension .bdoc. SK – Sertifitseerimiskeskus AS (CA in Estonia, http://www.sk.ee) Digidoc - infrastructure with libraries and utilities provided by SK to implement digital signatures (in BDOC and DDOC format) and encryption/decryption (CDOC format) RC – Registru Centras (CA in Lithuania, http://www.registrucentras.lt/en/ ) B4B – software certificate profile defined by SK (http://www.sk.ee/en/repository/CP/) SGW – Swedbank Gateway channel PKI – Public Key Infrastructure SOA – E-invoice Standing Order Agreement (service in Estonia) APA - E-invoice Automated Payment Agreement (service in Latvia) Toolbox – Swedbank provided client application Introduction Swedbank Gateway is an asynchronous automated data communications channel between client’s Information System (sometimes referred to as ERP) and Swedbank. Client and the bank exchange data asynchronously in real-time, 24 hours a day, making information available regardless of working hours. Data exchange is based on HTTPS protocol, XML format messages, DigiDoc and PKI infrastructure. SGW channel can be taken into use if client’s IS has a universal built-in support for it, or if the required interface will be developed separately for the client’s IS. Swedbank Gateway specification As mentioned above SGW is the data communications channel, where the bank and client are exchanging Request and Response data. Standard HTTPS (HTTP with SSL) protocol is used for communication. Client sends data requests to the bank with HTTP PUT request and receives responses from the bank with HTTP GET request. After receiving a response, client must send confirmation message with HTTP DELETE request. Each communication session is authenticated by client’s Transport certificate. SGW address in production environment is https://swedbankgateway.net To be able to start using this service client has to fulfill the following prerequisites: Conclude Swedbank Gateway service agreement, preceded by filling a SGW application. You will be issued unique AgreementId – used in message exchange for customer identification, enabling customers to address several agreements with same certificate. Develop required software for exchanging data between Client IS and SGW or use Bank’s toolbox client application (written in Java, available command line,GUI and webclient versions) for communication. Data exchange must consider the channel requirement for split9 ting a large dataset into several smaller messages, limitation to the message maximum size in channel can vary in time and depending on the service. Applies to both request and response messages. Successful testing results from Swedbank Gateway Sandbox environment. Sending request data to the bank PUT Request parameters: Request body – cdoc file Header CorrelationID – Message correlation ID set by the customer, which helps to connect request and response data. ID must be unique. Header X-AgreementId – Swedbank Gateway agreement number provided by the bank that uniquely identifies the agreement. The response contains: Header X-Gateway-Message – header with value „1“ confirming that message reached to the service Header X-AgreementId – Swedbank Gateway unique agreement number HTTP Response codes: 200 – OK 500 – Internal error Receiving responses from the bank Receiving response data from the bank consists of two steps: Message is received in a response of a GET request. After receiving a message a confirmation must be sent out with a DELETE request. If SGW does not receive a confirmation during one hour after the initial GET request, then the response message will be redelivered to the customer on the next GET request. GET Request parameters Header X-AgreementId – Swedbank Gateway agreement number provided by the bank that uniquely identifies the agreement. The response message is delivered as the response body. The response contains: Body – cdoc file Header CorrelationID – CorrelationID set by Client with PUT request. Header TrackingID – Bank side message ID. Header X-Gateway-Message – header with value „1“ confirming that message reached to the service Header X-AgreementId – Swedbank Gateway unique agreement number HTTP response codes: 200 – OK 400 – Bad request 404 – No messages 10 500 – Internal error NB!GET requests must be implemented with a reasonable frequency towards the SGW service (eg 1 request per minute). DELETE Request parameters: Header TrackingID – Bank side message ID received with the GET response. Header X-AgreementId – Swedbank Gateway agreement number provided by the bank that uniquely identifies the agreement. The response contains: Header X-Gateway-Message – header with value „1“ confirming that message reached to the service Header X-AgreementId – Swedbank Gateway unique agreement number HTTP Response codes: 200 – OK 400 – Bad request. Most probably no message found with the given Tracking ID 500 – Internal error Cryptography The whole cryptographic solution within SGW channel is built according to PKI crypto standard. Client must keep this in mind when developing their connection to SGW. For overview of PKI please read https://www.swedbank.ee/download/gateway/PKI-in-nutshell.pdf. Swedbank Gateway is accepting only encrypted and digitally signed files containing XML document with service-specific contents. Client certificates used for authentication, signing and encryption must be trusted by the bank’s IS. Client side certificates NB! Please be informed that certificates ordered via Swedbank ( Subject: O=Swedbank AS ) are issued for Swedbank Gateway usage only. Use of these certificates outside SGW channel infrastructure for any other purpose is strictly prohibited. 1. ERP certificate –technical signature (no OCSP confirmation is included, role “ERP” must be set) given by this organizational certificate identifies that messages were sent by client’s information system to the bank. The bank uses this certificate to address all encrypted information that is being sent to client (only client can decrypt the content). NB! ERP certificate must have minimum following values in Key Usage: Digital Signature, Key Encipherment. Extended Key Usage: Client Authentication Key Size: 2048 bit Suitable software token certificate is issued by SK from KLASS3 root, under “B4B” profile. Read more about SK’s certificate policies - http://www.sk.ee/en/repository/CP/ and about certificate profiles: https://www.sk.ee/en/repository/profiles/ In Lithuania, we also support ERP certificates that are issued by Lithuanian Registru Centras http://www.registrucentras.lt/en/ 11 2. Transport certificate – this certificate is used in order to authenticate communication session from client’s information system to SGW channel. In most cases when customer is connected directly to SGW channel (without other “middle-man” service providers), there is no need for separate certificates and only one certificate is used – meaning ERP certificate also has the role of a Transport certificate. 3. Signing certificate – qualified electronic signature with OCSP confirmation given by this certificate is used for approving payments in SGW channel. Signing certificates should always be on a physical device (non-reproducible) and issued by a CA that the bank trusts. Signing certificates should always be issued to a person and not to organization. Signing certificate generally has following value in Key Usage: Non-Repudiation. Currently accepted Signing certificates in SGW channel: Estonian ID cards Estonian Digi-ID Estonian Mobile-ID (M-ID) Estonian e-resident Digi ID Lithuanian ID card Lithuanian Mobile-ID Latvian ID card Finnish ID card Estonian cryptostick Aladdin eToken with SK B4B certificate (technical signature with OCSP confirmation given with this token is accepted by the bank. Requires special configuration) Lithuanian cryptostick Aladdin eToken with RC certificate Lithuanian cryptostick Giesecke & Devrient (G&D) with RC certificate Since certificates are valid only for a certain period, client has to monitor the validity of certificate, get a new certificate when it expires and contact the bank to update the service agreement with the new certificate. For mission critical systems where interruptions are not allowed, support of two certificates can be planned during the switching period. In case the certificate’s private key has been compromised, client should immediately inform the bank and the certificate will be closed. Bank side certificates 1. Channel website certificate – since SGW uses HTTPS connection with clients, we identify this by our website certificate, which in case of SGW is issued by SK. 2. Bank’s public e-Seal (Digital Stamp) certificate is used to sign all outgoing messages, so that clients can verify that all information is sent by the bank. 3. Bank’s public cryptocertificate (certificate for encryption) - all messages that clients are sending to the bank, will be encrypted with the bank cryptocertificate’s public key – so that only the bank will be able to open them. Information regarding Bank’s currently valid certificates is provided to you with SGW development toolbox. Since Bank’s certificates are valid only for certain period, clients should be aware and plan tasks required on their side to update Bank’s certificates. Since certificates can be issued from new roots, that may also mean trusting new root level certificates of CA. NB! Till 01.10.2017 Swedbank uses same certificate for both signing and encryption purposes , but from integration perspective it is needed to enable separate certificates for these functions. 12 Two bank certificates support is added to Swedbank toolbox client application starting from version 3.0. CA and OCSP responder certificates CA’s of certificates that are used in channel must be trusted; same applies to the OCSP responders. Information and validity can be found here: http://www.sk.ee/en/repository/certs/ The OCSP validity confirmation service is available at: http://ocsp.sk.ee/ or via Swedbank proxy. Digital signatures and encryption usage in Swedbank Gateway Every request XML has to be digitally signed with ERP certificate’s private key. This digital signature is defined as a technical signature – given by software certificate token and no OCSP confirmation is added to the signature. When creating a new signature object then signer’s role “ERP” has to be set in order to specify that the signature is created with organizational ERP certificate. In case of payments, additional qualified electronic signature(s) with OCSP confirmation has to be added by Signing certificate(s). Resulting digital signature file has to be encrypted using Bank certificate’s public key. As it is possible to encrypt for several recipients, we recommend that “Recipient” property of that EncryptedKey is set to “HGW”. This lets us choose correct encrypted transport key block for decryption. Response from bank is an encrypted and digitally signed XML file, signed by Bank certificate, encryption is addressed to ERP certificate found in request or in case of push messages, to ERP certificate listed in the service agreement. In case the request could not be processed, response will be a plaintext XML file with error details. The bank’s response message’s digital signature format and contained XML message format is determined by 2 factors: 1) Response to a request is with same digital signature format and same XML format as the request. Unsupported formats will produce an error – see next paragraph for supported formats for digital signature. Supported XML formats are listed under each service separately. 2) Push messages – messages initiated by bank based on service agreement automatically – such as Periodic statement, POS report, E-Invoice Seller reports – will be using the digital signature container format and XML format specified in the service agreement. Digital signature creation, encryption, definitions of different digital signature types (digital stamps, qualified electronic signatures, technical signatures), OCSP validity confirmation specifics and DigiDoc libraries for BDOC are described in detail in Swedbank Gateway Service Programmer’s Guide, available at SGW development toolbox download site http://dev.hansagateway.net/download. Access to this site is IP-address based. Supported digital signature and encryption file formats BDOC The BDOC file format is based on AsiC (ETSI TS 102 918 V1.2.1 (2012-02) – Associated Signature Containers) standard which is in turn profiled by ASiC BP (ETSI TS 103 174 V2.1.1 (2012-03) - ASiC Baseline Profile). The latter foresees ODF-type packaging specified in OpenDocument standard of OASIS. BDOC packaging is a ASiC-E XAdES type ZIP container. DigiDoc system uses .bdoc extension for the files complying with the model below. For more details please read http://id.ee/public/bdoc-spec212-eng.pdf. 13 The following figure illustrates use of XAdES elements within different BDOC-defined signature profiles. Currently SGW service supports only BDOC with time marks (TM profile). Figure 1: BDOC container. CDOC .CDOC is an extension, that is used to distinguish files encrypted in the BDOC format. The encrypted file format (ENCDOC-XML) is based on the international standard XML-ENC. A CDOC file contains a single encrypted data file (XML document or some other binary file (MS Word, Excel, PDF, RFT etc)), recipient certificate, encrypted key for the decryption of the data file (transport key), and other non-compulsory meta data. Data files are encrypted with AES encryption algorithm using a 128 bit key. One encrypted file can have several recipients (possible decrypters), and for this purpose each CDOC file contains the recipient certificates and transport keys for each recipient for data file decryption. 14 Sending request files to Bank Sign with Client ERP Certificate Private Key In case of transactions - Sign additionally with Authorized Person Signing Certificate Private Key + OCSP Encrypt with Bank Certificate Public Key CDOC: Encrypted with Bank Certificate Public Key BDOC: Signed container BDOC: Signed container Request XML file Request XML file Send to Bank Request XML file Receiving response files from Bank (except Alert service response) CDOC: Encrypted with Client ERP Certificate Public Key Receive from bank Decrypt with Client ERP Certificate Private Key Verify Bank Signature BDOC: Signed with Bank Certificate BDOC: Signed with Bank Certificate Response XML file Response XML file Response XML file Receiving Alert service response from Bank Decrypt with Client ERP Certificate Private Key CDOC: Encrypted with Client ERP Certificate Public Key Alert response XML file BDOC: Without Bank side Signature Receive Alert from bank Alert response XML file Figure 2: Overview of sending requests and receiving responses from the bank 15 IS sending request to Bank via SGW channel It is recommended to renew Bank’s public certificate from LDAP directory within reasonable time-frame (i.e. to check if Bank’s certificate hasn’t been compromised) This process can be initiated either by user’s request (for example, user makes an operation that requires data exchange with Bank) or by IS (periodic job) IS checks Bank’s public key - Connection via SSL protocol. - Session is being authenticated by client’s Transport certificate (B4B) No IS prepares request to Bank Request XML file - Technical signature (digital signature) given with software based ERP certificate. - OCSP confirmation is not required Qualifying certificates: • SK issued certificate (B4B or other suitable profile) • RC issued software certificate Required values in Key Usage: Digital Signature, Key Encipherment. Key Size: min 2048 bit Operations legend: Can be made (called out) with DigiDoc library IS development responsibility File is signed digitally by IS CDOC: Encrypted with Bank’s Public Key Encrypt with Bank crypto certificate public key Sign by person? 3 4 BDOC: Signed container IS sends file to Bank Request XML file Bank receives request Yes 2 1 IS signs with ERP certificate, using DD library User signs with Signing certificate from hardware token BDOC: Signed container BDOC: Signed container Request XML file Request XML file Certificate usage: 1 Software based ERP certificate (B4B) is used to sign document by IS 2 Hardware token based Signing certificate is used to sign document by person. Mandatory for payments service messages 3 Bank’s crypto certificate public key is used for encryption* 4 Software based Transport certificate (B4B) is used to authenticate client’s session - Legal signature given with Signing certificate from hardware token (key usage= non-repudiation digital signature). - User enters PIN code manually - OCSP validity confirmation is mandatory to include - support of relevant OCSP responder certificates is important Qualifying certificates: • Estonian ID card, Digi ID, e-resident Digi ID, Mobile-ID • Lithuanian ID card, Mobile-ID • Latvian ID card • Finnish ID card • EST USB cryptostick (Digital Stamp, B4B) • LT USB cryptostick DigiDoc usage (library / utility): 1 2 3 Technical signing – sign document with software certificate (issued under B4B profile). OCSP validity confirmation not required Legal Signing – sign document with hardware certificate (ID Card or other supported token). OCSP validiy confirmation required Encryption – Bank’s crypto certificate public key is used for encryption* in CDOC format Abbreviations: IS – Information System ERP – Enterprise Resource Planning DD – DigiDoc SK – Sertifitseerimiskeskus (CA in Estonia) RC - Registru Centras (CA in Lithuania) B4B – software certificate profile defined by SK *till 2016 Bank’s signing and crypto certificate are one and the same (old SK Digital Stamp profile) Figure 3: Signing, encrypting and sending messages to the bank 16 Bank sending answer to IS via SGW channel Bank generates response once client’s request processing is completed – this time may vary depending on the service used in channel Bank checks Client’s public certificate from LDAP directory before sending any message (i.e. checks if Client’s certificate hasn’t been compromised) - Connection via SSL protocol - Session is being authenticated by client’s Transport certificate (B4B) - Since SSL is being used, Bank’s SSL certificate (Website certificate) may also be checked by client Only client who has appropriate ERP certificate’s private key, can decrypt the file to see it’s content Bank checks Client’s ERP certificate public key 3 CDOC: Encrypted with Client’s Public Key Bank generates response Response XML file - Bank’s legal signature is given with hardware token certificate – Digital Stamp - OCSP validity confirmation is mandatory to include - support of relevant OCSP responder certificates is important Sign by Bank Encrypt with Client’s ERP certificate public key 2 BDOC: Signed container Request XML file Bank puts file to client’s „Inbox” at SGW channel Client’s files Bank authenticates client by Transport certificate Yes 1 Signing with Bank certificate (Digital Stamp) Qualifying certificate: • SK issued Digital Stamp BDOC: Signed container Request XML file Qualifying certificates: • SK issued certificate (B4B or other suitable profile) • RC issued software certificate Required values in Key Usage: Digital Signature, Key Encipherment. Key Size: min 2048 bit CDOC: Encrypted with Client’s Public Key BDOC: Signed container Request XML file IS downloads response files from Bank 4 IS decrypts message with ERP certificate BDOC: Signed container Operations legend: Can be made (called out) with DigiDoc library Client’s development responsibility Certificate usage: 1 Bank’s signing certificate is used to sign messages from Bank* 2 Client’s software based ERP certificate (B4B) public key is used for encryption. 2 Client’s software based Transport certificate (B4B) is used to authenticate client’s session 4 3 Request XML file DigiDoc usage (library / utility): 1 *till 2016 Bank’s signing and crypto certificate are one and the same (old SK Digital Stamp profile) Legal Signing – Bank signs document with hardware certificate* (Digital Stamp), key usage: non-repudiation. OCSP validity is included Encryption – Client’s ERP certificate (B4B) public key is used for message encryption in CDOC format Decryption – Client’s ERP certificate (B4B) private key is used for decryption of bank message IS verifies if Bank’s signature is both correct and valid. After that file can be used. IS validates Bank’s signature Response XML file IS can use file Figure 4: Receiving, decrypting and verifying messages from the bank 17 Error handling Error responses are sent as an XML file that can be in unencrypted form or inside an encrypted signature container. Error responses are sent unencrypted in case the request signature file is invalid and it is not possible to extract the ERP certificate from it. To avoid cases when the XML files sent to the bank are not valid, bank strongly recommends validating XML files on the client side before sending them to the bank. Additionally, we recommend not using comments in the beginning of the service XML messages, in front of the header tags for format and service, as it may cause message format and type detection failure. In case request message maximum file size is exceeded, SGW replies with error “Expected number of transactions in the message is too large”. Contact the bank in order to find out the current limitation and lower the number of transactions per file to fit the criteria. Current limitation is set to 60MB for digital signature container (this is size of ddoc or bdoc file) and approximately 45MB per contained XML file(s). Validation XSD locations can be found at the following addresses: https://www.swedbank.ee/hgw/valid/hgw.xsd https://www.swedbank.ee/hgw/valid/hgw-response.xsd Example error message <?xml version="1.0" encoding="UTF-8"?> <B4B xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://swedbankgateway.net/valid/hgw-response.xsd"> <HGWError> <Code>AccountNotAllowed</Code> <Message> None of the signers can access this account!</Message> </HGWError> </B4B> Communication test doesn’t produce error when service is not activated in client agreement. Error codes used Not all error codes and error descriptions might be listed here. We try our best to keep the following list updated! General error codes Code Description NoRights ERP signature is not tied to any HGW agreements! AccountNotAllowed None of the signers can access this account! MoreSignaturesNeeded More signatures needed! BankCodeNotFound Bank code could not be found! dailyLimitExceeded Daily limit exceeded! monthlyLimitExceeded Monthly limit exceeded! 84 Currency does not exist! 91 Operations are currently not permitted! 18 6009 Insufficient funds for transaction on the account! 6100 Locking of current account failed! FileSizeOverLimit Estimated number of records too high HGWProtocolError Missing payload, datafile not present InvalidParameter File name is not pointing to an existing file in DigiDoc container. Payment error codes Code Description balanceOfPaymentsCode Balance of Payments code is missing! RemitterIBAN Remitter IBAN is invalid! BeneficiaryIBAN Beneficiary IBAN is invalid! BeneficiaryBankAccount Beneficiary bank account is invalid! BeneficiaryAddress Beneficiary address is missing! ValueDate Invalid date! Currency Invalid currency! BeneficiaryBankCode Beneficiary bank code is invalid! BeneficiaryResidence Beneficiary residence is invalid! DocumentNumber Document number is missing! Amount Amount is missing or invalid! BeneficiaryName Beneficiary name is missing! RemitterPaymentID Payment ID is missing! ValueDateFormat Value date format is invalid! Costs Costs is incorrect! BeneficiaryBankName Beneficiary bank name is invalid! ReferenceNumber Reference number is invalid! Details Payment details or reference number must be set! ReferenceLV Reference number is not supported in Latvia! ReferenceNumberTooLong The Creditor Reference number is too long! InvalidIdentificationType Invalid Identification type! nameMatchIsTooSmall bothDetailsAndCreditorReferenceFilled The account number and the name do not coincide! Payment details are missing! missingDetailsOrReferenceNumber Payment details or reference number must be set! beneficiaryNameTooLong Beneficiary name is too long! intrabankPaymentCannotBeUrgent Intrabank payment cannot be urgent! incorrectFormatOrderingPartyId Incorrect Ordering Party ID! missingOrderingPartyName Ordering party name is missing! incorrectFormatAssigneeId Incorrect Assignee ID! missingAssigneeName Assignee name is missing! domesticPaymentCouldBeOnlyInLocalCurrency Only local currency is allowed for domestic payments! Remitter and beneficiary accounts must be differ- paymentToTheSameAccountIsNotAllowed 19 ent! operationWithCurrencyNotAllowed Operation with this currency is not allowed! invalidValueDate Payment date is not valid for this agreement! missingBopCode Balance of Payments code is missing! ERR00010 Non-sufficient funds! ERR00104 Non-sufficient funds! ERR00112 Non-sufficient funds! ERR00596 Non-sufficient funds on remitter account! H0011 invalidInstructionIdentification Duplicate payment! You have already made a payment with the same data within 24 hours. Payment cancelled! Payment format is not supported, only ISO20022 format is accepted! Invalid instruction identification! invalidUltimateCreditorName Invalid ultimate creditor name! negativeOrZeroAmount Negative or zero amount! invalidBeneficiaryName Invalid beneficiary name! invalidDetails Invalid details! invalidCustomerReference Invalid customer reference! invalidCreditorIdentificationNumber Invalid creditor identification number! invalidDebtorAgentBIC Invalid debtor agent BIC! invalidCreditorAgentBIC Invalid creditor agent BIC! bothDetailsAndCreditorReferenceFilled Both details and creditor reference filled! urgentPaymentsNotAllowedAfterEuroDay Domestic payment cannot be urgent! TransactionNotSupported InvalidTransactionCurrency Transaction type not supported/authorized on this account Transaction currency is invalid or missing InvalidAmount Amount is invalid or missing InvalidBICIdentifier InvalidPaymentTypeInformation BIC identifier is invalid or missing. Generic usage if cannot specify between debit or credit account. Amount of funds available to cover specified message amount is insufficient. Number of decimal points not compatible with the currency Balance of payments complementary info is requested Associated message, payment information block, or transaction was received after agreed processing cut-off time. Payment Type Information is missing or invalid. InvalidTransactionCurrency Transaction currency is invalid or missing TransactionForbidden InvalidCreditorAccountNumber Transaction forbidden on this type of account (formerly NoAgreement) Creditor account number invalid or missing TooLowAmount Specified transaction amount is less than agreed OnlyISO20022FormatIsAccepted InsufficientFunds DecimalPointsNotCompatibleWithCurrency BalanceInfoRequest InvalidCutOffTime 20 minimum. TransactionForbidden InvalidCreditorBICIdentifier Transaction forbidden on this type of account (formerly NoAgreement) Creditor BIC identifier is invalid or missing InvalidCreditorAccountNumber Creditor account number invalid or missing InvalidChargeBearerCode Charge bearer code for transaction type is invalid MissingCreditorName Creditor name is missing InvalidCreditorAccountNumber Creditor account number invalid or missing InvalidCreditorBankIdentifier Creditor bank identifier is invalid or missing InvalidDate Invalid date (eg, wrong or missing settlement date) RemittanceInformationInvalid Remittance information structure does not comply with rules for payment type. Debtor or Ultimate Debtor identification code missing or invalid Creditor or Ultimate Creditor identification code missing or invalid Identification code missing or invalid. Generic usage if cannot specifically identify debtor or creditor. Reason is provided as narrative information in the additional reason information. InvalidDebtorIdentificationCode InvalidCreditorIdentificationCode InvalidIdentificationCode Narrative Currency exchange error codes Code Description ExchangeRateNotFound Currency not found! 6093 Currency exchange is not permitted! 6094 Currency exchange is not permitted! 21 Troubleshooting First be sure that messages were sent to right place, in order to confirm that the response must contain X-Gateway-Message header with value “1”. Only HTTP response 200 is not an indicator of successful connection! In case of problems, for example if IS has not received responses from the bank or there is suspicion that some messages are lost, please send the following data to your agreed contact person in the bank: Transport and ERP certificate information (CN, serial number, validity) or public key file Filename of the request message Message type of the request message (payment, statement request, ping, etc) Time when the message was sent IBAN account number The response received CorrelationId and/or RequestID of the message AgreementId, the unique agreement number you are addressing in request The more information the bank receives for troubleshooting the faster the bank will be able to answer and solve the issue. 22 Service – Communication test Service description Client initiated query to receive a ‘pong’ response to a ‘ping’ request. Client can receive multiple responses to a ping request: one with from=”HGW” indicating that the communication is working in general and additionally one reply from each country where the customer has an active agreement (from=”EE/LV/LT”). Value property from Ping request is returned with Pong response. Example request XML <?xml version="1.0" encoding="UTF-8"?> <Ping> <Value>Test</Value> </Ping> Description of fields in request XML Ping Ping/Value 1..1 AN (0 – 210) Something that customer wants to be sent back. 0..1 Example response XML <?xml version="1.0" encoding="UTF-8"?> <B4B xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://swedbankgateway.net/valid/hgw-response.xsd"> <Pong from="HGW"> <Value>Test</Value> </Pong> </B4B> Description of fields in response XML Pong 1..* Pong @ from A (3) EE/LT/LV/SGW – to show which processor responded. 1..1 Pong/Value AN (0 – 210) Value from Ping request. 1..1 23 Service – Account Balance Service description Client initiated query to receive the balance of one specific account or all accounts listed in SGW agreement on a given time. “Given time” is the most up to date balance bank can send to customer for the current day. The Account number given in the balance request has to correspond to the IBAN standard. It is also possible to specify a date in the past, in which case SGW returns the end-of-day balance for that day. Message with AccountNotAllowed exception is returned if account requested is not listed in any of SGW agreements available for given Client ERP Certificateand/or agreement ID If account number or agreementId is not specified, there will be one response for each country where an SGW agreement is visible for given transport/ERP certificate combination. Balances can be requested with ISO20022 format message camt.060.001.03 and SGW native XML format. Detailed implementation guidelines can be found at SGW development toolbox download site http://dev.hansagateway.net/download. SGW native XML format description can be found in SGW Service Description version 6.1 at http://dev.hansagateway.net/info. Format validation XSDs are available at http://dev.hansagateway.net/info. Access to these sites is IP-address based. Example request XML in ISO20022 camt.060.001.03 format <?xml version="1.0" encoding="UTF-8"?> <Document xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns="urn:iso:std:iso:20022:tech:xsd:camt.060.001.03"> <AcctRptgReq> <GrpHdr> <MsgId>camt060_balance</MsgId> <CreDtTm>2014-03-19T13:00:00</CreDtTm> </GrpHdr> <RptgReq> <ReqdMsgNmId>camt.052.001.02</ReqdMsgNmId> <Acct> <Id> <IBAN>LT117300010000131196</IBAN> </Id> </Acct> <AcctOwnr> <Pty/> </AcctOwnr> <RptgPrd> <FrToDt> <FrDt>2014-03-19</FrDt> <ToDt>2014-03-19</ToDt> </FrToDt> <FrToTm> <FrTm>09:00:00+02:00</FrTm> <ToTm>23:59:59+02:00</ToTm> </FrToTm> <Tp>ALLL</Tp> </RptgPrd> <ReqdBalTp> <CdOrPrtry> <Prtry>ONLYBALANCE</Prtry> </CdOrPrtry> </ReqdBalTp> </RptgReq> </AcctRptgReq> </Document> 24 Description of fields in request XML and response example in ISO20011 camt.052.001.02 format can be found in ISO MIG on SGW development toolbox download site http://dev.hansagateway.net/download. 25 Service – Payment Service description Payment is a customer-initiated query. Customer can send one or more payments with one request. Like all other SGW services, payment request is sent in one XML file contained in encrypted and signed file. Swedbank Gateway responds with one or more status reports as payments are being processed. Customer’s information system must be ready to split one payments request file into several smaller request files in case the original request file size exceeds the current maximum incoming message file size set in the channel. Keep in mind that different formats produce different size files per same amount of transactions! Payment service requires that signature container file containing payments is signed by Client’s ERP certificate and by at least one user with Signing certificate. The SGW agreement is located using agreement Id and the ERP certificate (as it is done with other services) while user Signing certificates define users and their access rights to the accounts that payments are made from. Supported formats Based on European Union’s SEPA (Single Euro Payments Area) regulation only the file format complying with the ISO20022 standard may be used in payment file import in Estonia, Latvia and Lithuania. Supported are ISO20022 format pain.001.001.02 and pain.001.001.03 messages with according pain.002.001.02 and pain.002.001.03 response messages. Preferred in the pain.001.001.03. Detailed implementation guidelines for supported formats can be found at SGW development toolbox download site http://dev.hansagateway.net/download. Format validation XSDs are available at http://dev.hansagateway.net/info. Access to these sites is IP-address based. Allowed characters and file encoding Allowed characters check is performed in case of interbank Domestic Payments and European Payments in Estonia and Latvia starting from 01.02.2014 and from 01.01.2016 in Lithuania due to SEPA clearing requirements. In UNIFI messages like ISO20022 messages the UTF8 encoding and the Latin character set, which is commonly used for international communication, must be used in the file. Encoding of the file must be declared in the XML header. In case the declared encoding does not match the detected encoding, following error message will be sent: <B4B> <HGWError> <Code>FileValidatingError</Code> <Message>Invalid byte 1 of 1-byte UTF-8 sequence.</Message> </HGWError> </B4B> The Latin character set contains the following characters: abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789 /-?:().,' + space Local characters In interbank Domestic Payments additionally local characters are allowed: In Estonia: Šš, Žž, Õõ, Ää, Öö, Üü In Latvia: Āā, Čč, Ēē, Ģģ, Īī, Ķķ, Ļļ, Ņņ, Šš, Ūū, Žž In Lithuania: Ąą, Čč, Ęę, Ėė, Įį, Šš, Ųų, Ūū, Žž 26 Whitelisted characters Commonly used characters, which will be accepted, but replaced in domestic bank-to-bank message with ?, are: &%#|_";=!€ XML escape characters Symbols not allowed in XML must be replaced in message according to escaping rules: & " ' < > must be replaced in XML message as & replaced with &amp; < replaced with &lt; " replaced with &quot; > replaced with &gt; ' replaced with &apos; Characters for all payment type references, identifications and identifiers Instruction ID, End-to-End ID, Transaction ID, Message ID, Payment Information ID, Creditor and Debtor ID, Ultimate Debtor/Creditor ID, Remittance ID, Proprietary codes must respect the following: • Content is restricted to the Latin character set • Content must not start or end with a ‘/’ • Content must not contain ‘//’s Limits and double acceptance condition SGW agreement enables setting specific limits for payments that every payment is checked against daily limit (reset every midnight); monthly limit (reset at midnight on the first of every month); callback limit. Additionally, it is possible to set separate daily and monthly limits for each user who is permitted to make transactions (operations like payment and currency exchange). User daily limit is mandatory to set. Limits are defined in local currency and payment amount is checked against them after being converted into local currency using central bank rate. For each user it is possible to set specific double acceptance condition per account/transaction type. Double acceptance condition means that transaction is accepted by Swedbank for processing only if two signers with appropriate rights have signed the request and the limits set for the last signer (i.e. usable daily and monthly limit) are sufficient to cover the payment. Payment sum is always deducted from the second signer’s limits. Currency Exchange sum and Intra-company Payment sum is not deducted from either of the signers limit. Intra-company Payment means payment between two Swedbank accounts belonging to the same company. If a certain sum is entered to double acceptance filter Starting from Sum, then the second signature is required only for payments equal to/exceeding that sum. Signature container file with payment request XML can include many payments and many signatures. If multiple users have signed payment request then SGW will check double acceptance condition fulfillment and limits of users in the order of signatures - earliest (time-wise) first. If first signer has no double acceptance required for unique payment inside signature container for account involved, and all limit checks are successful, then further signatures are ignored. If first signature has double acceptance required for unique payment inside signature container for account involved, SGW checks next signature - if that one does not have double acceptance required for that 27 account, the payment will be processed. If both signatures have double acceptance required for the account, they will be checked for limits. SGW will repeat the cycle described per each contained payment through signatures in order of signing until double acceptance condition is fulfilled by 2 signatures OR a signature without a double acceptance requirement with sufficient available limit is found. If no user has enough available limit left for given payment, that payment will fail with error code showing whether it was daily limit or monthly limit that was not enough (daily limit is checked first). If payment amount exceeds the call-back limit in the agreement, payment will be made only after back-office employee has called and verified payment. Duplicity check If payment with same data for fields: - Beneficiary Account, - Remitter Account, - payment date, - payment amount, - currency, - Beneficiary Reference Number, - Payment details, - Document number is received by SGW within 24 hours, then channel marks it automatically as duplicate payment and it will not be automatically sent to debiting. Payment will be made only after back-office employee has verified payment with the customer. For optional fields such as Document number, Payment details, Beneficiary Reference Number „same data“ means a) filled for both and with equal value OR b) not filled for both. Example request XMLin ISO20022 pain.001.001.03 format <?xml version="1.0" encoding="UTF-8"?> <Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <CstmrCdtTrfInitn> <GrpHdr> <MsgId>201409251</MsgId> <CreDtTm>2015-03-18T11:16:58.696</CreDtTm> <NbOfTxs>3</NbOfTxs> <CtrlSum>1.6</CtrlSum> <InitgPty> <Nm>ETTEVÕTE AS</Nm> </InitgPty> </GrpHdr> <PmtInf> <PmtInfId>PMTID0025</PmtInfId> <PmtMtd>TRF</PmtMtd> <BtchBookg>false</BtchBookg> <NbOfTxs>3</NbOfTxs> <PmtTpInf> <SvcLvl> <Cd>SEPA</Cd> </SvcLvl> </PmtTpInf> <ReqdExctnDt>2015-03-18</ReqdExctnDt> <Dbtr> <Nm>Mari Jüri</Nm> <PstlAdr> <Ctry>EE</Ctry> <AdrLine>Metsa 8, Tallinn</AdrLine> </PstlAdr> 28 </Dbtr> <DbtrAcct> <Id> <IBAN>EE942200221017496868</IBAN> </Id> <Ccy>EUR</Ccy> </DbtrAcct> <DbtrAgt> <FinInstnId> <BIC>HABAEE2X</BIC> </FinInstnId> </DbtrAgt> <ChrgBr>SLEV</ChrgBr> <CdtTrfTxInf> <PmtId> <InstrId>11500001</InstrId> <EndToEndId>32700001</EndToEndId> </PmtId> <Amt> <InstdAmt Ccy="EUR">0.10</InstdAmt> </Amt> <Cdtr> <Nm>FIRMA AS</Nm> <PstlAdr> <Ctry>EE</Ctry> <AdrLine>Leevikese 5,Tallinn</AdrLine> </PstlAdr> </Cdtr> <CdtrAcct> <Id> <IBAN>EE572200221017496855</IBAN> </Id> </CdtrAcct> <RmtInf> <Strd> <CdtrRefInf> <Tp> <CdOrPrtry> <Cd>SCOR</Cd> </CdOrPrtry> </Tp> <Ref>8806947</Ref> </CdtrRefInf> </Strd> </RmtInf> </CdtTrfTxInf> <CdtTrfTxInf> <PmtId> <InstrId>1160000000X</InstrId> <EndToEndId>3280002578</EndToEndId> </PmtId> <Amt> <InstdAmt Ccy="EUR">0.85</InstdAmt> </Amt> <Cdtr> <Nm>Mari Ööbik</Nm> <PstlAdr> <Ctry>EE</Ctry> <AdrLine>Siinseal, Tallinn</AdrLine> </PstlAdr> </Cdtr> <CdtrAcct> <Id> <IBAN>EE652200221006102024</IBAN> </Id> </CdtrAcct> <RmtInf> <Ustrd>TEXT..TEXT</Ustrd> 29 <Strd> <CdtrRefInf> <Tp> <CdOrPrtry> <Cd>SCOR</Cd> </CdOrPrtry> </Tp> <Ref>88069474660</Ref> </CdtrRefInf> </Strd> </RmtInf> </CdtTrfTxInf> <CdtTrfTxInf> <PmtId> <InstrId>11700001</InstrId> <EndToEndId>32902545</EndToEndId> </PmtId> <Amt> <InstdAmt Ccy="EUR">0.65</InstdAmt> </Amt> <CdtrAgt> <FinInstnId> <BIC>NDEAFIHH</BIC> </FinInstnId> </CdtrAgt> <Cdtr> <Nm>Ettevõte OY</Nm> <PstlAdr> <Ctry>FI</Ctry> <AdrLine>ADDRESS 1, HELSINKI</AdrLine> </PstlAdr> </Cdtr> <CdtrAcct> <Id> <IBAN>FI05240018000055487</IBAN> </Id> </CdtrAcct> <RmtInf> <Ustrd>Foreign Payment EE</Ustrd> </RmtInf> </CdtTrfTxInf> </PmtInf> </CstmrCdtTrfInitn> </Document> Description of fields in request XML can be found in ISO MIG on SGW development toolbox download site http://dev.hansagateway.net/download. Example response XML in ISO20022 pain.002.001.03 format If in one file has payments from three different countries (domestic payment in Estonia, domestic payment in Latvia, domestic payment and foreign payment in Estonia), there will be at least three responses to it (each country processes payments separately). If for some reason it is not possible to debit domestic payments during first processing (customer might not have had enough money on account or payment’s value date is later than banking day are most common reasons for it), domestic payment will be first put into processing state. There will be a separate status report about payment when it has been processed further. <?xml version="1.0" encoding="UTF-8"?> 30 <Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03"> <CstmrPmtStsRpt> <GrpHdr> <MsgId>20150317-153148975-3445-1750/3569</MsgId> <CreDtTm>2015-03-18T12:45:43</CreDtTm> <InitgPty> <Id> <OrgId> <BICOrBEI>HABAEE2X</BICOrBEI> </OrgId> </Id> </InitgPty> </GrpHdr> <OrgnlGrpInfAndSts> <OrgnlMsgId>201409251</OrgnlMsgId> <OrgnlMsgNmId>pain.001.001.03</OrgnlMsgNmId> <OrgnlNbOfTxs>3</OrgnlNbOfTxs> <OrgnlCtrlSum>1.6</OrgnlCtrlSum> <GrpSts>PART</GrpSts> </OrgnlGrpInfAndSts> <OrgnlPmtInfAndSts> <OrgnlPmtInfId>PMTID0025</OrgnlPmtInfId> <PmtInfSts>PART</PmtInfSts> <OrgnlInstrId>1160000000X</OrgnlInstrId> <OrgnlEndToEndId>3280002578</OrgnlEndToEndId> <TxSts>ACSC</TxSts> <AcctSvcrRef>2015031800000315-1</AcctSvcrRef> <OrgnlTxRef> <Amt> <InstdAmt Ccy="EUR">0.85</InstdAmt> </Amt> <ReqdExctnDt>2015-03-18</ReqdExctnDt> <Dbtr> <Nm>ETTEVÕTE AS</Nm> </Dbtr> <DbtrAcct> <Id> <IBAN>EE942200221017496868</IBAN> </Id> </DbtrAcct> <DbtrAgt> <FinInstnId> <BIC>HABAEE2X</BIC> </FinInstnId> </DbtrAgt> <CdtrAgt> <FinInstnId> <BIC>HABAEE2X</BIC> </FinInstnId> </CdtrAgt> <Cdtr> <Nm>FIRMA AS</Nm> </Cdtr> <CdtrAcct> <Id> <IBAN>EE572200221017496855</IBAN> </Id> </CdtrAcct> </OrgnlTxRef> </TxInfAndSts> <TxInfAndSts> <OrgnlInstrId>11700001</OrgnlInstrId> <OrgnlEndToEndId>32902545</OrgnlEndToEndId> <TxSts>ACSP</TxSts> <OrgnlTxRef> <Amt> <InstdAmt Ccy="EUR">0.65</InstdAmt> </Amt> 31 <ReqdExctnDt>2015-03-18</ReqdExctnDt> <Dbtr> <Nm>ETTEVÕTE AS</Nm> </Dbtr> <DbtrAcct> <Id> <IBAN>EE942200221017496868</IBAN> </Id> </DbtrAcct> <DbtrAgt> <FinInstnId> <BIC>HABAEE2X</BIC> </FinInstnId> </DbtrAgt> <CdtrAgt> <FinInstnId> <BIC>NDEAFIHH</BIC> </FinInstnId> </CdtrAgt> <Cdtr> <Nm>FIRMA Oyj Ab</Nm> </Cdtr> <CdtrAcct> <Id> <IBAN>FI0524001800005407</IBAN> </Id> </CdtrAcct> </OrgnlTxRef> </TxInfAndSts> <TxInfAndSts> <OrgnlInstrId>11500001</OrgnlInstrId> <OrgnlEndToEndId>32700001</OrgnlEndToEndId> <TxSts>RJCT</TxSts> <StsRsnInf> <Rsn> <Cd>NARR</Cd> </Rsn> <AddtlInf>AccountNotFound</AddtlInf> </StsRsnInf> <OrgnlTxRef> <Amt> <InstdAmt Ccy="EUR">0.10</InstdAmt> </Amt> <ReqdExctnDt>2015-03-18</ReqdExctnDt> <Dbtr> <Nm>ETTEVÕTE AS</Nm> </Dbtr> <DbtrAcct> <Id> <IBAN>EE942200221017496868</IBAN> </Id> </DbtrAcct> <DbtrAgt> <FinInstnId> <BIC>HABAEE2X</BIC> </FinInstnId> </DbtrAgt> <Cdtr> <Nm>FIRMA AS</Nm> </Cdtr> <CdtrAcct> <Id> <IBAN>EE142200221002167820</IBAN> </Id> </CdtrAcct> </OrgnlTxRef> </TxInfAndSts> </OrgnlPmtInfAndSts> 32 </CstmrPmtStsRpt> </Document> Description of fields in response XML can be found in ISO MIG on SGW development toolbox download site http://dev.hansagateway.net/download. 33 Service – Account statement Service description Customer can use this service to request a list of transactions on account in a given period. The period range can be up to 90 days. If the period also includes current day, the request is charged – also the service Current Day Statement has to be active in SGW agreement. Account statement is returned in one or more responses with one response containing up to 10 000 transaction records. This is a current limit which might change. Limit can differ based on the format requested. Response format is determined by the customer request format. Supported formats include ISO20022 camt.053.001.02 (described below)/ camt.052.001.02 - responses to the camt.060.001.03 request, SGW native XML and FidaVista 1.01. Detailed implementation guidelines for ISO20022 and Fidavista 1.01 account statement request and response can be found at SGW development toolbox download site http://dev.hansagateway.net/download. SGW native XML format detailed description can be found in SGW Service Description version 6.1 at http://dev.hansagateway.net/info. Access to the sites is IPaddress based. Example request XML in ISO20022 camt.053.001.02 format <?xml version="1.0" encoding="UTF-8"?> <Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.060.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <AcctRptgReq> <GrpHdr> <MsgId>112324345136</MsgId> <CreDtTm>2014-06-10T17:00:00</CreDtTm> </GrpHdr> <RptgReq> <Id>reportRequestId</Id> <ReqdMsgNmId>camt.053.001.02</ReqdMsgNmId> <Acct> <Id> <IBAN>EE392200221011508011</IBAN> </Id> </Acct> <AcctOwnr> <Pty/> </AcctOwnr> <RptgPrd> <FrToDt> <FrDt>2014-06-18</FrDt> <ToDt>2014-06-18</ToDt> </FrToDt> <FrToTm> <FrTm>00:00:00+02:00</FrTm> <ToTm>23:59:59+02:00</ToTm> </FrToTm> <Tp>ALLL</Tp> </RptgPrd> </RptgReq> </AcctRptgReq> </Document> More detailed examples and description of fields in request and response XML can be found in ISO MIG on SGW development toolbox download site http://dev.hansagateway.net/download. 34 Latvian codes for Transaction/TypeCode Value Description OB Opening balance CB Closing balance K2 Turnover T2 Fees amount PRV Internal transfer MK Domestic currency payment IEM Cash lodgement IZM Cash withdrawal INB Incoming transfer IZP Outgoing transfer CTX Payment card transactions SOD Standing order EXC Currency exchange CQA Cashing of a cheque KOM Comission for cash withdrawal/ Comission for a transfer/ Cheques commission DKA Deposit or escrow account opening DPL Deposit breach or deal settlement AUT End of deposit AIA Accrued interest payment into account AZA Loan repayment SEC Securities operations TBP T-bill purchase TBC T-bill comission 7DN Amount booking IKS Cash delivery Estonian codes for Transaction/TypeCode Value Description TT Service charge - indicating that the transaction was Bank's service fee MK Domestic payment order - i.e. regular payment inside the value country MV International payment order MP Consolidated payment M Other charges K Card transaction 35 X Currency transaction I Interest PT Standing order service charges MD Deposits S Cash operation Lithuanian codes for Transaction/TypeCode Value Description AS Opening balance LS Closing balance K1 Daily turnover K2 Account turnover over the specified period MK DP Payment orders within the bank and between banks incorporated in Lithuania, in LTL and currency Debit orders and collections MV International payment orders S Cash operation IM Payments IMG Payments in cash in a branch IMB Payments in a branch (transfer) IME Payments via Internet bank MD Operation related to the deposit MP Mass payment DD Direct debit operation X Currency conversion K Card operation TS Operations with Bank, Traveller's Cheques M Interest, manual debiting and crediting operations I Interest, loan interest, overdrafts AI Accrued interest PV Value added tax TT, TT1-TT10 Charges TT11 Operation related to the loan TT12 Information on accounts, document processing and sending TT13 Direct debit fees TT14 Account maintenance fee, payment fee T2 Total charges G Total charges 36 PT Charge for regular payment order CTX Payments via ATM (automated teller machines) SMS Payment via SMS (mobile bank) S1 Balance BL Bank link payments 37 Service – Exchange rates Service description Customer can use this service to request currency exchange rates from different countries in Swedbank. SGW is providing currency rates for cash exchange (only current rate), local central bank (current rate and history) and currency exchange on account (current rate and history). It is possible to query rates for one, several or all rated currencies. Error message is sent as response if period requested is in future, past rates for cash exchange are requested, BIC of wrong bank is given or if requested transaction type is not allowed for some of given currencies. Response data is ordered by currency code and rate date. In case of central bank rates (ExchangeRateType is Central in request XML), buy and sell rates for currency are same. Example request XML <?xml version="1.0" encoding="UTF-8"?> <ExchangeRateRequest> <BIC>HABAEE2X</BIC> <ExchangeRateType>Transfer</ExchangeRateType> <StartDate>2007-06-27</StartDate> <EndDate>2007-07-01</EndDate> <Currencies> <Currency>USD</Currency> <Currency>NOK</Currency> <Currency>EUR</Currency> </Currencies> </ExchangeRateRequest> Description of fields in request XML ExchangeRateRequest Root element of request document 1..1 1..1 BIC AN (8) ExchangeRateType A Code of bank that should respond (HABAEE2X for Estonian, HABALV2X for Latvian and HABALT2X for Lithuanian branch) Transfer/Cash/Central StartDate D If not given, current banking day is used 0..1 EndDate D If not given, current banking day is used 0..1 Container element for currencies listing. If not given, all allowed currencies are listed in response 0..1 Currencies Currencies/Currency A (3) 1..1 1..* Example response XML <?xml version="1.0" encoding="UTF-8"?> <B4B xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://swedbankgateway.net/valid/hgw-response.xsd"> <ExchangeRateResponse> <BIC>HABAEE2X</BIC> <ExchangeRateType>Transfer</ExchangeRateType> <ExchangeRateInfo BaseCurrency="EEK"> <CurrencyInfo Date="2007-06-30"> <Currency>EUR</Currency> <Buy>15.62000</Buy> 38 <Sell>15.67350</Sell> </CurrencyInfo> <CurrencyInfo Date="2007-07-01"> <Currency>EUR</Currency> <Buy>15.62000</Buy> <Sell>15.67350</Sell> </CurrencyInfo> <CurrencyInfo Date="2007-06-30"> <Currency>NOK</Currency> <Buy>1.96000</Buy> <Sell>1.99200</Sell> </CurrencyInfo> <CurrencyInfo Date="2007-07-01"> <Currency>NOK</Currency> <Buy>1.96000</Buy> <Sell>1.99200</Sell> </CurrencyInfo> <CurrencyInfo Date="2007-06-30"> <Currency>USD</Currency> <Buy>12.25400</Buy> <Sell>12.48850</Sell> </CurrencyInfo> <CurrencyInfo Date="2007-07-01"> <Currency>USD</Currency> <Buy>12.25400</Buy> <Sell>12.48850</Sell> </CurrencyInfo> </ExchangeRateInfo> </ExchangeRateResponse> </B4B> Description of fields in response XML B4B/ExchangeRateResponse Container element for response 1..1 BIC AN (8) Code of bank responding 1..1 ExchangeRateType A Transfer/Cash/Central 1..1 Container element for currencies listing in ExchangeRateResponse element. Currency against what rates are given by bank is contained in BaseCurrency attribute. Container element for currency info in ExchangeRateInfo element Date parameter of CurrencyInfo element. 1..1 ExchangeRateInfo ExchangeRateInfo @ BaseCurrency A (3) CurrencyInfo 1..1 0..* CurrencyInfo @ Date D 1..1 CurrencyInfo/Currency A (3) CurrencyInfo/Buy N Bank buys at this rate 1..1 CurrencyInfo/Sell N Bank sells at this rate 1..1 1..1 39 Service – Currency exchange Service description Customer can use this service to request currency exchange on given account. It is possible to specify worst acceptable rates for both currencies in currency exchange request and SGW will send error if any of rates offered by bank is not good enough to match them. SGW will also send error in cases when: - there are not enough funds in sell currency on account - transactions are disabled in bank information system - given BIC does not belong to Swedbank. Currency exchange service similarly to payments service requires that request file is signed at least by one user with Signing certificate. The SGW agreement is located using the ERP certificate (as it is done with other services) while user Signing certificates define users and their access rights to the accounts that currency exchange is made from. Read more about user access right checking (limits, double acceptance, etc) from Payment service chapter. Example request XML <?xml version="1.0" encoding="UTF-8"?> <CurrencyExchangeRequest> <BIC>HABAEE2X</BIC> <IBAN>EE922200221010214144</IBAN> <Buy> <Currency>USD</Currency> <Amount>2500</Amount> <Rate>11.50811</Rate> </Buy> <Sell> <Currency>EUR</Currency> <Rate>15.638</Rate> </Sell> </CurrencyExchangeRequest> Description of fields in request XML BIC AN (8) 1..1 AN (4 – 35) BIC of Swedbank’s local branch (HABAEE2X for Estonian, HABALV2X for Latvian and HABALT2X for Lithuanian branch). Account number where currency exchange is performed. IBAN Buy/Currency A (3) Currency that customer wishes to buy. 1..1 Buy/Amount N 0..1 Buy/Rate N Sell/Currency A (3) Amount that customer wishes to buy. Has to be empty when sell amount is given, is calculated from sell amount then. When given, bank will perform exchange only if rate offered by bank is same or better than this. Currency that customer wishes to sell. Sell/Amount N 0..1 Sell/Rate N Amount that customer wishes to sell. Has to be empty when buy amount is given and is calculated from buy amount then. When given, bank will perform exchange only if rate offered by bank is same or better than this. 1..1 0..1 1..1 0..1 When currency exchange is performed successfully the response contains rates used and bank reference code. 40 Example response XML <?xml version="1.0" encoding="UTF-8"?> <B4B xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://swedbankgateway.net/valid/hgw-response.xsd"> <CurrencyExchangeResponse> <BIC>HABAEE2X</BIC> <IBAN>EE562200221008103199</IBAN> <BankReference>2007070200000195</BankReference> <Buy> <Currency>USD</Currency> <Amount>2500.00</Amount> <Rate>12.48850</Rate> </Buy> <Sell> <Currency>EUR</Currency> <Amount>1998.80</Amount> <Rate>15.62000</Rate> </Sell> </CurrencyExchangeResponse> </B4B> Description of fields in response XML B4B/CurrencyExchangeResponse Container element for response 1..1 BIC AN (8) Code of bank responding 1..1 IBAN AN (4 – 35) 1..1 BankReference N (16) Account number where currency exchange is performed. Bank reference for operation Buy/Currency A (3) Currency that customer bought 1..1 Buy/Amount N Amount that customer bought 1..1 Buy/Rate N Sell/Currency A (3) Currency that customer sold 1..1 Sell/Amount N Amount that customer sold 1..1 Sell/Rate N ExchangeRateType A ExchangeRateInfo 1..1 1..1 1..1 Transfer 1..1 Container element for currencies listing in ExchangeRateResponse element. 1..1 41 Service – Alert on transactions Service description It is possible for a customer to get a notification about every transaction that is booked on a given account. This chargeable service has to be activated for every account through SGW agreement and customer can choose to be notified about incoming payments or outgoing payments. Additionally alerts can be filtered by currency and amount – only transactions in certain currency (EUR or all currencies) and exceeding the specified amount in that currency will send a notification. Customer can also choose the format of the Alert message – supported formats include ISO20022 camt.054.001.02., FidaVista 1.01 and SGW native XML. Detailed implementation guidelines for Fidavista 1.01 and ISO20022 Alert message can be found at SGW development toolbox download site http://dev.hansagateway.net/download. Detailed implementation guidelines for SGW native XML format can be found in SGW Service Description version 6.1 at http://dev.hansagateway.net/info. Format validation XSDs are available at http://dev.hansagateway.net/info. Access to these sites is IP-address based. It is important to mention that alert message XML is only encrypted and put into BDOC container, but we do not add bank signature in case of alert. For every transaction matching the filter set in SGW agreement a message is created for each ERP certificate assigned to the agreement. Message is waiting to be picked up for 24 hours, after which it will be deleted from the system. Example request XML There is no request – bank is generating these messages based on SGW agreement details. Example response XML camt.054.001.02 It differs from statement response only by different container element (Alert instead of Statement) and missing statement-specific elements (Period, Partial and starting-ending balances for currency). 42 Service – Periodic statement Service description It is possible for a customer to get an account statement automatically according to global schedule bank is using for all regular statements (this is once per day and bank will try to send it before midday). Statement will be generated for previous day from 00:00 until 24:00. If no transactions are made on that day, empty statement with just balance information will be generated by default. But customer can also specify in the service agreement, that statement without transactions is not generated. Periodic statement is sent in one or more responses with one response containing up to 10 000 transaction records. This is a current limit which might change. Limit can differ based on the format selected in the SGW agreement. Supported formats include ISO20022 camt.053.001.02, SGW native XML and FidaVista 1.01. Detailed implementation guidelines for ISO20022 and Fidavista 1.01 account statement request can be found at SGW development toolbox download site http://dev.hansagateway.net/download. Detailed implementation guidelines for SGW native XML format can be found in SGW Service Description version 6.1 at http://dev.hansagateway.net/info. Access to this site is IP-address based. Every statement is encrypted for client ERP certificate tied to given SGW agreement. Example request XML There is no request – bank is generating these messages based on SGW agreement details. Example response XML Start date is either current banking day (for first statement) or day of the last operation in previous statement. End date is always current banking day. Otherwise response is just like an Account statement service response. If there were no transactions since previous statement’s last operation, an empty statement with opening and closing balances is sent. 43 Service – Sending e-invoices Before using this service, it is important to know the terms and conditions of e-invoicing service in the country of operations. An E-invoice sending service agreement must be entered into in order to send E-invoices to Bank. Although e-invoice operations exists in all Baltic countries, local implementations differ both from dataset and service range point of view. The applicability of the current Einvoice format may be verified using the XSD schema available on the website of Bank. Service description Swedbank allows operators and sellers to send e-invoices that are meant for Swedbank customers. Einvoices sent to others banks Swedbank forwards to their designated address (only in Estonia and Lithuania) . This service differs from other SGW services because it requires two .xml documents in a signature container – one that SGW uses to locate e-invoice agreement for customer and the other containing the actual e-invoices. SGW is sending this container file to e-invoices processor and responds to customer with processing result. SGW requires that in case of several files in one signature container, request file name has to end with “–request.xml”. That file is processed as SGW request .xml and validated against hgw.xsd. IS must be ready to split a large e-invoice file into several smaller files in case the original file size exceeds the current maximum incoming message file size set in the channel. Example request XML (einvoice-request.xml) <?xml version="1.0" encoding="UTF-8"?> <EinvoiceIncoming> <Filename>einvoices.xml</Filename> <CountryCode>EE</CountryCode> <ContractId>12345</ContractId> </EinvoiceIncoming> Description of fields in request XML Filename AN Name of the payload file in signature container. 1..1 CountryCode A (2) 0..1 ContractId AN Country code – can be omitted if customer has SGW agreement in only one country. EE/LV/LT otherwise. E-invoice seller agreement number owned by the einvoice file importer. 1..1 Estonian e-invoice version 1.11 Currently supported e-invoice format in Estonia are 1.11 and 1.2. Estonian e-invoice format descriptions can be found at http://www.pangaliit.ee/et/arveldused/e-arve. Estonian E-invoice version 1.11 is based on 2 separate documents: Description of Estonian electronic invoice (Ver. 1.1) Guidelines for Description of Estonian Electronic Invoice. Sending e-invoices to the bank and presentment of e-invoices at the bank (Ver 1.05) The latter gives overview of differences between version 1.1 and 1.11 and describes the added parameters. 44 E-invoice XML file can be validated against XSD validator provided by Estonian Banking Association on their website http://www.pangaliit.ee/images/files/E-arve/xsd_schemas.zip By agreement, bank verifies at least the following parameters on e-invoices sent to it: Conformity of file to agreed-upon e-invoice description (XML validation) Business-logic and technological verification of information in file Swedbank Gateway always notifies seller/operator upon receipt of e-invoices with VEA file. If file was accepted and no faulty e-invoices found, then empty response is returned Example response XML (success, EE) <?xml version="1.0" encoding="UTF-8" ?> <FailedInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="veaFailedInvoice.xsd"> <Header appId="VEA" date="2013-05-09" receiverId="SellerId" senderId="HABAEE2X" fileId="001" infileId="test252" /> <Footer totalNr="0" /> </FailedInvoice> Example response XML (errors on file level, EE) If file was incorrect (missing xsd, invalid xml) then file based error code is returned in header attribute fileFailReason. <?xml version="1.0" encoding="UTF-8" ?> <FailedInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="veaFailedInvoice.xsd"> <Header appId="VEA" date="2013-05-09" receiverId="SellerId" senderId="HABAEE2X" fileId="002" infileId="001" fileFailReason="51" /> <Footer totalNr="0" /> </FailedInvoice> Example response XML (errors on invoices level, EE) If file included faulty einvoices (missing agreement, incorrect account etc), then response file will include Invoice block with errorcode. <?xml version="1.0" encoding="UTF-8" ?> <FailedInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="veaFailedInvoice.xsd"> <Header appId="VEA" date="2013-05-09" receiverId="SellerId" senderId="HABAEE2X" fileId="002" infileId="001" /> <Invoice> <ChannelId>HABAEE2X</ChannelId> <InvoiceId>C923949</InvoiceId> <InvoiceGlobUniqId>ARVE_150087</InvoiceGlobUniqId> <ServiceId>1234</ServiceId> <SellerContractId>3975415</SellerContractId> <SellerRegNumber>111</SellerRegNumber> <FailReason>33</FailReason> </Invoice> <Footer totalNr="1" /> </FailedInvoice> Latvian e-invoice version 1.0 Currently supported e-invoice format in Latvia is 1.0. Latvian e-invoice format descriptions can be found at: https://www.swedbank.lv/en/pakalpojumi_uznemumiem/e_rekini/ Latvian E-invoice version 1.0 is based on 2 separate documents: 45 Description of Latvian electronic invoice (Ver. 1.0) Technical conditions of Latvian e-invoice E-invoice XML file can be validated against XSD validator, available at: https://www.swedbank.lv/files/pakalpojumi_uznemumiem/e_rekins/E_invoice_LV_XSD.zip . All einvoice service related validators are available also at SGW development toolbox site http://dev.hansagateway.net/info (LV e-invoice 1.0 XSD: http://dev.hansagateway.net/info/einvoice_lv_1.0.xsd ). Access to this site is IP-address based. Swedbank Gateway always notifies seller/operator upon receipt of e-invoices with FEI file. If file was accepted and no faulty e-invoices found, then empty response is returned Example response XML (success, LV) <?xml version="1.0" encoding="UTF-8" ?> <FailedInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="veaFailedInvoice.xsd"> <Header appId="FEI" date="2014-10-09" fileId="1001573956" infileId="headerLV11" receiverId="" senderId="HABALV22" /> <Footer totalNr="0" /> </FailedInvoice> Example response XML (errors on file level, LV) If file was incorrect (missing xsd, invalid xml) then file based error code is returned in header attribute fileFailReason. <?xml version="1.0" encoding="UTF-8" ?> <FailedInvoice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="veaFailedInvoice.xsd"> <Header appId="FEI" date="2014-09-10" fileFailReason="51" infileId="" receiverId="" senderId="HABALV22" /> <Footer totalNr="0" /> </FailedInvoice> Example response XML (errors on invoices level, LV) If file included faulty einvoices (missing agreement, incorrect account etc), then response file will include Invoice block with errorcode. <?xml version="1.0" encoding="UTF-8" ?> <FailedInvoice xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation="veaFailedInvoice.xsd"> <Header appId="FEI" date="2014-10-01" fileId="1001551112" infileId="headerLV-112481174" receiverId="" senderId="HABALV22" /> <Invoice> <ChannelId>HABALV22</ChannelId> <InvoiceId>456790</InvoiceId> <InvoiceGlobUniqId>1234</InvoiceGlobUniqId> <ServiceId>1337</ServiceId> <SellerContractId>254808</SellerContractId> <SellerRegNumber>80808080</SellerRegNumber> <FailReason>104</FailReason> </Invoice> <Footer totalNr="1"/> </FailedInvoice> Lithuanian e-invoice version 1.1 Currently supported e-invoice format in Lithuania is 1.1. 46 Technical requirements of E-invoice (hereinafter – Technical requirements) is based on Lithuanian Banking Association approved technical standard, which can be found here: http://www.lba.lt/go.php/lit/E._saskaita_/2638. Swedbank specific e-invoice technical conditions, including examples, can be found here: https://www.swedbank.lt/en/pages/corporate/submission_of_e_invoices. Swedbank Gateway always notifies seller/operator upon receipt of e-invoices with FEI file. If file was accepted and no faulty e-invoices found, then empty respone is returned <?xml version="1.0" encoding="UTF-8"?> <FailedInvoice> <Header appId="FEI" date="2015-10-16" senderId="HABALT22" fileId="1016888841"/> <Footer totalNr="0"/> </FailedInvoice> If file was incorrect (missing xsd, unparseable xml) then filebased errorcode is returned in header attribute fileFailReason. <?xml version="1.0" encoding="UTF-8"?> <FailedInvoice> <Header appId="FEI" date="2015-10-16" senderId="HABALT22" fileId="1016888841" fileFailReason="51"/> <Footer totalNr="0"/> </FailedInvoice> If file included faulty e-invoices (missing internetbank agreement, incorrect account etc), then response file will include Invoice block with errorcode and multiple errorcodes are to be expected. Errorcodes are described in Lithuanian Banking Association document, Swedbank specific errorcodes can be found in Swedbank e-invoice technical conditions <?xml version="1.0" encoding="UTF-8" ?> <FailedInvoice xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation="veaFailedInvoice.xsd"> <Header appId="FEI" date="2015-10-16" fileId="1016777741" infileId="0917545792" senderId="HABALT22" /> <Invoice> <ChannelId>HABALT22</ChannelId> <InvoiceId>456790</InvoiceId> <InvoiceGlobUniqId>1234</InvoiceGlobUniqId> <ServiceId>1337</ServiceId> <GlobalSellerContractId>1017968HABALT2241</GlobalSellerContractId>> <SellerRegNumber>1017968</SellerRegNumber> <FailReason>104</FailReason> </Invoice> <Footer totalNr="1"/> </FailedInvoice> Description of fields in response XML FailedInvoice Root element 1..1 Header Container element inside FailedInvoice 1..1 1..1 Header @ appId A(3) Header @ date D Enumeration value=”VEA” in Estonia, Enumeration value=”FEI” in Latvia, Response message date Header @ receiverId AN(20) Receiver Id 1..1 Header @ senderId AN(20) Sender (bank) Id, HABAEE2X for Swedbank EE, HABALV22 for Swedbank 1..1 1..1 47 LV Header @ fileId AN(20) Response file Id 0..1 Header @ infileId AN(20) Original e-invoice file Id 0..1 Header @ fileFailReason N Positive integer. Error code identifying the fail reason, see Error codes. Container element inside FailedInvoice for each defective e-invoice BIC code of bank where the error situation came up Value of the InvoiceId attribute in the Invoice element of the e-invoice sent to the bank Value of the GlobUniqId attribute from the Invoice element of the e-invoice sent to the bank Value of the serviceId attribute from the Invoice element of the e-invoice sent to the bank 0..1 Seller’s contract ID in Estonia and Latvia Seller’s contract ID in Lithuania 0..1 Seller’s registry code from the RegNumber element under SellerParty Positive integer. Bank e-invoice error code. See Error codes Container element inside FailedInvoice 0..1 Positive integer. Total number of failed invoices 1..1 Invoice Invoice /ChannelId AN(11) Invoice / InvoiceId AN(100) Invoice / invoiceGlobUniqId AN(100) Invoice /ServiceId Invoice / SellerContractId EE, LV: AN(20) LT: AN(35) AN(100) Invoice / GlobalSellerContractId AN(100) Invoice/SellerRegNumber AN(15) Invoice/FailReason N Footer Footer@ totalNr N 0..* 0..1 1..1 0..1 0..1 0..1 1..1 1..1 Error codes Code Reason File-related errors 51 File structure incorrect 59 Lacks reference DTD or XSD file 56 Total invoices amount in file incorrect (the TotalAmount element in the Footer element) File with same ID or name already exists 64,65 61 81,66 Total number of invoices in file incorrect (the TotaNumberInvoices element in the Footer element) AppId incorrect 63 File name does not conform to standard E-invoice header related (element Invoice) errors 82 File is lacking e-invoice address 3 E-invoice address does not exist at bank 22 E-invoice address is not intended for sending e-invoices (because it is 48 not a current account or related reason) 33 86 76,78, 58 87 80 E-invoice addressee lacks electronic possibility for presenting invoice (Internet bank lacking or closed) E-invoice addressee lacks possibility for presenting invoice electronically (Internet bank lacking or closed) but a standing order service agreement has been concluded for the invoice serviceId E-invoice channel is incorrect An e-invoice with the same invoiceGlobUniqId from the same e-invoice sender exists ServiceId incorrect (does not conform to seller’s agreement) Invoice content related errors 14 The e-invoice information needed for factoring is incorrect Buyer’s postal address missing 79 Seller related errors (if seller information is verified) 11 E-invoice’s seller information (registry code) incorrect 57 Seller’s agreement missing/blocked 70 Seller lacks privilege to send e-invoices E-invoice payment order information related errors (element PaymentInfo) 6 9 Reference number incorrect (PaymentRefId element does not conform to standard) Payment order reference number and details missing (PaymentRefId=““, PaymentDescription=““) Amount payable incorrect (PaymentTotalSum<0) 7 Currency payable incorrect (Currency) 49 E-invoice payment due date incorrect (PayDueDate<Today) 12 E-invoice with the same PaymentId from the same seller exists (If invoiceGlobUniqId is not specified for the invoice, the uniqueness of the PaymentId shall be verified in the PaymentInfo element.) Payee’s pay-to account incorrect (PayToAccount) 50 54 55 88 Seller incorrect (PayToName), can be verified if the seller’s bank is the same as the payer’s bank BIC code incorrect (PayToBIC) 88 BIC code incorrect (PayToBIC) 35 ERROR_CODE_BUYER_AND_SELLER_ACCOUNTS_ARE_THE_SAME 49 Validations performed upon E-invoice receipt in Estonia Figure 5: Swedbank validations performed upon E-invoice receipt in Estonia 50 Validations performed upon E-invoice receipt in Latvia Figure 6: Swedbank validations performed upon E-invoice receipt in Latvia 51 Validations performed upon E-invoice receipt in Lithuania Figure 7: Swedbank validations performed upon E-invoice receipt in Lithuania 52 General e-invoice file exchange process Figure 8: General e-invoice file exchange process layout in Estonia Figure 9: General e-invoice file exchange process layout in Latvia 53 Figure 10: General e-invoice file exchange process layout in Lithuania 54 Einvoice and e-invoice SOA/APA cancelling via Credit Invoice In order to disallow payment of an e-invoice sent to bank and cancel the SOA/APA payment order connected to the e-invoice Seller must send a Credit invoice to the bank. Swedbank finds the original e-invoice to be cancelled by following parameters: Invoice attribute sellerContractId Invoice attribute sellerRegnumber Invoice attribute channelAddress InvoiceInformation.SourceInvoice (specify the original e-invoice InvoiceInformation.InvoiceNumber). E-invoice recipient (Buyer) will see in Internetbank both the cancelled e-invoice and the credit invoice. In case Seller has sent several e-invoices with same InvoiceNumber to different addresses (if Seller has issued 2 or more copies of the same invoice - for instance one e-invoice has attribute presentment = Yes and the other one has attribute presentment = NO), then only the e-invoice with same address than the credit invoice will be cancelled. Thus Seller must send separate credit invoice (or copy of a credit invoice) per each debit e-invoice (or it’s copy) . Upon receipt of credit invoice, if possible, Swedbank will also cancel the payment order created based on e-invoice SOA/APA. In e-invoice response file (VEA/FEI) bank will always notify about the einvoice and e-invoice SOA/APA cancellations. Possible codes used in response are: 91 – Debit invoice not found. Invoice and SOA/APA payment order not cancelled 92 – The debit invoice linked with the credit invoice is already paid 93 – A credit invoice may not be Payable=Yes 102 – More than one invoice found. No invoices nor SOA/APA payment orders cancelled 103 – Debit invoice cancelled, SOA/APA payment order not found 104 – Debit invoice cancelled, SOA/APA payment order not cancelled 105 – Invoice and SOA/APA payment order cancelled Following restrictions apply to cancellation of e-invoice and e-invoice SOA/APA payment order: Swedbank can only guarantee cancellation of e-invoices sent to Swedbank. If Seller uses Swedbank as operator (available only in EE; Seller is sending e-invoices to other banks via Swedbank), credit invoice will be forwarded to the bank noted in credit invoice address, but the possibility to cancel e-invoice and connected SOA payment order depends on the recipient bank’s technical solution; In order to cancel SOA/APA payment order, Seller must send credit invoice to the adressee, who has e-invoice standing order agreement with corrsponding parameters (ie client number, personal code, apartment number) to the cancelled e-invoice; Response regarding e-invoice and SOA/APA cancellation result is sent only in case credit invoice address is Swedbank account; Only e-invoices forwarded to Buyer can be cancelled. In case e-invoices sent by Seller are waiting for second accept by other employee or are not forwarded to addressee due to some other reason, e-invoice can not be cancelled (in this case there is also no SOA/APA payment order in the bank); Only full cancellation of e-invoice is supported – in case a partial credit invoice is sent the original e-invoice will be cancelled. And a new correct e-invoice must be sent after the cancellation; 55 In Credit invoice tag attribute SellerRegnumber is mandatory; In case of Credit invoice availability of the e-invoice presentation channel (internet bank or others) of the addressee is not checked. Otherwise there can be situation where bank can not show einvoice and SOA/APA payment order cancellation result in response (VEA; FEI) file, as it can only contain 1 error/response code according to standard. . Recalling e-invoice and SOA/APA payment order means following actions: Paying of the cancelled e-invoice is disabled in internetbank and bank office; A notification is added to the cancelled e-invoice: „Invoice has been cancelled by Seller“; SOA/APA payment order created based on the cancelled e-invoice will also be cancelled, it is possible only if it has not yet been paid; No financial transactions are performed. E-Invoice Standing Order Agreement (EE) / E-Invoice Automated Payment Agreement (LV/LT) E-invoice Standing Order Agreement (SOA) in Estonia and E-Invoice Automated Payment Agreement (APA) in Latvia is a feature added to e-invoices that allows customer to instruct bank to pay incoming e-invoices on behalf of customer. SOA/APA can be concluded from: Predefined list, meaning that seller has an active Seller agreement in bank and has allowed submitting e-invoice single application in bank From e-invoice. In such case SellerContractId (E_Invoice/Invoice/sellerContractId) and/or sellerRegNumber (E_Invoice/Invoice/sellerRegnumber) are taken from einvoice and put into SOA/APA. o Swedbank uses SellerContractId and/or sellerRegNumber to search for Seller agreement from database. If match is found then it is checked if SOA/APA is allowed in favour of the Seller. If not, then SOA/APA will not be concluded. o If Seller agreement is not found, then Swedbank considers e-invoice as abstract invoice. SOA/APA concluding is allowed. 56 Service – Single E-Invoice application Service description Single einvoice application is customers request to receive e-invoices from pre-determined seller. Customer can submit single e-invoice application in branch and in Internetbank. Submitting single einvoice application must be allowed in Seller agreement. Seller can receive submitted single e-invoice applications through operator or directly using Swedbank Gateway. Applications are sent by bank once a day as a rule. If there is large number of applications, service message is split up into smaller messages. Current splitting parameter is set to 500 per file, this value can change in time. Example request XML There is no request – bank is generating these messages based on SGW agreement details. There are small country-based differences in the XML, so please use the correct XSD validator. Example response XML, EE <?xml version="1.0" encoding="UTF-8" ?> <ApplicationBank appId="EAA" date="2012-11-01" receiverId="SellerId" senderId="HABAEE2X" fileId="89" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="eaaApplicationBank.xsd"> <Application> <SellerRegNumber>123456789</SellerRegNumber> <SellerContractId>123456</SellerContractId> <Action>ADD</Action> <!-- Possible values ADD, DEL --> <ServiceId>2378463788</ServiceId> <ChannelId>HABAEE2X</ChannelId> <ChannelAddress>221002938946</ChannelAddress> <PresentmentType>FULL</PresentmentType> <!-- possible values FULL, PAY --> <CustomerIdCode>38004160294</CustomerIdCode> <CustomerName>MAALI MAASIKAS</CustomerName> <CustomerEmail>maali.maasikas@email.com</CustomerEmail> <CustomerPhone>6121212</CustomerPhone> <TimeStamp>2013-04-05T09:00:00</TimeStamp> </Application> </ApplicationBank> Example response XML, LV <?xml version="1.0" encoding="UTF-8" standalone="no" ?> <ApplicationBank xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EIA" date="2014-08-28" fileId="0828830960" xsi:noNamespaceSchemaLocation="eaaApplicationBankLV.xsd"> <Application> <SellerRegNumber>80808080</SellerRegNumber> <SellerContractId>254808</SellerContractId> <Action>ADD</Action> <ServiceId>13374</ServiceId> <AdditionalServiceId>1234</AdditionalServiceId> <ChannelId>HABALV22</ChannelId> <ChannelAddress>LV27HABA0551006170865</ChannelAddress> <PresentmentType>FULL</PresentmentType> <CustomerIdCode>80808080</CustomerIdCode> <CustomerName>NUTELLA CORPORATION</CustomerName> <UserCode>10581787</UserCode> <UserName>Leonīds Purviņa</UserName> <CancelPreviousInvoice>NO</CancelPreviousInvoice> <CustomerEmail>nut@nut.ee</CustomerEmail> <CustomerPhone>+37167444444</CustomerPhone> <TimeStamp>2014-08-28T12:25:52</TimeStamp> 57 </Application> </ApplicationBank> Example response XML, LT <?xml version="1.0" encoding="UTF-8"?> <ApplicationBank xsi:noNamespaceSchemaLocation="applicationBank.xsd" senderId="HABALT22" fileId="1213670762" date="2015-12-13" appId="EIA" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Application> <SellerRegNumber>123456789</SellerRegNumber> <GlobalSellerContractId>123456789HABALT22123456</GlobalSellerContractId> <Action>ADD</Action> <ServiceId>1234567891</ServiceId> <ChannelId>HABALT22</ChannelId> <ChannelAddress>LT27HABA2251006170865</ChannelAddress> <PresentmentType>FULL</PresentmentType> <CustomerIdCode>80808080</CustomerIdCode> <CustomerName>NUTELLA CORPORATION</CustomerName> <CustomerEmail>nut@nut.lt</CustomerEmail> <CustomerPhone>+37067444444</CustomerPhone> <TimeStamp>2015-12-10T15:54:04</TimeStamp> </Application> </ApplicationBank> Response XML file can be validated against XSD validator available at SGW development toolbox information site http://dev.hansagateway.net/info. Access to this site is IP-address based. Description of fields in response XML can be found in concrete country e-invoice technical descriptions. 58 Service – E-Invoice Standing Order (EE) / Automated Payment (LV, LT) agreement management Before using this service it is important to know the terms and conditions of E-invoice service. Separate E-invoice Seller agreement must be signed. Service description Updates in Seller’s information system regarding new E-Invoice SO/AP agreements and/or closed/changed existing E-Invoice SO/AP agreements can be synchronized with the Bank using this service in case bank has authorized Seller to conclude SOAs/APAs in the name of bank. This service differs from other SGW services because it requires two .xml documents in a signature container – similarly to E-invoice sending service. SGW requires that in case of several files in one signature container, request file name has to end with “–request.xml”. That file is processed as SGW request .xml and validated against hgw.xsd. IS must be ready to split a large E-invoice SOA/APA report file into several smaller files in case the original file size exceeds the current maximum incoming message file size set in the channel. In case of this service Seller must maintain the e-invoice standing order agreement database and keep it updated. Both Bank and Seller are obligated to forward information about new, changed or closed agreement within one hour after the change took place. In case there are no changes, no report is sent. Seller must send to the Bank only the changes made by Seller. Changes received by Seller via periodic report of E-Invoice SOA/APA changes sent by Bank should not be reported back to Bank. Preconditions for using the service: E-invoice agreement with mandate allowing Seller to conclude e-invoice standing order agreements in the name of Bank; E-invoice reports agreement, allowing exchange of SOA/APA reports via Swedbank Gateway. Relevant service must also be activated in SGW agreement Seller/Operator uses same fileformat for reporting SOA/APA changes to the Bank as Bank uses in service Periodic report of E-Invoice Standing Order/Automated Payment changes. File format can be validated by using XSD, available at SGW development toolbox information site http://dev.hansagateway.net/info. Access to this site is IP-address based. Example request XML (SOAreport-request.xml, EE) <?xml version="1.0" encoding="UTF-8"?> <StandingOrderAgreementIncoming> <Filename>SOAreport.xml</Filename> <CountryCode>EE</CountryCode> <ContractId>4022845</ContractId> </StandingOrderAgreementIncoming> Example request XML (APAreport-request.xml, LV) <?xml version="1.0" encoding="UTF-8"?> <StandingOrderAgreementIncoming> <Filename>APAreport.xml</Filename> <CountryCode>LV</CountryCode> <ContractId>4022845</ContractId> </StandingOrderAgreementIncoming> 59 Example request XML (APAreport-request.xml, LT) <?xml version="1.0" encoding="UTF-8"?> <StandingOrderAgreementIncoming> <Filename>APAreport.xml</Filename> <CountryCode>LT</CountryCode> <ContractId>123456789HABALT22123456</ContractId> </StandingOrderAgreementIncoming> Description of fields in request XML StandingOrderAgreementIncoming 1..1 Filename AN CountryCode A (2) ContractId AN Name of the SOA/APA report file in signature container. Country code – if customer has SGW agreement in only one country. EE/LV/LT otherwise. E-invoice seller agreement number. 1..1 0..1 1..1 Example request XML (SOAreport.xml, EE, ADD) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="SOAREP" date="2013-10-18" fileId="1118573518" receiverId="RECEIVER" senderId="HABAEE2X" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="" sequenceId="1"> <SellerRegNumber>11517605</SellerRegNumber> <SellerContractId>4022845</SellerContractId> <Action>ADD</Action> <ServiceId>1234567842</ServiceId> <PayerName>RAIKI RAMM</PayerName> <PayerRegNumber>35108238664</PayerRegNumber> <PayerIBAN>EE542200221055100802</PayerIBAN> <PartialDebiting>NO</PartialDebiting> <MonthLimit currency="EUR">100.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2013-09-28</StartDate> <EndDate/> <TimeStamp>2013-09-28T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> Example request XML (SOAreport.xml, EE, UPD) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="SOAREP" date="2013-10-18" fileId="1118573519" receiverId="RECEIVER" senderId="HABAEE2X" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="" sequenceId="2"> <SellerRegNumber>11517605</SellerRegNumber> <SellerContractId>4022845</SellerContractId> <Action>UPD</Action> <ServiceId>1234567842</ServiceId> <PayerName>RAIKI RAMM</PayerName> <PayerRegNumber>35108238664</PayerRegNumber> <PayerIBAN>EE542200221055100802</PayerIBAN> <PartialDebiting>YES</PartialDebiting> <MonthLimit currency="EUR">100.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2013-10-28</StartDate> 60 <EndDate/> <TimeStamp>2013-10-28T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> Example request XML (SOAreport.xml, EE, DEL) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="SOAREP" date="2013-12-18" fileId="1118573521" receiverId="RECEIVER" senderId="HABAEE2X" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="" sequenceId="3"> <SellerRegNumber>11517605</SellerRegNumber> <SellerContractId>4022845</SellerContractId> <Action>DEL</Action> <ServiceId>1234567842</ServiceId> <PayerName>RAIKI RAMM</PayerName> <PayerRegNumber>35108238664</PayerRegNumber> <PayerIBAN>EE542200221055100802</PayerIBAN> <PartialDebiting>YES</PartialDebiting> <MonthLimit currency="EUR">100.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2013-11-28</StartDate> <EndDate>2013-12-18</EndDate> <TimeStamp>2013-11-28T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> Example request XML (APAreport.xml, LV, ADD) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPREP" date="2014-08-03" fileId="0803106031" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="SOA" sequenceId="1"> <SellerRegNumber>80808080</SellerRegNumber> <SellerContractId>254808</SellerContractId> <Action>ADD</Action> <ServiceId>1234567891</ServiceId> <AdditionalServiceId>123</AdditionalServiceId> <PayerName>Ārija Lęšis</PayerName> <PayerRegNumber>12421736</PayerRegNumber> <PayerIBAN>LV38HABA0551000003213</PayerIBAN> <PartialDebiting>NO</PartialDebiting> <MonthLimit currency="EUR">100.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2014-08-27</StartDate> <EndDate /> <TimeStamp>2014-08-27T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> Example request XML (APAreport.xml, LV, UPD) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPREP" date="2014-09-03" fileId="0903106031" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="SOA" sequenceId="2"> <SellerRegNumber>80808080</SellerRegNumber> <SellerContractId>254808</SellerContractId> <Action>UPD</Action> 61 <ServiceId>1234567891</ServiceId> <AdditionalServiceId>123</AdditionalServiceId> <PayerName>Ārija Lęšis</PayerName> <PayerRegNumber>12421736</PayerRegNumber> <PayerIBAN>LV38HABA0551000003213</PayerIBAN> <PartialDebiting>NO</PartialDebiting> <MonthLimit currency="EUR">150.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2014-09-27</StartDate> <EndDate /> <TimeStamp>2014-09-27T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> Example request XML (APAreport.xml, LV, DEL) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPREP" date="2014-10-03" fileId="1003106031" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="SOA" sequenceId="3"> <SellerRegNumber>80808080</SellerRegNumber> <SellerContractId>254808</SellerContractId> <Action>DEL</Action> <ServiceId>1234567891</ServiceId> <AdditionalServiceId>123</AdditionalServiceId> <PayerName>Ārija Lęšis</PayerName> <PayerRegNumber>12421736</PayerRegNumber> <PayerIBAN>LV38HABA0551000003213</PayerIBAN> <PartialDebiting>NO</PartialDebiting> <MonthLimit currency="EUR">150.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2014-11-27</StartDate> <EndDate>2014-11-27</EndDate> <TimeStamp>2014-11-27T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> Example request XML (APAreport.xml, LT, ADD) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPREP" date="2014-08-03" fileId="0803106031" receiverId="RECEIVER" senderId="HABALT22" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="SOA" sequenceId="1"> <SellerRegNumber>80808080</SellerRegNumber> <GlobalSellerContractId>80808080HABALT22254808</GlobalSellerContractId> <Action>ADD</Action> <ServiceId>1234567891</ServiceId> <PayerName>Ārija Lęšis</PayerName> <PayerRegNumber>12421736</PayerRegNumber> <PayerIBAN>LT38HABA0551000003213</PayerIBAN> <PartialDebiting>NO</PartialDebiting> <MonthLimit currency="EUR">100.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2014-08-27</StartDate> <EndDate /> <TimeStamp>2014-08-27T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> 62 Example request XML (APAreport.xml, LT, UPD) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPREP" date="2014-09-03" fileId="0903106031" receiverId="RECEIVER" senderId="HABALT22" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="SOA" sequenceId="2"> <SellerRegNumber>80808080</SellerRegNumber> <GlobalSellerContractId>80808080HABALT22254808</GlobalSellerContractId> <Action>UPD</Action> <ServiceId>1234567891</ServiceId> <PayerName>Ārija Lęšis</PayerName> <PayerRegNumber>12421736</PayerRegNumber> <PayerIBAN>LT38HABA0551000003213</PayerIBAN> <PartialDebiting>NO</PartialDebiting> <MonthLimit currency="EUR">150.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2014-09-27</StartDate> <EndDate /> <TimeStamp>2014-09-27T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> Example request XML (APAreport.xml, LT, DEL) <?xml version="1.0" encoding="UTF-8"?> <EInvoiceStandingOrderAgreementReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPREP" date="2014-10-03" fileId="1003106031" receiverId="RECEIVER" senderId="HABALT22" xsi:noNamespaceSchemaLocation="eInvoiceStandingOrderAgreementReport.xsd"> <Agreement name="SOA" sequenceId="3"> <SellerRegNumber>80808080</SellerRegNumber> <GlobalSellerContractId>80808080HABALT22254808</GlobalSellerContractId> <Action>DEL</Action> <ServiceId>1234567891</ServiceId> <PayerName>Ārija Lęšis</PayerName> <PayerRegNumber>12421736</PayerRegNumber> <PayerIBAN>LT38HABA0551000003213</PayerIBAN> <PartialDebiting>NO</PartialDebiting> <MonthLimit currency="EUR">150.00</MonthLimit> <DaysLookForFunds>3</DaysLookForFunds> <PaymentDay>InvoiceDueDate</PaymentDay> <StartDate>2014-11-27</StartDate> <EndDate>2014-11-27</EndDate> <TimeStamp>2014-11-27T08:38:55</TimeStamp> </Agreement> </EInvoiceStandingOrderAgreementReport> Description of fields in request XML EinvoiceStandingOrderAgreementReport @ senderId 1..1 AN(20) Sender Id 1..1 @ receiverId AN(20) Receiver Id 1..1 @ date D Request message date 1..1 @ fileId AN(20) Original file Id 1..1 @ appId A(6) Enumeration value=”SOAREP” in Estonia 1..1 63 Enumeration value=”EAPREP” in Latvia Agreement 1..* Agreement@name AN(40) Agreement identifier 1..1 Agreement@sequenceId N Positive integer. Sequence id 1..1 Agreement / SellerRegNumber AN(15) 1..1 Agreement / SellerContractId Seller’s registry/personal identification code AN(100) Seller’s contract ID in Estonia and Latvia Agreement / GlobalSellerContractId AN(100) Seller’s contract ID in Lithuania 1..1 Agreement /Action AN(3) 1..1 Agreement /ServiceId EE, LV: AN(20) LT: AN(35) AN(20) Agreement /AdditionalServiceId Possible values for action are ADD, DEL and UPD Value of the serviceId attribute from the Invoice element of the e-invoice sent to the bank 1..1 1..1 0..1 Agreement /PayerName Value of the additional serviceId attribute from the Invoice element of the e-invoice sent to the bank. Used only in Latvia AN(100) Payer name Agreement / PayerRegNumber AN(15) 1..1 Agreement / PayerIBAN AN(35) Payer’s registry/personal identification code Payer’s IBAN Agreement / PartialDebiting AN(3) 1..1 Agreement / MonthLimit N YES/NO, indicating if partial debiting is allowed. Monthly limit. Max 2 decimal positions Agreement /MonthLimit@Currency A (3) Currency for monthly limit 1..1 Agreement / DayLimit N Daily limit. Max 2 decimal positions 0..1 Agreement / DayLimit @Currency A (3) Currency for daily limit 1..1 Agreement / PaymentLimit N Payment limit. Max 2 decimal positions 0..1 Agreement / PaymentLimit @Currency Agreement /DaysLookForFunds A (3) Currency for payment limit 1..1 N 1..1 Agreement / PaymentDay AN Agreement / StartDate D Days after Payment day that funds are still looked for in case no available balance Date of month when payment is carried out. ReceivedDay+2 - E-invoice will be paid 2 days after receipt InvoiceDueDate - Einvoice will be paid on date set in PaymentInfo/PayDueDate element Day (1 - 31) - E-Invoice will be paid on that day of month. Day presumes debiting period being set in seller agreement and being within that period. Startdate of update information period Agreement / EndDate D 1..1 Agreement / TimeStamp DT Enddate of update information period, allowed to be empty, except for DEL Date and time of the request, format: yyyymm-ddThh:mm:ss 0..1 1..1 1..1 1..1 1..1 1..1 64 Possible action types are ADD, DEL and UPD. In case e-invoice standing order agreement has several changes since last update report, only last change is added to the message. If a new agreement is concluded by Seller and after it a change is added to it, report will include the agreement with latest changes and with action type ADD; If several consecutive changes are made to an existing agreement, report will include the agreement with latest changes and with action type UPD; If a change is made to an existing agreement and after it the agreement is closed, report will include the agreement with action type DEL; If a new agreement is concluded by Seller and after it the agreement is closed, report will not include this agreement. Timestamp added to the report stands for the time of e-invoice SOA/APA adding, changing or closing. Agreements will be processed in the order of timestamp in ascending order meaning ADD, DEL and UPD actions are processed in the order they were carried out by Seller/Operator. In case of DEL action Bank first adds all the changes and then closes the agreement.This will assure that both parties have same data about the closed agreement. Possible values for PaymentDay: InvoiceDueDate: standing order/automated payment will be carried out on due date marked on invoice InvoiceDueDate-2: standing order/automated payment will be carried out 2 days before the due date marked on invoice ReceivedDay+2: standing order/automated payment will be carried out 2 days after the invoice arrival Number (ie 21): standing order/automated payment will be carried on specified date (allowed values 1 -31). In case value is set to 31, and the current month has less days, standing order will be carried on the last day of the month (used only in Estonia) Changed e-invoice standing order/automated payment agreement is uniquely identified by following parameters: SellerContractId SellerRegNumber ServiceId Bank will always respond to a report received from Seller. In case request file was valid and all agreements are valid, response will be as follows: Example response XML (success, EE) <?xml version="1.0" encoding="UTF-8"?> <EinvoiceStandingOrderAgreementResponse> <Header appId="SOARESP" date="2013-07-30" fileId="0620189613" inFileId="0620189613" receiverId="TESTER1" senderId="TESTER2"/> <Footer totalNr="0"/> </EinvoiceStandingOrderAgreementResponse> 65 Example response XML (success, LV) <?xml version="1.0" encoding="UTF-8"?> <EinvoiceStandingOrderAgreementResponse> <Header appId="EAPRESP" date="2014-10-01" fileId="1001836422" fileId="18914215" /> <Footer totalNr="0" /> </EinvoiceStandingOrderAgreementResponse> in- Example response XML (success, LT) <?xml version="1.0" encoding="UTF-8"?> <EinvoiceStandingOrderAgreementResponse> <Header appId="EAPRESP" date="2014-10-01" fileId="1001836422" receiverId="TESTER1" senderId="TESTER2" infileId="18914215" /> <Footer totalNr="0" /> </EinvoiceStandingOrderAgreementResponse> In case request file is invalid, following response is sent: Example response XML (invalid file, EE) <?xml version="1.0" encoding="UTF-8"?> <EinvoiceStandingOrderAgreementResponse> <Header appId="SOARESP" date="2013-07-30" receiverId="TESTER1" senderId="HABAEE2X" fileFailReason="1"/> <Footer totalNr="0"/> </EinvoiceStandingOrderAgreementResponse> Example response XML (invalid file, LV) <?xml version="1.0" encoding="UTF-8" ?> <EinvoiceStandingOrderAgreementResponse> <Header appId="EAPRESP" date="2014-09-26" receiverId="TESTER1" senderId="HABALV22" fileFailReason="3" /> <Footer totalNr="0" /> </EinvoiceStandingOrderAgreementResponse> Example response XML (invalid file, LT) <?xml version="1.0" encoding="UTF-8" ?> <EinvoiceStandingOrderAgreementResponse> <Header appId="EAPRESP" date="2014-09-26" receiverId="TESTER1" senderId="HABALT22" fileFailReason="3" /> <Footer totalNr="0" /> </EinvoiceStandingOrderAgreementResponse> In case request file is valid, but some agreements in the request are not correct, following response is sent: Example response XML (agreement based errors, EE) <?xml version="1.0" encoding="UTF-8"?> <EinvoiceStandingOrderAgreementResponse xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xsi:noNamespaceSchemaLocation="einvoiceStandingOrderAgreementResponse.xsd"> <Header appId="SOARESP" date="2012-11-01" receiverId="RECEIVER" senderId="HABAEE2X" fileId="1" infileId="11"/> <Agreement sequenceId="123"> <SellerContractId>88888888</SellerContractId> <SellerRegNumber>88888888</SellerRegNumber> <ServiceId>324324242</ServiceId> <FailureCode>35</FailureCode> 66 </Agreement> <Footer totalNr="1"/> </EinvoiceStandingOrderAgreementResponse> Example response XML (agreement based errors, LV) <?xml version="1.0" encoding="UTF-8" ?> <EinvoiceStandingOrderAgreementResponse> <Header appId="EAPRESP" date="2014-10-01" fileId="1001446072" infileId="18914206" /> <Agreement sequenceId="1"> <SellerContractId>3</SellerContractId> <SellerRegNumber>40003052786</SellerRegNumber> <ServiceId>13377</ServiceId> <AdditionalServiceId>123456123</AdditionalServiceId> <FailureCode>4</FailureCode> </Agreement> <Footer totalNr="1" /> </EinvoiceStandingOrderAgreementResponse> Example response XML (agreement based errors, LT) <?xml version="1.0" encoding="UTF-8" ?> <EinvoiceStandingOrderAgreementResponse> <Header appId="EAPRESP" date="2014-10-01" receiverId="TESTER1" senderId="HABALT22" fileId="1001446072" infileId="18914206" /> <Agreement sequenceId="1"> <GlobalSellerContractId>80808080HABALT22254808</GlobalSellerContractId> <SellerRegNumber>80808080</SellerRegNumber> <ServiceId>13377</ServiceId> <FailureCode>4</FailureCode> </Agreement> <Footer totalNr="1" /> </EinvoiceStandingOrderAgreementResponse> In case of conflict in data, e-invoice SOA/APA information in Bank has superiority over e-invoice SOA/APA information at Seller. For instance, conflict can occur in situation where client signs an einvoice SO/AP agreement in Bank, but a week later makes a change to the agreement by the Seller. If Seller informs about this change with a wrong action type (ADD instead of UPD), Bank will respond with errorcode 7 – Duplicate. Description of fields in response XML EinvoiceStandingOrderAgreementResponse Header 1..1 Container element inside EinvoiceStandingOrderAgreementResponse Enumeration value=” SOARESP” in Estonia Enumeration value=” EAPRESP” in Latvia 1..1 Header @ appId A(7) 1..1 Header @ date D Response message date 1..1 Header @ receiverId AN(20) Receiver Id 1..1 Header @ senderId AN(20) Sender (bank) Id 1..1 Header @ fileId AN(20) Original file Id 0..1 67 Header @ infileId AN(20) Original e-invoice file Id 0..1 Header @ fileFailReason N 0..1 Agreement @sequenceId N See SOA/APA management service error codes Container element inside EinvoiceStandingOrderAgreementResponse for each defective e-invoice Positive integer Agreement /SellerContractId AN(100) Seller’s contract ID in Estonia and Latvia 1..1 Agreement /GlobalSellerContractId AN(100) Seller’s contract ID in Lithuania only 1..1 Agreement /SellerRegNumber AN(15) 1..1 Agreement /ServiceId Agreement /AdditionalServiceId EE, LV: AN(20) LT: AN(35) AN(20) Seller’s registry/personal identification code Value of the serviceId attribute from the Invoice element of the e-invoice sent to the bank Agreement /FailureCode N Agreement /Comment AN(100) Agreement Footer Footer@ totalNr N 0..* 1..1 1..1 Value of the additional serviceId attrib- 0..1 ute from the Invoice element of the einvoice sent to the bank Positive integer. SOA/APA management 1..1 service error code Comment 0..1 Container element inside EinvoiceStandingOrderAgreementResponse Positive integer . Total number of failed SOA/APA updates 1..1 1..1 SOA/APA management service error codes Errorcode Description File-based errors 1 Invalid xml (XSD validation failed) 3 File is a duplicate (combination of senderId, fileId and appId has already been used) Agreement based checks: 2 4 Sender does not have active Seller agreement or e-invoice SOA/APA reports are not allowed. Seller has not allowed SOA/APA management in Seller agreement 7 Duplicate 8 Changed agreement does not exist 9 Account number invalid 10 Payment day is not within debiting period 11 Start date is in the past 12 End date is earlier than start date 13 Monthly limit missing or invalid 68 Service – Periodic report of E-Invoice Standing Order (EE)/ Automated Payment (LV, LT) changes Before using this service it is important to know the terms and conditions of E-invoice service. Separate E-invoice Seller agreement must be signed. Service description This periodic report is used to notify the Seller/Operator about changed/added/deleted e-invoice standing order agreements (SOA/APA) concluded in favour of the seller. Changes are sent several times a day, in case new information has occurred since last report. The frequency may change in time. First report will include all existing active and on hold e-invoice standing order/automated payment agreements that are connected to the corresponding e-invoice service agreement. Next reports will include only changes to e-invoice standing order/automated payment agreements. This means that Seller should use the first report to store all necessary data to database, and based on following reports apply changes to that database. Report will be sent to Seller or Operator, based on the agreement. The operator chosen to receive the report may be different from the Operator collecting the einvoice applications. The recipient of Periodic report of E-Invoice Standing Order changes has to be the same as the recipient of E-Invoice Standing Order/Automated Payment agreement payment report. In case e-invoice standing order/automated payment agreement has several changes since last update report, only last change is added to the message. Timestamp added to the report stands for the time of e-invoice SOA/APA adding, changing or closing. Agreements will be processed in the order of timestamp in ascending order meaning ADD, DEL and UPD actions are processed by Seller/Operator in the order they were carried out by Bank. Changed e-invoice standing order/automated payment agreement is uniquely identified by following parameters: SellerContractId (EE, LV) / GlobalSellerContractId (LT) SellerRegNumber ServiceId Seller should not send a response to the Periodic report of E-Invoice SOA/APA changes received from the Bank. File format of the SOA/APA report can be validated by using XSD, available at SGW development toolbox information site http://dev.hansagateway.net/info. Access to this site is IP-address based. Example request XML There is none – bank is generating these messages based on SGW agreement details. Example response XML This is reverse of previous E-Invoice Standing Order/automated payment agreement management service. In Estonia and Latvia the report sent by bank has the same structure as Seller’s request in that service. In Lithuanian version PayerRegNumber is excluded from the request XML. The bank does not expect any response to these messages and responds with XML validation error if one is sent. 69 Service – E-Invoice Standing Order (EE) / Automated Payment (LV, LT) agreement payment report Before using this service it is important to know the terms and conditions of E-invoice service. Separate E-invoice Seller agreement and SOA/APA reports agreement must be signed. Service description Swedbank allows seller to receive report about payments initiated by SOA/APAs in given period. Reports are sent several times a day, in case new information has occurred since last report. The frequency may change in time. Report does not contain information about payments manually initiated by client from E-invoice, only payments automatically initiated by E-invoice Standing Order / Automated Payment Agreement are included. Example request XML There is no request – bank is generating these messages based on SGW agreement details. Example response XML, EE <?xml version="1.0" encoding="UTF-8"?> <EInvoiceSOAPaymentReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="SOAPMT" date="2013-11-18" receiverId="TESTER1" senderId="HABAEE2X" xsi:noNamespaceSchemaLocation="eInvoiceSOAPaymentReport.xsd"> <EinvoiceStandingOrder> <SellerRegNumber>11517605</SellerRegNumber> <SellerContractId>4022845</SellerContractId> <ServiceId>1234567842</ServiceId> <EInvoice number="40669498"> <GlobUniqueId>40669498</GlobUniqueId> <Amount>7.09</Amount> </EInvoice> <Payment> <ValueDate>2013-11-16</ValueDate> <Amount>7.09</Amount> <ReferenceNumber>12344</ReferenceNumber> <Description>Einvioce 40669498 paid</Description> <ArchiveNumber>2013111600243859</ArchiveNumber> <Status>Successful</Status> </Payment> </EinvoiceStandingOrder> </EInvoiceSOAPaymentReport> Example response XML, LV <?xml version="1.0" encoding="UTF-8" ?> <EInvoiceSOAPaymentReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPPMT" date="2014-10-01" xsi:noNamespaceSchemaLocation="eInvoiceSOAPaymentReportLV.xsd"> <EinvoiceStandingOrder> <SellerRegNumber>40003052786</SellerRegNumber> <SellerContractId>3</SellerContractId> <ServiceId>40003020441</ServiceId> <EInvoice number="456788"> <GlobUniqueId>123</GlobUniqueId> <Amount>1.12</Amount> 70 </EInvoice> <Payment> <ValueDate>2014-10-01</ValueDate> <Amount>1.12</Amount> <ReferenceNumber>1234</ReferenceNumber> <ArchiveNumber>2014100100129866</ArchiveNumber> <Status>Successful</Status> </Payment> </EinvoiceStandingOrder> </EInvoiceSOAPaymentReport> Example response XML, LT <?xml version="1.0" encoding="UTF-8" ?> <EInvoiceSOAPaymentReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPPMT" date="2014-10-01" xsi:noNamespaceSchemaLocation="eInvoiceSOAPaymentReportLV.xsd"> <EinvoiceStandingOrder> <SellerRegNumber>80808080</SellerRegNumber> <GlobalSellerContractId>80808080HABALT22254808</GlobalSellerContractId> <ServiceId>40003020441</ServiceId> <EInvoice number="456788"> <GlobUniqueId>123</GlobUniqueId> <Amount>1.12</Amount> </EInvoice> <Payment> <ValueDate>2014-10-01</ValueDate> <Amount>1.12</Amount> <ReferenceNumber>1234</ReferenceNumber> <ArchiveNumber>2014100100129866</ArchiveNumber> <Status>Successful</Status> </Payment> </EinvoiceStandingOrder> </EInvoiceSOAPaymentReport> Description of fields in response XML EInvoiceSOAPaymentReport 1..1 EInvoiceSOAPaymentReport@appId A(9) 1..1 D Enumeration value=” SOAPMT” in Estonia Enumeration value=” EAPPMT” in Latvia Response message date EInvoiceSOAPaymentReport@date EInvoiceSOAPaymentReport@receiverId AN(20) Receiver Id 1..1 EInvoiceSOAPaymentReport@senderId AN(20) SenderId 1..1 EInvoiceSOAPaymentReport@periodStartDate EInvoiceSOAPaymentReport@ periodEndDate EinvoiceStandingOrder D Period startdate 0..1 D Period enddate 0..1 EinvoiceStandingOrder/ SellerRegNumber AN(15) EinvoiceStandingOrder/ SellerContractId EinvoiceStandingOrder/ GlobalSellerContractId EinvoiceStandingOrder/ServiceId AN(100) 1..1 1..n 1..1 AN(100) Seller’s registry/personal identification code Seller’s contract ID in Estonia and Latvia Seller’s contract ID in Lithuania EE, LV: AN(15) Value of the serviceId attribute from the Invoice element of the e- 1..1 1..1 1..1 71 LT: AN(35) EinvoiceStandingOrder/EInvoice EInvoice@number AN(100) EInvoice / EInvoiceGlobUniqueId AN(100) EInvoice /Amount N EinvoiceStandingOrder/Payment Payment/ValueDate D Payment/Amount N Payment/Description AN(140) invoice sent to the bank Container element inside EinvoiceStandingOrder for e-invoice Value of the invoiceId attribute in the Invoice element of the einvoice sent to the bank Value of the GlobUniqId attribute from the Invoice element of the einvoice sent to the bank E-invoice amount, max 2 decimal positions Container element inside EinvoiceStandingOrder for Payment Payment valuedate 1..1 Payment amount. Max 2 decimal positions Payment description 0..1 1..1 1..1 1..1 1..1 0..1 1..1 OR Payment/ReferenceNumber AN(35) 1..1 AN(140) Payment reference number. Until 02.2014 only 7-3-1 reference number method http://www.pangaliit.ee/en/settle ments-and-standards/referencenumber-of-the-invoice is supported. Starting from 02.2014 also ISO11649 reference number is supported. Payment description Payment/Description Payment/ArchiveNumber AN(16) Payment archiving number in Bank 0..1 Payment/Status AN(20) Look at Status codes below 1..1 0..1 E-invoice Standing Order/Automated Payment Payment status codes Possible payment status codes are: Successful – Paid in full PartDeb – Partially paid OverLimit – Payment failed – over limit InvPmtInfo – Payment failed – faulty payment order info Failed – Payment failed – other reason CancCust – Payment failed – cancelled by payer CancAgrTerm – Payment failed – cancelled by closure of SOA agreement CancSeller – Payment failed – cancelled by Seller Seller/Operator should not send a response to the E-Invoice SOA/APA payment report received from the Bank. 72 Service – E-Invoices for customer Service description Customer can choose SGW as a channel to receive the company’s purchase invoices as e-invoices. SGW is periodically checking for unread e-invoices and sends their content .xml (without applying supplier’s style sheets) encrypted with client’s ERP public key. Forwarded e-invoices are also marked as “downloaded” so they will not show as “unread” in other electronic channels (like Internet bank). Example request XML There is none – bank is generating these messages based on SGW agreement details. Example response XML This depends on e-invoice processing. 73 Service – POS report delivery Service description This service is used as delivery channel for POS reports from the bank to the client. Example request XML There is no request – bank is generating these messages based on POS agreement and SGW agreement details. Example response XML Response XML is not generated by SGW, thus there is only 2 report types given as samples. Please refer to POS report generator documentation about details and XSD (example Estonian details page: https://www.swedbank.ee/business/cash/cashflow/posReport). XSD (MerchReportNo1_2.1.xsd) is also available at SGW development toolbox information site http://dev.hansagateway.net/info. Access to this site is IP-address based. Example 1: Transaction based report <?xml version="1.0" encoding="UTF-8" ?> - <posreport version="2.1" rep_date="2012-05-02" per_start="2012-04-17" per_end="2012-04-18"> - <company> <id>93201456</id> <name>Luuk OÜ</name> <contact_address>LIIVALAIA 10</contact_address> <contact_city>Tallinn</contact_city> <contact_zip>15040</contact_zip> <contact_country>EE</contact_country> - <outlet> <id>9297565</id> <name>Luuk-LibakaupmeesI</name> <address>LIIVALAIA 8</address> <city>Tallinn</city> <zip>15040</zip> <account_no>221014217590</account_no> <country>ESTONIA</country> - <terminal> <id>11060344515</id> - <batch> <batch_no>041624</batch_no> <batch_start>2012-04-16</batch_start> <batch_close>2012-04-16</batch_close> <value_date>2012-04-16</value_date> <proc_date>2012-04-17</proc_date> - <card_group> <organization>MasterCard</organization> <type>Credit</type> <region>EU</region> - <transaction> <trans_type>Term</trans_type> <hidden_pan>2764</hidden_pan> <stan>000060</stan> <local_date>2012-04-13</local_date> <local_time>11:40:20</local_time> <ret_ref_nr>210854993993</ret_ref_nr> <auth_code /> <orig_currency>EUR</orig_currency> <orig_amount>3.95</orig_amount> <paym_currency>EUR</paym_currency> 74 <paym_amount>3.95</paym_amount> <fee_amount>0.05</fee_amount> <net_amount>3.90</net_amount> </transaction> - <transaction> <trans_type>Term</trans_type> <hidden_pan>3404</hidden_pan> <stan>000062</stan> <local_date>2012-04-13</local_date> <local_time>14:32:05</local_time> <ret_ref_nr>210854993994</ret_ref_nr> <auth_code>414364</auth_code> <orig_currency>EUR</orig_currency> <orig_amount>4.75</orig_amount> <paym_currency>EUR</paym_currency> <paym_amount>4.75</paym_amount> <fee_amount>0.05</fee_amount> <net_amount>4.70</net_amount> </transaction> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>2</count> <trans_currency>EUR</trans_currency> <gross_amount>8.70</gross_amount> </trans_curr_summary> <count>2</count> <paym_currency>EUR</paym_currency> <gross_amount>8.70</gross_amount> <fee_amount>0.10</fee_amount> <net_amount>8.60</net_amount> </total> </card_group> - <card_group> <organization /> <type>Debit</type> <region>Swedbank</region> + <transaction> + <transaction> + <transaction> + <transaction> + <total> </card_group> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>6</count> <trans_currency>EUR</trans_currency> <gross_amount>23.43</gross_amount> </trans_curr_summary> <count>6</count> <paym_currency>EUR</paym_currency> <gross_amount>23.43</gross_amount> <fee_amount>0.25</fee_amount> <net_amount>23.18</net_amount> </total> </batch> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>6</count> <trans_currency>EUR</trans_currency> <gross_amount>23.43</gross_amount> </trans_curr_summary> <count>6</count> <paym_currency>EUR</paym_currency> <gross_amount>23.43</gross_amount> <fee_amount>0.25</fee_amount> 75 <net_amount>23.18</net_amount> </total> </terminal> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>6</count> <trans_currency>EUR</trans_currency> <gross_amount>23.43</gross_amount> </trans_curr_summary> <count>6</count> <paym_currency>EUR</paym_currency> <gross_amount>23.43</gross_amount> <fee_amount>0.25</fee_amount> <net_amount>23.18</net_amount> </total> </outlet> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>6</count> <trans_currency>EUR</trans_currency> <gross_amount>23.43</gross_amount> </trans_curr_summary> <count>6</count> <paym_currency>EUR</paym_currency> <gross_amount>23.43</gross_amount> <fee_amount>0.25</fee_amount> <net_amount>23.18</net_amount> </total> </company> </posreport> Example 2: Batch based report <?xml version="1.0" encoding="UTF-8" ?> - <posreport version="2.1" rep_date="2012-05-02" per_start="2012-04-01" per_end="2012-05-01"> - <company> <id>93201456</id> <name>Luuk OÜ</name> <contact_address>LIIVALAIA 10</contact_address> <contact_city>Tallinn</contact_city> <contact_zip>15040</contact_zip> <contact_country>EE</contact_country> - <outlet> <id>9297565</id> <name>Luuk-Libakaupmees</name> <address>LIIVALAIA 8</address> <city>Tallinn</city> <zip>15040</zip> <account_no>221014217590</account_no> <country>ESTONIA</country> - <terminal> <id>11060344515</id> - <batch> <batch_no>040209</batch_no> <batch_start>2012-04-02</batch_start> <batch_close>2012-04-02</batch_close> <value_date>2012-04-02</value_date> <proc_date>2012-04-03</proc_date> - <card_group> <organization>VISA</organization> <type>Debit</type> <region>EU</region> - <total> 76 <trans_type>Term</trans_type> - <trans_curr_summary> <count>1</count> <trans_currency>EUR</trans_currency> <gross_amount>1.00</gross_amount> </trans_curr_summary> <count>1</count> <paym_currency>EUR</paym_currency> <gross_amount>1.00</gross_amount> <fee_amount>0.01</fee_amount> <net_amount>0.99</net_amount> </total> </card_group> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>1</count> <trans_currency>EUR</trans_currency> <gross_amount>1.00</gross_amount> </trans_curr_summary> <count>1</count> <paym_currency>EUR</paym_currency> <gross_amount>1.00</gross_amount> <fee_amount>0.01</fee_amount> <net_amount>0.99</net_amount> </total> </batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> + <batch> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>83</count> <trans_currency>EUR</trans_currency> <gross_amount>328.05</gross_amount> </trans_curr_summary> <count>83</count> <paym_currency>EUR</paym_currency> <gross_amount>328.05</gross_amount> <fee_amount>3.46</fee_amount> <net_amount>324.59</net_amount> </total> </terminal> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>83</count> <trans_currency>EUR</trans_currency> <gross_amount>328.05</gross_amount> </trans_curr_summary> <count>83</count> <paym_currency>EUR</paym_currency> <gross_amount>328.05</gross_amount> <fee_amount>3.46</fee_amount> <net_amount>324.59</net_amount> </total> 77 </outlet> - <total> <trans_type>Term</trans_type> - <trans_curr_summary> <count>83</count> <trans_currency>EUR</trans_currency> <gross_amount>328.05</gross_amount> </trans_curr_summary> <count>83</count> <paym_currency>EUR</paym_currency> <gross_amount>328.05</gross_amount> <fee_amount>3.46</fee_amount> <net_amount>324.59</net_amount> </total> </company> </posreport> 78
