Swedbank Gateway Service Description

Swedbank Gateway service description 

Version 4.2

Contents 

Revision history ................................................................................................................................................ 6 

Definitions and abbreviations .......................................................................................................................... 8 

Introduction ..................................................................................................................................................... 8 

Swedbank Gateway specification ..................................................................................................................... 8 

Sending request data to the bank ...................................................................................................................... 9 

PUT ................................................................................................................................................................ 9 

Receiving responses from the bank ................................................................................................................... 9 

GET ................................................................................................................................................................ 9 

DELETE ........................................................................................................................................................... 9 

Cryptography .................................................................................................................................................... 10 

Client side certificates .................................................................................................................................. 10 

Bank side certificates ................................................................................................................................... 11 

CA and OCSP certificates ............................................................................................................................. 11 

DigiDoc File Format overview ...................................................................................................................... 11 

OCSP validity confirmation overview ........................................................................................................... 12 

DigiDoc usage in SGW ................................................................................................................................. 12 

Error handling ................................................................................................................................................ 16 

Example error message .................................................................................................................................... 16 

Error codes used ............................................................................................................................................... 17 

General error codes ..................................................................................................................................... 17 

Payment error codes .................................................................................................................................... 17 

Direct Debit error codes ............................................................................................................................... 18 

Currency exchange error codes ................................................................................................................... 19 

Troubleshooting ............................................................................................................................................... 20 

Service – Communication test ........................................................................................................................ 21 

Service description ........................................................................................................................................... 21 

Example request XML ....................................................................................................................................... 21 

Description of fields in request XML ................................................................................................................ 21 

Example response XML .................................................................................................................................... 21 

Description of fields in response XML .............................................................................................................. 21 

Service – Account Balance .............................................................................................................................. 22 






Service – Payment .......................................................................................................................................... 24 




Estonian domestic payment ............................................................................................................................. 26 

Latvian domestic payment ............................................................................................................................... 26 

Lithuanian domestic payment .......................................................................................................................... 27 

Foreign payment .............................................................................................................................................. 27 



Service – Account statement .......................................................................................................................... 30 


2





Latvian codes for Transaction/TypeCode .................................................................................................... 33 

Estonian codes for Transaction/TypeCode .................................................................................................. 34 

Lithuanian codes for Transaction/TypeCode ............................................................................................... 34 

Service – Exchange rates ................................................................................................................................ 36 






Service – Currency exchange .......................................................................................................................... 38 






Service – Alert on transactions ....................................................................................................................... 40 





Service – Periodic statement .......................................................................................................................... 43 




Service – Sending e-invoices ........................................................................................................................... 44 






Service – E-Invoices for customer ................................................................................................................... 46 




Service – Direct debit payer agreement management .................................................................................... 47 






Service – Direct debit payer agreement changes ............................................................................................ 50 





3

Service – Direct debit payment requests ........................................................................................................ 53 






Service – POS report delivery ......................................................................................................................... 56 




Example 1: Transaction based report ............................................................................................................... 56 

Example 2: Batch based report ........................................................................................................................ 58 

4

Figures 

Figure 1: DigiDoc container ............................................................................................................................ 11 

Figure 2: Overview of sending requests and receiving responses from the bank ............................................ 13 

Figure 3: Signing, encrypting and sending messages to the bank.................................................................... 14 

Figure 4: Receiving, decrypting and verifying messages from the bank .......................................................... 15 

5

Revision history 

Version Changes Date 

2.9 Changed EE domestic payment fields: 

05.12.2008 

BeneficiaryName (length 70) 

Changed Foreign payment fields: 


BeneficiaryAddress (length 70+optional) 

Details (length 140) 

Cost (comment) 

BalanceOfPaymentsCountry (comment) 

2.10 Changed LV domestic payment fields: 

11.12.2008 


BeneficiaryBankCode (mandatory) 

Added new error codes 

2.11 Added more information to service specification 

07.01.2009 

EE payment document number (length) 

Foregin payment tag: BeneficiaryIBAN – removed 

2.12 Added additional information about Active MQ in paragraph Service 

27.01.2009 

specification > More about message exchange and ACK: 

XML validation demand in paragraph HGW Exceptions and errors 

