Swedbank Gateway Service Description 7.0

Transcription

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
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
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
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 – Currency exchange .......................................................................................................................... 40
Service – Alert on transactions ....................................................................................................................... 42
Example response XML camt.054.001.02 ........................................................................................................ 42
Service – Periodic statement .......................................................................................................................... 43
Service – Sending e-invoices ........................................................................................................................... 44
Example request XML (einvoice-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
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
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
Example request XML (SOAreport-request.xml, EE) ........................................................................................ 59
Example request XML (APAreport-request.xml, LV) ........................................................................................ 59
Example request XML (APAreport-request.xml, LT)......................................................................................... 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
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
SOA/APA management service error codes ..................................................................................................... 68
Service – Periodic report of E-Invoice Standing Order (EE)/ Automated Payment (LV, LT) changes ............... 69
Service – E-Invoice Standing Order (EE) / Automated Payment (LV, LT) agreement payment report .............. 70
Example response XML, EE ............................................................................................................................... 70
Example response XML, LV............................................................................................................................... 70
Example response XML, LT ............................................................................................................................... 71
E-invoice Standing Order/Automated Payment Payment status codes ........................................................... 72
Service – E-Invoices for customer ................................................................................................................... 73
Service – POS report delivery ......................................................................................................................... 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:
BeneficiaryAddress (length 70+optional)
Details (length 140)
Cost (comment)
BalanceOfPaymentsCountry (comment)
Changed LV domestic payment fields:
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
The response message is delivered as the response body.
 Body – cdoc file
 Header CorrelationID – CorrelationID set by Client with PUT request.
 Header TrackingID – Bank side message ID.
service
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.
service
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
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
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
• 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
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
• 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
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
ERR00112
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
InvalidChargeBearerCode
Charge bearer code for transaction type is invalid
MissingCreditorName
Creditor name is 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
<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
<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
<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 &
< replaced with <
" replaced with "
> replaced with >
' replaced with '
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
<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>
</PmtId>
<Amt>
</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>
</PmtId>
<Amt>
</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.
30
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03">
<CstmrPmtStsRpt>
<GrpHdr>
<MsgId>20150317-153148975-3445-1750/3569</MsgId>
<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>
</Amt>
<Dbtr>
</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>
<TxSts>ACSP</TxSts>
<OrgnlTxRef>
<Amt>
</Amt>
31
<Dbtr>
</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>
<TxSts>RJCT</TxSts>
<StsRsnInf>
<Rsn>
<Cd>NARR</Cd>
</Rsn>
<AddtlInf>AccountNotFound</AddtlInf>
</StsRsnInf>
<OrgnlTxRef>
<Amt>
</Amt>
<Dbtr>
</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
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.060.001.03"
<AcctRptgReq>
<GrpHdr>
<MsgId>112324345136</MsgId>
</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
<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>
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..*
<ExchangeRateResponse>
<BIC>HABAEE2X</BIC>
<ExchangeRateType>Transfer</ExchangeRateType>
<ExchangeRateInfo BaseCurrency="EEK">
<CurrencyInfo Date="2007-06-30">
<Buy>15.62000</Buy>
38
<Sell>15.67350</Sell>
</CurrencyInfo>
<Buy>15.62000</Buy>
<Sell>15.67350</Sell>
</CurrencyInfo>
<Buy>1.96000</Buy>
<Sell>1.99200</Sell>
</CurrencyInfo>
<Buy>1.96000</Buy>
<Sell>1.99200</Sell>
</CurrencyInfo>
<Buy>12.25400</Buy>
<Sell>12.48850</Sell>
</CurrencyInfo>
<Buy>12.25400</Buy>
<Sell>12.48850</Sell>
</CurrencyInfo>
</ExchangeRateInfo>
</ExchangeRateResponse>
</B4B>
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
<CurrencyExchangeRequest>
<BIC>HABAEE2X</BIC>
<IBAN>EE922200221010214144</IBAN>
<Buy>
<Amount>2500</Amount>
<Rate>11.50811</Rate>
</Buy>
<Sell>
<Rate>15.638</Rate>
</Sell>
</CurrencyExchangeRequest>
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
<CurrencyExchangeResponse>
<BIC>HABAEE2X</BIC>
<IBAN>EE562200221008103199</IBAN>
<BankReference>2007070200000195</BankReference>
<Buy>
<Amount>2500.00</Amount>
<Rate>12.48850</Rate>
</Buy>
<Sell>
<Rate>15.62000</Rate>
</Sell>
</CurrencyExchangeResponse>
</B4B>
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
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)
<EinvoiceIncoming>
<Filename>einvoices.xml</Filename>
<CountryCode>EE</CountryCode>
<ContractId>12345</ContractId>
</EinvoiceIncoming>
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.
<Header appId="VEA" date="2013-05-09" receiverId="SellerId" senderId="HABAEE2X"
fileId="002" infileId="001" fileFailReason="51" />
</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.
<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>
</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)
<Header appId="FEI" date="2014-10-09" fileId="1001573956" infileId="headerLV11"
receiverId="" senderId="HABALV22" />
</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.
<Header appId="FEI" date="2014-09-10" fileFailReason="51" infileId=""
</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.
<FailedInvoice xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
<Header appId="FEI" date="2014-10-01" fileId="1001551112" infileId="headerLV-112481174"
<Invoice>
<ChannelId>HABALV22</ChannelId>
<InvoiceId>456790</InvoiceId>
<InvoiceGlobUniqId>1234</InvoiceGlobUniqId>
</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
<FailedInvoice>
<Header appId="FEI" date="2015-10-16" senderId="HABALT22" fileId="1016888841"/>
</FailedInvoice>
If file was incorrect (missing xsd, unparseable xml) then filebased errorcode is returned in header
attribute fileFailReason.
<FailedInvoice>
<Header appId="FEI" date="2015-10-16" senderId="HABALT22" fileId="1016888841" fileFailReason="51"/>
</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
<FailedInvoice xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
<Header appId="FEI" date="2015-10-16" fileId="1016777741" infileId="0917545792"
senderId="HABALT22" />
<Invoice>
<ChannelId>HABALT22</ChannelId>
<InvoiceId>456790</InvoiceId>
<InvoiceGlobUniqId>1234</InvoiceGlobUniqId>
<GlobalSellerContractId>1017968HABALT2241</GlobalSellerContractId>>
</Invoice>
</FailedInvoice>
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.
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
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
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
<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>
<Action>ADD</Action>