2.13 Lithuanian fields (OrderingParty/IBAN, OrderingParty/Name, Assignee/IBAN, 04.03.2009 

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 

2.14 Removed sample client information 13.05.2009 

2.15 LT payment tag change: Assignee/IBAN =>Assignee/Account 

07.07.2009 

LT payment tag change: OrderingParty/IBAN =>Ordering/Account 

Foreign payment rule fix 

3.0 Major changes in communication protocol. Dropping Active MQ and starting 14.09.2009 

to use HTTP protocol. All communication parameters are changed. 

3.1 Added info about HTTP protocol at the pg 6. 

09.11.2009 

Added additional tag for LV in statements and alert - tag BIC 

3.2 Added info about troubleshooting 18.01.2010 

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 

03.01.2011 

payment “BalanceOfPaymentsCode” is mandatory as from 50,000 EUR 

equivalent for EE 

3.6 Changed xsd validation addresses inside examples to 

01.03.2012 

http://swedbankgateway.net/... 

Added Process Flow diagrams for message exchange and certificate usage. 

Corrected terminology referring to certificates. 

4.0 Revised and expanded Swedbank Gateway specification description. 

24.04.2012 

Revised error handling and error codes. 

Changed document style. 

Added a table of figures. 

4.1 Added bank response message header X-Gateway-Message functionality. 10.10.2012 

6

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 

4.2 Corrected Service – Direct debit payer agreement changes root-tag: from 

to 

Added sample XML for POS reports – transaction based report and batch 

based report. 

11.12.2012 

7

Definitions and abbreviations 

IS – Information System 

ERP – Enterprise Resource Planning 

DigiDoc file format – DigiDoc file format is a profile of XAdES (XML Advanced Electronic Signatures), 

technical standard published by ETSI (European Telecommunication Standards Institute) 

DD – DigiDoc 

SK – Sertifitseerimiskeskus AS (CA in Estonia, http://www.sk.ee) 

RC – Registru Centras (CA in Lithuania, http://www.registrucentras.lt/rcsc/index_en.php) 

B4B – software certificate profile defined by SK (http://www.sk.ee/en/repository/CP/) 

SGW – Swedbank Gateway channel 

PKI – Public Key Infrastructure 

Introduction 

Swedbank Gateway is an 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 SLL) 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: 

Swedbank Gateway service agreement, preceded by SGW application. 

Develop required software for exchanging data between Client IS and SGW or use Bank’s 

sample command line Java Client for communication. 

Successful testing results from Swedbank Gateway Sandbox environment. 

8

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. 

The response contains: 

Header X-Gateway-Message – header with value „1“ confirming that message reached to the 

service 

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 

The GET request has no 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 


DELETE 

Request parameters: 

Header TrackingID – Bank side message ID received with the GET response. 



service 

9

HTTP Response codes: 

200 – OK 

400 – Bad request. Most probably no message found with the given Tracking ID 


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 DigiDoc 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 

1. ERP certificate – certificate that identifies that messages were sent by client’s ERP (e.g. information 

system) to the bank. The bank uses this certificate to address all encrypted information that 

is being sent to client (only client can see the content). This certificate is issued by SK under 

“B4B” profile; therefore it is sometimes also called as “B4B certificate”. 

This certificate is issued from KLASS3 root. Read more about SK’s certificate policies - 

http://www.sk.ee/en/repository/CP/ 

In Lithuania, we also support ERP certificates that are issued by Lithuanian Registru Centras - 

http://www.registrucentras.lt/rcsc/index_en.php 

2. Transport certificate – transport certificate is being 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 being used – i.e. ERP certificate also has the 

role of a transport certificate. 

3. Signing certificate (sometimes referred to as “Transaction Certificate”) – signing certificates are 

used for signing payments in SGW channel. Signing certificates should always be on a physical 

device (i.e. they are 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 certificates should always 

have “non-repudiation” key-usage. 

Currently accepted Signing certificates in SGW channel: 

Estonian ID cards 

Estonian Digi-ID 

Estonian Mobile-ID (M-ID) 

Lithuanian ID cards 

Lithuanian Mobile-ID 

Finnish E-ID 

Estonian cryptostick 

Lithuanian cryptostick 

Since certificates are valid only for a certain period, client has to monitor the validity of certificate 

and get a new certificate when it expires. For mission critical systems where interruptions are not 

10

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 certificate is used to sign all outgoing messages, so that clients can verify that all 

information is sent by the bank. All messages that clients are sending to the bank, will be encrypted 

with the bank certificate’s public key – so that only the bank will be able to open them. 

Information regarding Bank’s currently valid certificate is provided to you with SGW development 

toolbox. Since Bank’s certificate is valid only for certain period, clients should be aware and 

plan tasks required on their side to update Bank’s certificate. Since certificates can be issued 

from new roots, that may also mean trusting new root level certificates of CA. 

CA and OCSP 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/ 

DigiDoc File Format overview 

Digitally signed file format is based on the ETSI TS 101 903 standard called "XML Advanced Electronic 

Signatures (XAdES)". This standard describes the structure of digitally signed documents on various 

information validity confirmation containment levels. Based on the model of trust above, the DigiDoc 

XAdES corresponds to profile “XAdES-XL”. This profile allows to incorporate with a signature the following 

signing attributes: 

Certificate used for signing 

Signing time 

Location of the signing 

The role of the signer, or resolution 

Signature contains the signer’s certificate validity information 

OCSP response 

OCSP server certificate 

Figure 1: DigiDoc container 

11

The model enables XAdES-CL profile signature verification without additional information the verifier 

should trust the certificate issuer and the certificate of the OCSP validity confirmation server. 

DigiDoc container contains original files (the files that were signed) and signatures which are related 

to the signed file(s). Each signature contains signer’s certificate, validity confirmation and validity 

confirmation service certificate. 

DigiDoc system uses .ddoc extension for the files complying with the model above. 

OCSP validity confirmation overview 

The service is based on OCSP (Online Certificate Status Protocol), which has been described in 

Internet standard RFC 2560. OCSP is a simple client-server system where an OCSP client sends to the 

OCSP responder (server) a query about a certificate and the responder gives a confirmation regarding 

the certificate, which contains the validity of the certificate, invalidity and the time of giving the 

confirmation. The reply given by the responder is digitally signed. 

OCSP responder has three replies regarding a certificate: 

Certificate is valid. 

Certificate is not valid. 

No information about the requested certificate. 

OCSP's positive response means that the certificate has been issued and it was valid at the time of 

giving the confirmation. 

DigiDoc usage in SGW 

In SGW we are using version 1.3 of the DigiDoc file format. The XSD can be found at this address 

http://www.id.ee/public/DigiDoc_1.3.xsd and description in PDF format here 

http://www.id.ee/public/DigiDoc_format_1.3.pdf. 

Request DigiDoc itself has to be encrypted using the bank certificate’s public key (“Recipient” property 

of that EncryptedKey in DigiDoc has to be “HGW” – it is possible to encrypt DigiDoc for several 

recipients and this rule lets us choose correct encrypted transport key block for decryption). It also 

has to be signed with Client ERP Certificate’s Private Key and in case of transactions, additionally with 

Signing certificate with OCSP confirmation. ERP signature must have role “ERP” set. 

Response is an encrypted and signed DigiDoc file or a plaintext XML file with error details if request 

could not be processed. 

12

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 

Request XML 

file 

DDOC: Signed 

container 

Request XML 

file 

Encrypt with Bank 

Certificate Public Key 

CDOC: Encrypted with Bank 


DDOC: Signed 

container 

Request XML 

file 

Send to Bank 

Receiving response files from Bank (except Alert service response) 

Receive from 

bank 

CDOC: Encrypted with Client ERP 


DDOC: Signed 

with Bank 

Certificate 

Response 

XML file 

Decrypt with Client 

ERP Certificate 

Private Key 

DDOC: Signed with 

Bank Certificate 

Response 

XML file 

Verify Bank 

Signature 

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 

Alert response 

XML file 

Receive Alert from bank 

Figure 2: Overview of sending requests and receiving responses from the bank 

13

IS sending request to Bank via SGW channel 

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) 

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) 

No 

IS checks 

Bank’s public 

key 

CDOC: Encrypted with 

Bank’s Public Key 

- Connection via SSL protocol. 

- Session is being 

authenticated by client’s 

Transport certificate (B4B) 

IS prepares 

request 

to Bank 

Request 

XML file 

- Technical signature 

(digital signature) given with software 

based ERP certificate. 

- OCSP confirmation is not required 

File is signed 

digitally by IS 

1 

IS signs with 

ERP certificate, 

using DD library 

Sign by 

person? 

Yes 

2 

User signs with 

Signing 

certificate from 

hardware token 

Encrypt with 

Bank’s public 

key 

3 

DDOC: Signed 

container 

Request 

XML file 

- 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 

IS sends file to 

Bank 

4 

Bank receives 

request 

Qualifying certificates: 

• SK issued certificate (B4B) 

• SK issued Digital Stamp 

• RC issued software certificate 

DDOC: Signed 

container 

Request 

XML file 

DDOC: Signed 

container 

Request 

XML file 


• EST ID card 

• Digi ID 

• M-ID 

• Digital Stamping 

• Lithuanian ID card 

• Finnish ID card 

• EST cryptostick 

• LT cryptostick 

Operations legend: 

Can be made 

(called out) with 

DigiDoc library 

IS development 

responsibility 

Certificate usage: 

1 Technical signing – software based ERP 

certificate (B4B) is used to sign document by 

IS 

2 Legal Signing – hardware token based 

Signing certificate is used to sign document 

by person. Mandatory for payments 

3 Encryption – Bank’s public key is used for 

encryption. Bank has certificate with Digital 

Stamp profile 

4 Authentication – software based Transport 

certificate (B4B) is used to authenticate 

client’s session 

Figure 3: Signing, encrypting and sending messages to the bank 

DigiDoc usage (library / utility): 

1 Technical signing – sign document 

with software certificate (issued under 

B4B profile). OCSP validity 

confirmation not required 

2 Legal Signing – sign document with 

hardware certificate (ID Card or other 

supported token). OCSP validiy 

confirmation required 

3 Encryption – Bank’s public key is used 

for encryption – Bank has certificate 

with Digital Stamp profile 

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 

14

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 generates 

response 

Operations legend: 

Response 

XML file 

- Bank’s legal signature is given with 

hardware token certificate – Digital 

Stamp (key usage=non-repudiation, 

digital signature) 

- OCSP validity confirmation is 

mandatory to include 

- support of relevant OCSP 

responder certificates is important 

Can be made 

(called out) with 

DigiDoc library 

Client’s 

development 

responsibility 

Qualifying certificate: 

• Digital Stamping 

Certificate usage: 

1 Legal Signing – hardware certificate (Digital 

Stamp) is used to sign payments by Bank 

2 

Bank checks Client’s public 

certificate from LDAP 

directory before sending any 

message (i.e. checks if 

Client’s certificate hasn’t 

been compromised) 

Sign by Bank 

Yes 

1 

Signing with 

Digital Stamp, 


DDOC: Signed 

container 

Response 

XML file 

Encryption – Client’s ERP certificate (B4B) 

public key is used for encryption. 

3 Authentication – Client’s software based 

Transport certificate (B4B) is used to 

authenticate client’s session 

Bank checks 

Client’s ERP 

certificate public 

key 

Encrypt with 

Client’s public 

key 

2 


• SK issued certificate (B4B) 

• Digital Stamping’s 

authentication certificate 

• RC issued software 

certificate 

Only client who has appropriate ERP 

certificate’s private key, can decrypt the 

file to see it’s content 


Client’s Public Key 

DDOC: Signed 

container 

Response 

XML file 

DigiDoc usage (library / utility): 

1 Legal Signing – Bank signs document 

with hardware certificate (Digital 

Stamp) 

2 Encryption – Client’s ERP certificate 

(B4B) public key is used for encryption. 

4 Decryption – Client’s ERP certificate 

(B4B) private key is used for 

decryption 

Bank puts file to 

client’s „Inbox” 

at SGW channel 

Client’s 

files 


Client’s Public Key 

DDOC: Signed 

container 

Response 

XML file 

IS verifies if Bank’s 

signature is both 

correct and valid. After 

that file can be used. 

- 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 

Bank 

authenticates 

client by 

Transport 

certificate 

IS downloads 

response files 

from Bank 

3 

4 

IS decrypts 

message with 

ERP certificate 


DDOC: Signed 

container 

Response 

XML file 

IS validates 

Bank’s signature 

Response 

XML file 

Figure 4: Receiving, decrypting and verifying messages from the bank 

IS can use file 

15

Error handling 

Error responses are sent as an XML file than can be in unencrypted form or inside an encrypted Digi- 

Doc container. Error responses are sent unencrypted in case the request DigiDoc 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. 

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 

 

 

 

AccountNotAllowed 

You have no rights to these accounts through HGW agreement. 

 

 

16

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! 

6009 Insufficient funds for transaction on the account! 

6100 Locking of current account failed! 

Payment error codes 

Code 

balanceOfPaymentsCode 

RemitterIBAN 

BeneficiaryIBAN 

BeneficiaryBankAccount 

BeneficiaryAddress 

ValueDate 

Currency 

BeneficiaryBankCode 

BeneficiaryResidence 

DocumentNumber 

Amount 

BeneficiaryName 

RemitterPaymentID 

ValueDateFormat 

Costs 

BeneficiaryBankName 

ReferenceNumber 

Details 

ReferenceLV 

ReferenceNumberTooLong 

InvalidIdentificationType 

nameMatchIsTooSmall 


Balance of Payments code is missing! 

Remitter IBAN is invalid! 

Beneficiary IBAN is invalid! 

Beneficiary bank account is invalid! 

Beneficiary address is missing! 

Invalid date! 

Invalid currency! 

Beneficiary bank code is invalid! 

Beneficiary residence is invalid! 

Document number is missing! 

Amount is missing or invalid! 

Beneficiary name is missing! 

Payment ID is missing! 

Value date format is invalid! 

Costs is incorrect! 

Beneficiary bank name is invalid! 

Reference number is invalid! 

Payment details or reference number must be set! 

Reference number is not supported in Latvia! 

The Creditor Reference number is too long! 

Invalid Identification type! 

The account number and the name do not coin- 

17

missingDetails 

missingDetailsOrReferenceNumber 

beneficiaryNameTooLong 

intrabankPaymentCannotBeUrgent 

incorrectFormatOrderingPartyId 

missingOrderingPartyName 

incorrectFormatAssigneeId 

missingAssigneeName 

domesticPaymentCouldBeOnlyInLocalCurrency 

paymentToTheSameAccountIsNotAllowed 

operationWithCurrencyNotAllowed 

invalidValueDate 

missingBopCode 

ERR00006 

ERR00057 

H0011 

Direct Debit error codes 

Code 

InvalidIBAN 

UtilityNumberIsMandatory 

InvalidOperation 

InvalidAccountNumber 

InvalidRemitterRegistrationNumber 

RemitterAccountInWrongCountry 

LimitLessThanZero 

NoActiveRemitterAgreement 

DiscountNumberIsMandatory 

LimitNotAllowed 

LimitRequired 

ReferenceRequired 

ReferenceTooShort 

ReferenceTooLong 

ReferencePrefixInvalid 

DebitingPeriodStartTooEarly 

DebitingPeriodEndTooLate 

DebitingPeriodUsingNotAllowed 

cide! 

Payment details are missing! 

Payment details or reference number must be set! 

Beneficiary name is too long! 

Intrabank payment cannot be urgent! 

Incorrect Ordering Party ID! 

Ordering party name is missing! 

Incorrect Assignee ID! 

Assignee name is missing! 

Only local currency is allowed for domestic payments! 

Remitter and beneficiary accounts must be different! 

Operation with this currency is not allowed! 

Payment date is not valid for this agreement! 




Duplicate payment! You have already made a payment 

with the same data within 24 hours. Payment 

cancelled! 


Invalid IBAN! 

Utility number is required! 

Invalid operation! 

Invalid account number! 

Invalid remitter registration number! 

Remitter account is in the wrong country. 

Limit is less than zero! 

No active remitter agreements found! 

Discount number is required! 

Limit is not allowed! 

Limit is required! 

Reference is required! 

Reference is too short! 

Reference is too long! 

Reference prefix is invalid! 

Debiting period starts too early! 

Debiting period ends too late! 

Debiting period is not allowed! 

18

AgreementNotFound 

AgreementEndDateInPast 

AgreementStartDateInPast 

AgreementStartDateLaterThanEnd 

RemitterAgreementConcludingIsNotAllowed 

RemitterAgreementClosingIsNotAllowed 

PaymentDateIsEarlierThanOperationDate 

PaymentDateIsEarlierThanAgreementStartDate 

invalidCurrency 

InvalidPayerAgreement 

AmountOverLimit 

Agreement not found! 

Agreement end date is in the past! 

Agreement start date is in the past! 

Agreement start date is later than the end date! 

Remitter agreement concluding is not allowed! 

Remitter agreement closing is not allowed! 

Payment request date is earlier than the operation 

date! 

Payment request date is earlier than the remitter 

agreement start date! 


Remitter agreement ID is invalid! 

Specified amount is over the limit! 

2135 Wrong agreement start date for the changed remitter 

agreement! 

2136 New remitter agreement start date is later than the 

previous or new end date! 

6202 Beneficiary account does not have a valid beneficiary 

agreement! 

6212 Remitter agreement payment date is earlier than 

the debiting start date! 

6213 Remitter agreement payment date is later than the 

debiting end date! 

6214 Remitter agreement payment date cannot be used 

with the given beneficiary agreement! 

register_dd_remit_agreement_2104 

Invalid contract start date! 



Currency exchange error codes 

Code 

ExchangeRateNotFound 

Remitter agreement with the given reference 

number already exists! 

Beneficiary's utility number or discount number is 

not unique! 


Currency not found! 

6093 Currency exchange is not permitted! 

6094 Currency exchange is not permitted! 

19

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

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 certificate name 

Filename 

Time when the message was sent 

Account number 

The response received 

The more information the bank receives for troubleshooting the faster the bank will be able to answer 

and solve the issue! 

20

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 

 

 

Test 

 

Description of fields in request XML 

Ping 1..1 

Ping/Value AN (0 – 210) Something that customer wants to be sent back. 0..1 

Example response XML 

 

 

 

Test 

 

 

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 

21

Service – Account Balance 


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. 

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

If account number is omitted, there will be one response for each country where an SGW agreement 

is visible for given transport/ERP certificate combination. 


 

 

LT117300010000131196 

2007-08-20 

 


GetBalance 1..1 

GetBalance/IBAN AN (4 – 35) Account number in IBAN format. 0..1 

GetBalance/Date D Balance data. Defaulting to current day. 0..1 


 

 

 

2007-08-20 

 

LT117300010000131196 

HABALT2X 

 

 

 

 

-301.07 

0.00 

0.00 

-301.07 

 

 

-100.00 

0.00 

0.00 

-100.00 

 

 

22

 


Balance 

One Balance element for each account 1..* 

in response. 

Balance/Date D Balance date. If none was given in request, 

1..1 

bank’s operation date. 

Balance/AccountInfo 

One AccountInfo element in each Balance 

1..1 

element. 

Balance/AccountInfo/IBAN AN (4 - 35) Account number 1..1 

Balance/AccountInfo/BIC AN (8) Responding bank BIC code 1..1 

Balance/AccountInfo/BankName CDATA Responding bank name 1..1 

Balance/Currencies 

One Currencies element in each Balance 

1..1 

element. 

Balance/Currencies/Currency 

One Currency element for each currency 

0..* 

on given account. 

Balance/Currencies/Currency/@id A (3) Currency code is returned as id 

1..1 

attribute of Currency element. 

Balance/Currencies/Currency/Deposit N Account balance 1..1 

Balance/Currencies/Currency/Reserved N Total of reservations 1..1 

Balance/Currencies/Currency/Credit N Overdraft limit 1..1 

Balance/Currencies/Currency/Available N Deposit – Reserved + Credit 1..1 

23

Service – Payment 


Payment is a customer-initiated query. Customer can send one or more payments with one request. 

There are different payment formats supported in SGW - native formats for domestic and foreign 

payments (with country-specific differences between Estonian, Latvian and Lithuanian domestic 

payments) are described in detail here in this document. Additionally ISO20022 format 

pain.001.001.02 and pain.002.001.02 messages are supported – detailed implementation guidelines 

can be found in http://dev.hansagateway.net/download/SGW_ISO20022_IMPL.pdf. Access to this 

SGW development toolbox download site http://dev.hansagateway.net/download is IP-address 

based. 

Like all other SGW services, payments are in one XML file contained in encrypted and signed Digi- 

Doc. Swedbank responds with one or more status reports as payments are being processed. 

Every SGW agreement has agreement specific limits for payments (daily limit usage is reset every 

midnight, monthly limit usage is reset at midnight on the first of every month) and call-back limit that 

every payment is checked against. SGW agreement may have a list of users who are permitted to 

make transactions (operations like payment and currency exchange) with daily and monthly limits of 

their own. Limits are defined in local currency and payment amount is checked against them after 

being converted into local currency using central bank rate. SGW agreement enables setting doubleacceptance 

condition to transactions per account, when this condition is activated SGW requires at 

least two authorized users’ signatures in the request. 

Payment service requires that DigiDoc 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 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. If more than one user has signed payments 

then SGW will try to use limits of users in the order the users have signed the DigiDoc file. If first user 

does not have enough available limits, next user’s limit is checked and so on. 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 checking limit in the agreement, payment will be made only after back-office employee has 

called and verified payment, but limits (both daily and monthly limits for both user and agreement) 

are used during initial processing by SGW. 


 

 

 

 

C1_D_EE_01 

C1_D_EE_01 

2007-08-14 

N 

EE352200221000127267 

6.78 

EUR 

EE922200221010214144 

ÕU'NEILL 

B4B Estonian Domestic payment, Happy1 - 1 

7605262 

24

 

C1_D_LT_01 

C1_D_LT_01 

2007-08-14 

N 

LT257300010161511493 

2.45 

LTL 

LT617300010071014501 

ŠÄÄKAL PÜVI 

B4B Lithuanin Domestic payment, Happy1 - 1 

 

 

C1_D_LV_01 

C1_D_LV_01 

2007-08-14 

N 

LV35HABA0551000141298 

1.24 

USD 

LV13UNLA0001001609573 

Maris 

B4B Latvian Domestic payment, Happy1 - 1 

LV 

UNLALV2X 

 

 

C1FLT01 

1 

2007-08-14 

N 

LT257300010161511493 

6.31 

LTL 

USD 

Peatänav 4 - 14, Tallinn, Eesti Vabariik 

Toomas Nipi 

LB 

B4B Lithuanian Foreign payment, Happy1 - 1 

O 

200 

EE 

 

Hansabank 

HABAEE2X 

EE922200221010214144 

 

 

 

 


At the moment there are four different payment types supported by SGW. 

Payments 1..1 

25

Estonian domestic payment 

Payments/DomesticPaymentEE 0..* 

ID AN (1 - 50) Id of a payment. We suggest it to be unique in 1..1 

payment file. This value is not shown to beneficiary. 

DocumentNumber AN (1 – 8) Document number of payment shown to 1..1 

beneficiary. 

ValueDate D YYYY-MM-DD 1..1 

Priority A (1) ‘N’ = Normal 1..1 

RemitterIBAN AN (4 - 35) Payer account number. Needs to be in IBAN 1..1 

format. 

Amount N Needs to be positive. ‘.’ is used as decimal 1..1 

separator. 

Currency A (3) 1..1 

BeneficiaryIBAN AN (4 – 35) Beneficiary account in IBAN format. 1..1 

BeneficiaryName AN (1 – 70) 1..1 

Details AN (0 – 300) Either details or reference number may be 

missing. 

ReferenceNumber AN (0 – 20) Either details or reference number may be 

missing. 

Latvian domestic payment 

Payments/DomesticPaymentLV 0..* 



DocumentNumber AN (1 – 10) Document number of payment shown to beneficiary. 

1..1 


Priority A (1) ‘N’ = Normal, ‘U’ = Urgent 1..1 


format. 


separator. 



BeneficiaryID AN (1 – 15) 0..1 


Details AN (0 – 300) 1..1 

BudgetCode N (0 – 10) 0..1 

BeneficiaryResidence A (2) Country code 1..1 

BalanceOfPaymentsCode N (3) Mandatory from 1000 LVL (or equivalent) 0..1 

when latvian resident is paying to a nonresident. 

BeneficiaryBankCode AN (8 – 11) SWIFT 1..1 

0..1 

0..1 

26

Lithuanian domestic payment 

Payments/DomesticPaymentLT 0..* 



DocumentNumber AN (1 – 10) Document number of payment shown to beneficiary. 

1..1 


Priority A (1) ‘N’ = Normal, ‘U’ = Urgent. 1..1 


format. 


separator. 




Details AN (0 – 300) 1..1 

ReferenceNumber AN (0 – 28) 0..1 

ReferenceToPayer AN (1 – 16) 0..1 

BeneficiaryRegistrationCode AN (1 – 15) 0..1 

ReferenceToBeneficiary AN (1 – 16) 0..1 

OrderingParty 0..1 

OrderingParty/Account AN (4 – 35) 0..1 

OrderingParty/Id AN (1 – 11) 0..1 

OrderingParty/Name AN (1 – 140) 0..1 

Assignee 0..1 

Assignee/Account AN (4 – 35) 0..1 

Assignee/Id AN (1 – 11) 0..1 

Assignee/Name AN (1 – 140) 0..1 

Foreign payment 

Payments/ForeignPayment 0..* 

ID AN (1 - 50) Id of a payment. We suggest it to be 1..1 

unique in payment file. This value is not 

shown to beneficiary. 

DocumentNumber AN (1 – 8) Document number of payment shown to 1..1 

beneficiary. 


Priority A (1) ‘N’ = Normal, ‘U’ = Urgent, ‘E’ = Express. 1..1 

Costs A (1) EE and LT (‘O’ = commission is paid by 

remitter, ‘S’ = commission is shared between 

both parties) 

LV (‘O’ = commission is paid by remitter, 

‘B’ =commission is shared between parties 

1..1 

27

RemitterIBAN AN (4-35) Payer account number. Needs to be in 1..1 

IBAN format. 


separator. 


DebitCurrency A (3) 1..1 


Details AN (1 – 140) 1..1 

BeneficiaryAddress AN (1 - 70) 0..1 

BeneficiaryResidence A (2) Country code 1..1 

BalanceOfPaymentsCode N (3) EE, LV:Conditional->; LT - not used 0..1 

Mandatory as from 50,000 EUR equivalent 

for EE* and from 1000 LVL equivalent for 

LV** 

BalanceOfPaymentsCountry A (2) Country code 

1..1 

EE, LV:Conditional->; LT - not used 

BeneficiaryBank 1..1 

BeneficiaryBank/Name AN (1 - 140) 1..1 

BeneficiaryBank/BIC AN (8 – 11) Large chars. only 0..1 

BeneficiaryBank/Account AN (4 – 35) 1..1 

CorrespondentBank 0..1 

CorrespondentBank/Name AN (1 - 140) 1..1 

CorrespondentBank/BIC AN (8 – 11) 0..1 

CorrespondentBank/Account AN (4 – 35) 0..1 

IntermediaryBank 0..1 

IntermediaryBank/Name AN (1 - 140) 1..1 

IntermediaryBank/BIC AN (8 – 11) 0..1 

IntermediaryBank/Account AN (4 – 35) 0..1 

* Estonian codes: http://www.eestipank.ee/en/transaction-codes-used-case-payments-originatedclients-credit-institutions 

** Latvian codes: http://www.bank.lv/en/legal/list-of-external-payment-codes-lepc-21 


As above example has payments from three different countries (domestic payment in Estonia, domestic 

payment in Latvia, domestic payment and foreign payment in Lithuania), 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. 

 

 

 

 

28

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


B4B/PaymentStatus Root element of status report 1..1 

PaymentStatus/Payment Payment details 1..* 

Payment @ id AN (1 - 50) Payment id assigned by remitter 1..1 

Payment @ status A success/failed/processing – state of payment 1..1 

Payment @ bankReference 

N (16) For payment in success state Swedbank Gateway 

also reports reference to debiting operation. 

Payment @ error A For payment in failed state Swedbank Gateway reports 

the reason of failure. 

0..1 

0..1 

29

Service – Account statement 


Customer can use this service to request a list of transactions on account in a given period. The period 

range can be up to 365 days. If the period also includes current day, the request is charged – also 

the service Current Day Statement has to be activated 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). Statement/Partial element’s value in response XML is used to 

show if this response is last part of statement or not (“Complete” means last part, “Partial” being the 

opposite). 


 

 

2007-06-09 

2007-06-17 

EE392200221011508011 

 


AccountStatement 1..1 

StartDate D Request validation will return error if StartDate is later 1..1 

than EndDate or missing. 

EndDate D Request validation will return error is EndDate is later than 1..1 

previous day or missing. 

IBAN AN (4 – 35) Account number 1..1 


 

 

 

 

EE392200221011508011 

HABAEE2X 

 

 

complete 

 

2007-06-09 

2007-06-17 

 

 

 

 

 

 

45010.12 

35027.12 

 

 

MK 

30

2007-06-14 

2007-05-11 

2007061400000190 

4 

 

-1.00 

 

 

 

EE482200221011515415 

 

 

 

TT 

2007-06-14 

2007061400000190 

 

-2.00 

 

 

 

 

 

 

 

X 

2007-06-14 

2007061400000238 

EUR 636.74 kurss 15.6735]]> 

-9980.00 

 

 

 

 

 

 

 

 

 

1023.23 

1659.97 

 

 

X 

2007-06-14 

2007061400000238 

EUR kurss 15.6735]]> 

636.74 

 

 

 

 

 

 

 

 

 

475.00 

475.00 

 

31

 


B4B/Statement 1..1 

AccountInfo Container element inside B4B/Statement 1..1 

AccountInfo/IBAN AN (4 – 35) Account number 1..1 

AccountInfo/BIC AN (8) Bank code of responding bank 1..1 

AccountInfo/BankName CDATA Name of responding bank 1..1 

Partial A Partial/Complete 1..1 

Page D 1..1 

Period Container element inside B4B/Statement 1..1 

Period/StartDate D Start date from request 1..1 

Period/EndDate D End date from request 1..1 

Customer Container element inside B4B/Statement 1..1 

Customer/Name CDATA Name of account owner 1..1 

Customer/LegalID CDATA Registration number of account owner 1..1 

Currency Container element inside B4B/Statement 0..* 

Currency @ id A (3) Currency code is given in id attribute of 1..1 

Currency element 

Currency/OpeningBalance N 1..1 

Currency/ClosingBalance N 1..1 

Currency/Transactions 

Container element inside Statement/Currency 

1..1 

Transactions/Transaction 0..* 