<ChannelId>HABAEE2X</ChannelId>
<ChannelAddress>221002938946</ChannelAddress>
<PresentmentType>FULL</PresentmentType>

<CustomerIdCode>38004160294</CustomerIdCode>
<CustomerName>MAALI MAASIKAS</CustomerName>
<CustomerEmail>[email protected]</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>
<AdditionalServiceId>1234</AdditionalServiceId>
<ChannelId>HABALV22</ChannelId>
<ChannelAddress>LV27HABA0551006170865</ChannelAddress>
<CustomerName>NUTELLA CORPORATION</CustomerName>
<UserCode>10581787</UserCode>
<UserName>Leonīds Purviņa</UserName>
<CancelPreviousInvoice>NO</CancelPreviousInvoice>
<CustomerPhone>+37167444444</CustomerPhone>
57
</Application>
</ApplicationBank>
Example response XML, LT
<ApplicationBank xsi:noNamespaceSchemaLocation="applicationBank.xsd" senderId="HABALT22"
fileId="1213670762" date="2015-12-13" appId="EIA"
<Application>
<GlobalSellerContractId>123456789HABALT22123456</GlobalSellerContractId>
<ChannelId>HABALT22</ChannelId>
<ChannelAddress>LT27HABA2251006170865</ChannelAddress>
<CustomerName>NUTELLA CORPORATION</CustomerName>
<CustomerPhone>+37067444444</CustomerPhone>
</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)
<StandingOrderAgreementIncoming>
<Filename>SOAreport.xml</Filename>
<CountryCode>EE</CountryCode>
</StandingOrderAgreementIncoming>
Example request XML (APAreport-request.xml, LV)
<Filename>APAreport.xml</Filename>
<CountryCode>LV</CountryCode>
59
Example request XML (APAreport-request.xml, LT)
<Filename>APAreport.xml</Filename>
<CountryCode>LT</CountryCode>
<ContractId>123456789HABALT22123456</ContractId>
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)
<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">
<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>
<EndDate/>
</Agreement>
</EInvoiceStandingOrderAgreementReport>
Example request XML (SOAreport.xml, EE, UPD)
senderId="HABAEE2X"
<Action>UPD</Action>
<PartialDebiting>YES</PartialDebiting>
60
<EndDate/>
</Agreement>
Example request XML (SOAreport.xml, EE, DEL)
senderId="HABAEE2X"
<Action>DEL</Action>
<PartialDebiting>YES</PartialDebiting>
</Agreement>
Example request XML (APAreport.xml, LV, ADD)
appId="EAPREP" date="2014-08-03" fileId="0803106031"
<Agreement name="SOA" sequenceId="1">
<PayerName>Ārija Lęšis</PayerName>
<PayerIBAN>LV38HABA0551000003213</PayerIBAN>
<EndDate />
</Agreement>
Example request XML (APAreport.xml, LV, UPD)
61
<EndDate />
</Agreement>
Example request XML (APAreport.xml, LV, DEL)
</Agreement>
Example request XML (APAreport.xml, LT, ADD)
appId="EAPREP" date="2014-08-03" fileId="0803106031" receiverId="RECEIVER"
senderId="HABALT22"
<PayerIBAN>LT38HABA0551000003213</PayerIBAN>
<EndDate />
</Agreement>
62
Example request XML (APAreport.xml, LT, UPD)
senderId="HABALT22"
<EndDate />
</Agreement>
Example request XML (APAreport.xml, LT, DEL)
senderId="HABALT22"
</Agreement>
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)
<EinvoiceStandingOrderAgreementResponse>
<Header appId="SOARESP" date="2013-07-30" fileId="0620189613" inFileId="0620189613" receiverId="TESTER1" senderId="TESTER2"/>
</EinvoiceStandingOrderAgreementResponse>
65
Example response XML (success, LV)
<Header appId="EAPRESP" date="2014-10-01" fileId="1001836422"
fileId="18914215" />
in-
Example response XML (success, LT)
<Header appId="EAPRESP" date="2014-10-01" fileId="1001836422" receiverId="TESTER1"
senderId="TESTER2" infileId="18914215" />
In case request file is invalid, following response is sent:
Example response XML (invalid file, EE)
<Header appId="SOARESP" date="2013-07-30" receiverId="TESTER1" senderId="HABAEE2X" fileFailReason="1"/>
Example response XML (invalid file, LV)
<Header appId="EAPRESP" date="2014-09-26" receiverId="TESTER1" senderId="HABALV22" fileFailReason="3" />
Example response XML (invalid file, LT)
<Header appId="EAPRESP" date="2014-09-26" receiverId="TESTER1" senderId="HABALT22" fileFailReason="3" />
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)
<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">
<FailureCode>35</FailureCode>
66
</Agreement>
Example response XML (agreement based errors, LV)
<Header appId="EAPRESP" date="2014-10-01" fileId="1001446072" infileId="18914206" />
</Agreement>
Example response XML (agreement based errors, LT)
<Header appId="EAPRESP" date="2014-10-01" receiverId="TESTER1" senderId="HABALT22"
fileId="1001446072" infileId="18914206" />
</Agreement>
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.
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
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
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
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
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.
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
Example response XML, EE
<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>
<EInvoice number="40669498">
<GlobUniqueId>40669498</GlobUniqueId>
</EInvoice>
<Payment>
<ValueDate>2013-11-16</ValueDate>
<ReferenceNumber>12344</ReferenceNumber>
<Description>Einvioce 40669498 paid</Description>
<ArchiveNumber>2013111600243859</ArchiveNumber>
<Status>Successful</Status>
</Payment>
</EinvoiceStandingOrder>
</EInvoiceSOAPaymentReport>
Example response XML, LV
<EInvoiceSOAPaymentReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPPMT" date="2014-10-01"
xsi:noNamespaceSchemaLocation="eInvoiceSOAPaymentReportLV.xsd">
70
</EInvoice>
<Payment>
</Payment>
Example response XML, LT
<EInvoiceSOAPaymentReport xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" appId="EAPPMT" date="2014-10-01"
xsi:noNamespaceSchemaLocation="eInvoiceSOAPaymentReportLV.xsd">
</EInvoice>
<Payment>
</Payment>
EInvoiceSOAPaymentReport
1..1
EInvoiceSOAPaymentReport@appId
A(9)
1..1
D
Enumeration value=” SOAPMT” in
Estonia
Enumeration value=” EAPPMT” in
Latvia
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.
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.
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
- <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>
<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_amount>4.75</paym_amount>
</transaction>
- <total>
- <trans_curr_summary>
<count>2</count>
<trans_currency>EUR</trans_currency>
<gross_amount>8.70</gross_amount>
</trans_curr_summary>
<count>2</count>
</total>
</card_group>
- <card_group>
<organization />
<type>Debit</type>
<region>Swedbank</region>
+ <transaction>
+ <transaction>
+ <transaction>
+ <transaction>
+ <total>
</card_group>
- <total>
<count>6</count>
<count>6</count>
</total>
</batch>
- <total>
<count>6</count>
<count>6</count>
75
</total>
</terminal>
- <total>
<count>6</count>
<count>6</count>
</total>
</outlet>
- <total>
<count>6</count>
<count>6</count>
</total>
</company>
</posreport>
Example 2: Batch based report
- <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
<count>1</count>
<count>1</count>
</total>
</card_group>
- <total>
<count>1</count>
<count>1</count>
</total>
</batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
+ <batch>
- <total>
<count>83</count>
<count>83</count>
</total>
</terminal>
- <total>
<count>83</count>
<count>83</count>
</total>
77
</outlet>
- <total>
<count>83</count>
<count>83</count>
</total>
</company>
</posreport>
78

Swedbank Gateway Service Description 7.0

Transcription

Similar documents

Batch Production of Driving Distances and Times Using SAS® and

MIDI-PYRENÉES

Giving yourself all the chances to succeed... in college !

parathom - Stillwaters Law Firm

XML - Prof. M. Saeed

Certificate of Registration Williamston Products, Inc.

TOURISTIC BROCHURE 2015

Lecture 2

Sail on our Southern rivers and canals

LavaCon Final Program.book

assisting students from venezuela with the cadivi process

How I learned to love XML! (FME Certified Professional, Peter

advantedge vending

HAL E-BANK MANUAL

trident - URBA 2000