Transaction/TypeCode AN (5) Values are different in EE, LV, LT, see following 

1..1 

tables. Codes are used to auto- 

matically filter or summarize different 

types of transactions, for example Bank's 

service fees. 

Transaction/TransactionDate D 1..1 

Transaction/ReferenceDate D Document date 0..1 

Transaction/BankReference N (16) 1..1 

Transaction/DocumentNumber AN (1 – 30) Payment document number 0..1 

Transaction/ReferenceNumber AN (1 – 60) Reference to beneficiary 0..1 

Transaction/Description CDATA 1..1 

Transaction/Amount N 1..1 

Transaction/ReferenceToPayer AN (1 - 16) Reference number (Lithuanian) 0..1 

Transaction/Counterparty 

Container element inside Transactions/Transaction 

1..1 

Counterparty/Name CDATA 1..1 

Counterparty/LegalID CDATA 1..1 

Counterparty/IBAN AN (4 – 35) 1..1 

32

Counterparty/BIC Latvian specific 1..1 

Counterparty/ 

ReferenceToBeneficiary 

Transaction/OrderingParty 

AN (1 - 16) Lithuanian-specific 0..1 

Container element inside Transactions/Transaction. 

Used for Lithuanian 

payments. 




Transaction/Assignee 


0..1 

Used for Lithuanian 

payments. 




0..1 

Latvian codes for Transaction/TypeCode 

Value 

OB 

CB 

K2 

T2 

PRV 

MK 

IEM 

IZM 

INB 

IZP 

CTX 

SOD 

EXC 

CQA 

KOM 

DKA 

DPL 

AUT 

AIA 

AZA 

SEC 

TBP 


Opening balance 

Closing balance 

Turnover 

Fees amount 

Internal transfer 

Domestic currency payment 

Cash lodgement 

Cash withdrawal 

Incoming transfer 

Outgoing transfer 

Payment card transactions 

Standing order 

Currency exchange 

Cashing of a cheque 

Comission for cash withdrawal/ Comission for a transfer/ Cheques commission 

Deposit or escrow account opening 

Deposit breach or deal settlement 

End of deposit 

Accrued interest payment into account 

Loan repayment 

Securities operations 

T-bill purchase 

33

TBC 

7DN 

IKS 

T-bill comission 

Amount booking 

Cash delivery 

Estonian codes for Transaction/TypeCode 

Value 

TT 

MK 

MV 

MP 

M 

K 

X 

I 

PT 

MD 

S 


Service charge - indicating that the transaction was Bank's service fee 

Domestic payment order - i.e. regular payment inside the value country 

International payment order 

Consolidated payment 

Other charges 

Card transaction 

Currency transaction 

Interest 

Standing order service charges 

Deposits 

Cash operation 

Lithuanian codes for Transaction/TypeCode 

Value 

AS 

LS 

K1 

K2 

MK 

DP 

MV 

S 

IM 

IMG 

IMB 

IME 

MD 

MP 


Opening balance 

Closing balance 

Daily turnover 

Account turnover over the specified period 

Payment orders within the bank and between banks 

incorporated in Lithuania, in LTL and currency 

Debit orders and collections 

International payment orders 

Cash operation 

Payments 

Payments in cash in a branch 

Payments in a branch (transfer) 

Payments via Internet bank 

Operation related to the deposit 

Mass payment 

34

DD 

X 

K 

TS 

M 

I 

AI 

PV 

TT, TT1-TT10 

TT11 

TT12 

TT13 

TT14 

T2 

G 

PT 

CTX 

SMS 

S1 

BL 

Direct debit operation 

Currency conversion 

Card operation 

Operations with Bank, Traveller's Cheques 

Interest, manual debiting and crediting operations 

Interest, loan interest, overdrafts 

Accrued interest 

Value added tax 

Charges 

Operation related to the loan 

Information on accounts, document processing and sending 

Direct debit fees 

Account maintenance fee, payment fee 

Total charges 

Total charges 

Charge for regular payment order 

Payments via ATM (automated teller machines) 

Payment via SMS (mobile bank) 

Balance 

Bank link payments 

35

Service – Exchange rates 


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 SGWException is sent if period requested is in future, past rates for cash exchange are requested 

or BIC of wrong bank is given. It is also possible that requested transaction type is not allowed 

for some of given currencies in which case SGWException error is also sent. 

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. 


 

 

HABAEE2X 

Transfer 

2007-06-27 

2007-07-01 

 

USD 

NOK 

EUR 

 

 


ExchangeRateRequest Root element of request document 1..1 

BIC AN (8) Code of bank that should respond (HABAEE2X for Estonian, 

1..1 

HABALV2X for Latvian and HABALT2X for Lithua- 

nian branch) 

ExchangeRateType A Transfer/Cash/Central 1..1 

StartDate D If not given, current banking day is used 0..1 

EndDate D If not given, current banking day is used 0..1 

Currencies 

Container element for currencies listing. If not given, all 0..1 

allowed currencies are listed in response 

Currencies/Currency A (3) 1..* 


 

 

 

HABAEE2X 

36

Transfer 

 

 

EUR 

15.62000 

15.67350 

 

 

EUR 

15.62000 

15.67350 

 

 

NOK 

1.96000 

1.99200 

 

 

NOK 

1.96000 

1.99200 

 

 

USD 

12.25400 

12.48850 

 

 

USD 

12.25400 

12.48850 

 

 

 

 


B4B/ExchangeRateResponse Container element for response 1..1 

BIC AN (8) Code of bank responding 1..1 

ExchangeRateType A Transfer/Cash/Central 1..1 

ExchangeRateInfo 

Container element for currencies listing 1..1 

in ExchangeRateResponse element. 

ExchangeRateInfo @ BaseCurrency A (3) Currency against what rates are given 1..1 

by bank is contained in BaseCurrency 

attribute. 

CurrencyInfo 

Container element for currency info in 0..* 

ExchangeRateInfo element 

CurrencyInfo @ Date D Date parameter of CurrencyInfo element. 

1..1 

CurrencyInfo/Currency A (3) 1..1 

CurrencyInfo/Buy N Bank buys at this rate 1..1 

CurrencyInfo/Sell N Bank sells at this rate 1..1 

37

Service – Currency exchange 


Customer can use this service to perform 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 

SGWException if any of rates offered by bank is not good enough to match them. SGW will also send 

error SGWException when there is not enough funds in sell currency on account or transactions are 

disabled in bank information system or given BIC does not belong to Swedbank. 

Response contains rates used and bank reference code if currency exchange is performed successfully. 


 

 

HABAEE2X 

EE922200221010214144 

 

USD 

2500 

11.50811 

 

 

EUR 

15.638 

 

 


BIC AN (8) BIC of Swedbank’s local branch (HABAEE2X for Estonian, 1..1 

HABALV2X for Latvian and HABALT2X for Lithuanian 

branch). 

IBAN AN (4 – 35) Account number where currency exchange is performed. 1..1 

Buy/Currency A (3) Currency that customer wishes to buy. 1..1 

Buy/Amount N Amount that customer wishes to buy. Has to be empty 0..1 

when sell amount is given, is calculated from sell 

amount then. 

Buy/Rate N When given, bank will perform exchange only if rate 0..1 

offered by bank is same or better than this. 

Sell/Currency A (3) Currency that customer wishes to sell. 1..1 

Sell/Amount N Amount that customer wishes to sell. Has to be empty 

when buy amount is given and is calculated from buy 

amount then. 

Sell/Rate N When given, bank will perform exchange only if rate 

offered by bank is same or better than this. 

0..1 

0..1 

38


 

 

 

HABAEE2X 

EE562200221008103199 

2007070200000195 

 

USD 

2500.00 

12.48850 

 

 

EUR 

1998.80 

15.62000 

 

 

 


B4B/CurrencyExchangeResponse Container element for response 1..1 

BIC AN (8) Code of bank responding 1..1 

IBAN AN (4 – 35) Account number where currency exchange 

1..1 

is performed. 

BankReference N (16) Bank reference for operation 1..1 

Buy/Currency A (3) Currency that customer bought 1..1 

Buy/Amount N Amount that customer bought 1..1 

Buy/Rate N 1..1 

Sell/Currency A (3) Currency that customer sold 1..1 

Sell/Amount N Amount that customer sold 1..1 

Sell/Rate N 1..1 

ExchangeRateType A Transfer 1..1 

ExchangeRateInfo 

Container element for currencies listing 

in ExchangeRateResponse element. 

1..1 

39

Service – Alert on transactions 


It is possible for a customer to get a notification about every transaction that is done 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 and exceeding 

the specified amount in that currency will send a notification. 

It is important to mention that alert message xml is only encrypted. We do not add bank signature 

there. 

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. 


There is no request – bank is generating these messages based on SGW agreement details. 


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

 

 

 

 

EE922200221010214144 

HABAEE2X 

 

 

 

 

 

 

 

 


B4B/Alert 1..1 

AccountInfo 

Container element inside 

1..1 

B4B/Alert 

AccountInfo/IBAN AN (4 – 35) Account number 1..1 

AccountInfo/BIC AN (8) Bank code of responding bank 1..1 

AccountInfo/BankName CDATA Name of responding bank 1..1 

Customer 


1..1 

B4B/Statement 

Customer/Name CDATA Name of account owner 1..1 

Customer/LegalID CDATA Registration number of account 1..1 

owner 

Currency 


1..1 

B4B/Alert 

Currency @ id A (3) Currency code is given in id 1..1 

attribute of Currency element 

Currency/Transactions 

Container element inside Alert 1..1 

/Currency 

Transactions/Transaction 

Container element inside Currency/Transactions 

0..* 

Transaction/TypeCode AN (2) 1..1 

Transaction/TransactionDate D 1..1 

Transaction/ReferenceDate D Document date 0..1 

Transaction/BankReference N (16) 1..1 

Transaction/DocumentNumber AN (1 – 30) Payment document number 0..1 

Transaction/ReferenceNumber AN (1 – 60) Reference to beneficiary 0..1 

Transaction/Description CDATA 1..1 

Transaction/Amount N 1..1 

Transaction/ReferenceToPayer AN (1 - 16) Lithuanian-specific 0..1 

Transaction/Counterparty 

Container element inside Transactions/Transaction 

1..1 

Counterparty/Name CDATA 1..1 

Counterparty/LegalID CDATA 1..1 

Counterparty/IBAN AN (4 – 35) 1..1 

Counterparty/BIC Latvian specific 1..1 

Counterparty/ReferenceToBeneficiary AN (1 - 16) Lithuanian-specific 0..1 

Transaction/OrderingParty 


Used for 

lithuanian payments. 

0..1 

41




Transaction/Assignee 


0..1 

Used for 

lithuanian payments. 




42

Service – Periodic statement 


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 will be generated. 

Every statement is encrypted for Client ERP certificate tied to given SGW agreement. 


There is no request – bank is generating these messages based on SGW agreement details. 


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 it is just like an account statement. If 

there were no transactions since previous statement’s last operation, an empty statement is returned. 

43

Service – Sending e-invoices 

Before using this service, it is important to know the terms and conditions of e-invoicing service! 

Separate E-invoice seller agreement must be signed. 


SGW allows customers to send e-invoices to their customers. This service differs from other SGW 

services a little because it requires two .xml documents in a DigiDoc 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 DigiDoc container, request file name has to end with 

“–request.xml”. That file is processed as SGW request .xml and validated against hgw.xsd. 


 

 

einvoices.xml 

EE 

12345 

 


Filename AN Name of the payload file in DigiDoc container. 1..1 

CountryCode A (2) Country code – can be omitted if customer has SGW 0..1 

agreement in only one country. EE/LV/LT otherwise. 

ContractId AN E-invoice seller agreement number. 1..1 


 

 

 

 

8 

2 

 

 

 

 

 

 

 

 

 

 

 

44


B4B/ImportResult 1..1 

Statistics 


1..1 

B4B/ImportResult 

Statistics/TotalCount N Number of e-invoices found in 1..1 

payload .xml 

Statistics/DefectiveCount N Number of e-invoices with errors. 1..1 

DefectiveInvoices 


1..1 

B4B/ImportResult 

Invoice 

Container element for each defective 

0..* 

e-invoice 

Invoice @ invoiceId AN ID for defective invoice 1..1 

Invoice/Errors Container inside Invoice 1..1 

Errors/Error 

Element for error code for each 

error 

Error @ id N Error code used by e-invoice processor. 

1..* 

1..1 

45

Service – E-Invoices for customer 


Customer can choose SGW as a channel to receive e-invoices meant for him/her (purchase 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). 


There is none – bank is generating these messages based on SGW agreement details. 


This depends on e-invoice processing. 

46

Service – Direct debit payer agreement management 

Before using this service it is important to know the terms and conditions of Direct Debit service! 

Separate direct debit beneficiary agreement must be signed. 


Updates in client’s information system regarding new Direct Debit agreements and/or closed existing 

Direct Debit agreements can be synchronized with the Bank using this service. 


 

 

 

EE 

12345 

 

 

 

1 

ADD 

 

3764444444 

EE082200001100701729 

Püvi 

 

1500.12 

EEK 

123000123 

654654 

456456 

 

12 

15 

 

 

2008-08-14 

2012-07-14 

 

 

 

2 

REMOVE 

 

3764444444 

EE082200001100701729 

1 

Püvi 

 

123000123 

 

 

 

47


Header/BeneficiaryAgreement N (1 – 16) Direct debit beneficiary agreement 1..1 

number. 

Header/CountryCode A (2) Country code – EE/LV/LT. 1..1 

Agreements/Agreement 

Container element for each agreement 0..* 

add/remove request 

Agreement/SequenceNumber N Agreement change id 1..1 

Agreement/Operation ADD/REMOVE Operation code 

Agreement/Payer 

Container for payer agreement owner 1..1 

data 

Payer/Name A (1 – 200) Payer name 1..1 

Payer/AccountNumber AN (1 – 35) Payer account number 1..1 

Payer/AgreementNumber N (1 – 16) Payer agreement number (used for 1..1 

REMOVE operation) 

Payer/RegistrationNumber A Payer registration number 1..1 

Agreement/Limit N Payer agreement debiting limit (used 0..1 

for ADD operation) 

Agreement/CurrencyCode A (3) Debiting limit currency (used for ADD 0..1 

operation in LV) 

Agreement/ReferenceNumber AN (1 – 20) Reference number for payer 1..1 

Agreement/Utility AN (0 – 25) Utility code (used in LV for ADD operation) 

0..1 

Agreement/Discount AN (0 – 25) Discount code (used in LV for ADD operation) 

0..1 

Agreement/DebitingPeriod 

Container for debiting period, used for 0..1 

ADD operation 

DebitingPeriod/From N First day of debiting period, cannot be a 1..1 

date in the past or in current month 

DebitingPeriod/To N Last day of debiting period 1..1 

Agreement/AgreementValid 

Container for agreement period, used 0..1 

for ADD operation. 

AgreementValid/From D First date of period 1..1 

AgreementValid/To D Last date of period 1..1 


 

 

 

 

EE 

12345 

 

 

2 

0 

1 

1 

 

 

48

 

 

 

 


B4B/DirectDebitImportResult 1..1 

Header/CountryCode A (2) Country code 1..1 


number. 

Statistics/TotalCount N Total number of agreements 

1..1 

processed by given processor 

Statistics/DefectiveCount N Number of agreements that failed 1..1 

validation 

Statistics/RemovedCount N Number of agreements that were 1..1 

removed 

Statistics/InsertedCount N Number of new agreements 1..1 


Container for every processed 0..* 

agreement 

Agreement @ recordId N Sequence number from request XML 1..1 

Agreement @ operation ADD/REMOVE Operation code from request XML 1..1 

Agreement @ agreementNumber N (1 – 16) Agreement number for created payer 

0..1 

agreement 

Agreement/Errors 

Container for errors for given agreement 

0..1 

change operation 

Errors/Error Element for every error 1..* 

Error @ id A Error code 1..1 

49

Service – Direct debit payer agreement changes 

Before using this service, it is important to know the terms and conditions of Direct Debit service! 



This service is used to notify the client about changed payer agreements for every direct debit beneficiary 

agreement. 


There is none – bank is generating these messages based on SGW agreement details. 


This is inverse of previous service. So XML sent by bank has same structure as customer’s request in 

that service. The bank does not expect any response to these messages and responds with XML validation 

error if one is sent. 

 

 

 

 

LV 

12345 

 

 

 

1 

REMOVE 

 

JANA SHEHU 

LV94HABA0551006169465 

111704 

100628-11490 

 

1000.00 

LVL 

 

1234567 

 

 

 

 

 

2007-05-01 

2010-05-01 

 

 

 

2 

ADD 

 

OMAR BALLA 

50

LV48HABA0551006169614 

119298 

111 

 

125.00 

LVL 

 

125869 

 

 

 

 

 

2012-04-01 

 

 

 

 

 

 

51



number. 



Container element for each agreement 0..* 

add/remove request 

Agreement/SequenceNumber N Agreement change id 1..1 

Agreement/Operation ADD/REMOVE Operation code 

Agreement/Payer 

Container for payer agreement owner 1..1 

data 

Payer/Name A (1 – 200) Payer name 1..1 

Payer/AccountNumber AN (1 – 35) Payer account number 1..1 

Payer/AgreementNumber N (1 – 16) Payer agreement number 1..1 

Payer/RegistrationNumber A Payer registration number 1..1 

Agreement/Limit N Payer agreement debiting limit (used 0..1 

for ADD operation) 

Agreement/CurrencyCode A (3) Debiting limit currency (used for ADD 0..1 

operation in LV) 

Agreement/ReferenceNumber AN (1 – 20) Reference number for payer 1..1 

Agreement/Utility AN (0 – 25) Utility code (used in LV for ADD operation) 

0..1 

Agreement/Discount AN (0 – 25) Discount code (used in LV for ADD operation) 

0..1 

Agreement/DebitingPeriod 

Container for debiting period, used for 0..1 

ADD operation 

DebitingPeriod/From N First day of debiting period 1..1 

DebitingPeriod/To N Last day of debiting period 1..1 

Agreement/AgreementValid 

Container for agreement period, used 0..1 

for ADD operation. 

AgreementValid/From D First date of period 1..1 

AgreementValid/To D Last date of period 1..1 

52

Service – Direct debit payment requests 

Before using this service it is important to know the terms and conditions of Direct Debit service! 



This service allows client to send payment requests to one or more payers with valid direct debit 

payer agreement. Although direct debit operation exists in all Baltic countries, local implementations 

differ – so our XML has different requirements for each country. 


 

 

 

12345 

EE 

 

 

 

Payment description 

 

Customer name 

54321 

 

2008-08-12 

341.12 

123123 

 

 

 



number. 


Payments/Payment 

Container element for each payment 0..* 

request 

Payment/Payer Container element for payer data 1..1 

Payer/Name AN (1 – 200) Name of the payer. Required in EE and 0..1 

LV. 

Payer/AccountNumber AN (1 – 35) Account number of the payer. Required 0..1 

in LT. 

Payer/Agreement N (1 – 16) Direct debit payer agreement number. 0..1 

Required in EE and LT. 

Payment/PaymentDate D Date of the payment. Required in EE and 0..1 

LV. 

Payment/CurrencyCode A (3) Currency of payment. Required in LV. EE 0..1 

and LT always use local currency. 

Payment/Amount N Amount of payment. 1..1 

53

Payment/Description AN (0 – 75) Description of payment 0..1 

Payment/ReferenceNumber AN (0 – 20) Reference number of payer 1..1 

Payment/Utility AN (0 – 25) Utility code. Required in LV. 0..1 

Payment/Discount AN (0 – 25) Discount code. Required in LV. 0..1 


Direct debit payment requests are processed similarly to payments – initially the request is split into 

blocks of 500 payments (this number could change in time). After that SGW checks payer agreement 

data (if reference number matches given payer, payer name is correct and so on) and stores valid 

requests. 

Due to two-tier processing logic SGW responds to request with at least two messages. If there were 

more payment requests than the maximum block size of 500, then one response from SGW contains 

statistics about all of them and second message is sent for each block that has been processed. 

Structure for response file is still the same: 

 

 

 

 

EE 

12345 

 

 

1 

0 

 

 

 

 

 

 

 

 

 

EE 

12345 

 

 

1 

1 

 

 

 

 

 

 

 

 

 

 

54


B4B/DirectDebitPaymentsImportResult 1..1 

DirectDebitImportResult @ from A (2 - 3) Processor id – HGW/EE/LV/LT 1..1 

Header/CountryCode A (2) Country code 1..1 

Header/BeneficiaryAgreement N (1 – 16) Direct debit beneficiary agreement 

1..1 

number. 

Statistics/TotalCount N Total number of payments 1..1 

processed by given processor 

Statistics/DefectiveCount N Number of payments that failed 1..1 

validation by given processor. 

DefectivePayments 

Container for defective payment 1..1 

listing 

DefectivePayments/Payment Container for payment data 0..* 

Payment @ recordId N Payment location in request file. 1..1 

Payment/Errors Container for payment errors 1..1 

Errors/Error Element for error code 1..* 

Error @ id A Validation error code 1..1 

55

Service – POS report delivery 


This service is used as delivery channel for POS reports from the bank to the client. 


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 1: Transaction based report 

 

- 

- 

93201456 

Luuk OÜ 

LIIVALAIA 10 

Tallinn 

15040 

EE 

- 

9297565 

Luuk-LibakaupmeesI 

LIIVALAIA 8 

Tallinn 

15040 

221014217590 

ESTONIA 

- 

11060344515 

- 

041624 

2012-04-16 

2012-04-16 

2012-04-16 

2012-04-17 

- 

MasterCard 

Credit 

EU 

- 

Term 

2764 

000060 

2012-04-13 

11:40:20 

210854993993 

56

EUR 

3.95 

EUR 

3.95 

0.05 

3.90 

 

- 

Term 

3404 

000062 

2012-04-13 

14:32:05 

210854993994 

414364 

EUR 

4.75 

EUR 

4.75 

0.05 

4.70 

 

- 

Term 

- 

2 

EUR 

8.70 

 

2 

EUR 

8.70 

0.10 

8.60 

 

 

- 

 

Debit 

Swedbank 

+ 

+ 

+ 

+ 

+ 

 

- 

Term 

- 

6 

EUR 

23.43 

 

6 

EUR 

23.43 

0.25 

23.18 

 

57

- 

Term 

- 

6 

EUR 

23.43 

 

6 

EUR 

23.43 

0.25 

23.18 

 

 

- 

Term 

- 

6 

EUR 

23.43 

 

6 

EUR 

23.43 

0.25 

23.18 

 

 

- 

Term 

- 

6 

EUR 

23.43 

 

6 

EUR 

23.43 

0.25 

23.18 

 

 

 

Example 2: Batch based report 

 

- 

- 

93201456 

Luuk OÜ 

LIIVALAIA 10 

Tallinn 

15040 

EE 

58

- 

9297565 

Luuk-Libakaupmees 

LIIVALAIA 8 

Tallinn 

15040 

221014217590 

ESTONIA 

- 

11060344515 

- 

040209 

2012-04-02 

2012-04-02 

2012-04-02 

2012-04-03 

- 

VISA 

Debit 

EU 

- 

Term 

- 

1 

EUR 

1.00 

 

1 

EUR 

1.00 

0.01 

0.99 

 

 

- 

Term 

- 

1 

EUR 

1.00 

 

1 

EUR 

1.00 

0.01 

0.99 

 

 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

59

+ 

+ 

- 

Term 

- 

83 

EUR 

328.05 

 

83 

EUR 

328.05 

3.46 

324.59 

 

 

- 

Term 

- 

83 

EUR 

328.05 

 

83 

EUR 

328.05 

3.46 

324.59 

 

 

- 

Term 

- 

83 

EUR 

328.05 

 

83 

EUR 

328.05 

3.46 

324.59 

 

 

 

60

Swedbank Gateway Service Description

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?