Documentation

Borgun, all rights reserved. 2017 ©

About B-Gateway

B-Gateway is a code name for a web service that allows a merchant to obtain authorizations for credit card transactions and to submit transactions for clearing and settlement.

Key features

B-Gateway’s key features enable the user to do the following:

Get authorizations – allows the user to either make a normal purchase transaction or to pre-authorize it.

The difference is:

If a transaction is pre-authorized, the given amount is reserved from the cardholder’s account. The amount will not be charged to the cardholder until a financial transaction is submitted. The authorization code needs to be stored by the merchant and later used to send in the financial transaction. Financial transactions are submitted by calling getAuthorization with the AuthCode from a previous pre-authorized transaction.

With the normal purchase transaction the cardholders account is charged for the given amount. If the transaction was pre-authorized then the transaction must include the authorization code received from that transaction.

This feature also allows the user to make a refund transaction if he wants to refund an amount to the cardholder’s account.

Cancel authorizations – allows the user to cancel previously authorized transactions. Authorizations can be cancelled if the batch they belong to is still open. If it is closed then a refund transaction must be used.

Create new batches – allows the user to create a new batch. By doing so the user closes the currently open batch and opens a new one.

Get batch authorizations – allows the user to authorize many transactions as one batch.

Get processing results – allows the user to get results from previous batch job.

Get transaction lists – allows the user to get a transaction list from the authorization service listing, on either batch or transaction level details on transactions processed through the service.

Send detail data – allows the user to supply detailed invoice after the financial transaction has been processed.

Introduction to batches

A batch is a unit that the acquirer uses to settle with the merchant. It is a collection of credit card transactions charged over a period of time, usually one day.

Each batch is identified by a batch number and this batch number must be unique per terminal within one year. The batch number can either be controlled by the merchant or the authorization services. This will be explained later.

How does B-Gateway work

B-Gateway will expose the authorization services with the use of web services. The web services run securely over HTTPS.

All web services provided by B-Gateway will be password protected. The connecting merchant has to supply username and password each time the merchant calls a B-Gateway web service.

Once the merchant has connected to the web service he will be able to access the features mentioned above. When using these features the merchant must send all necessary information on XML format. This will be explained later. This XML information will then be sent through the web service and a response, also on XML format, will be given.

B-Gateway


Model 1 – This diagram shows an example of B-Gateway’s process

Data Storage and Manipulation

The security of cardholder account data has become one of the biggest issues facing the payment card industry. Visa and MasterCard have therefore created the Payment Card Industry Data Security Standard (PCI DSS) – a set of industry-wide requirements and processes, that are supported by all international payment card systems.

PCI DSS is intended for any organization that stores, transmits or processes cardholder account and transaction data – merchants, acquiringbanks and related service providers.

The PCI standard is available at https://www.pcisecuritystandards.org Please download and review the standard.

While all merchants are required to comply with thePayment Card Industry Data Security Standard, merchants that store, process or transmitcard account data may also be required to validate compliance with their acquirer. Please note that for a merchant to be considered compliant, any Service Providers that store, process or transmit card account data on behalf of the merchant must also be compliant.

Data types Data types

Field Form
A Alphabetic
N Numeric
AN Alphanumeric
Z ISO 7811 and ISO 7813 track 2 and track 3 data format

Field Length
10 Indicates length=10
LL..19 Indicates max length of 19
..17 Variable length up to 17 characters

Field Code
M Mandatory
C Conditional
O Optional

Amounts
All amounts are represented with two digits after the decimal and an implied decimal point. Icelandic Krona is therefore represented in aurar. Dollars are in cents etc. For instance 100 USD is in TrAmount as “10000”.

Getting authorizations

Normal purchase transaction

This element is referred as TransType 1 in the XML sheet. If you wish to make a normal purchase transaction you can either insert a variable in the AuthCode in the XML sheet or leave the field empty.

The difference is that if the AuthCode is empty B-Gateway will request authorization from the issuer and, if successful, B-Gateway will storethe financial transaction in its database and later submit the financial transaction to the acquirer automatically.

OR

If the transaction has already been authorized by the pre-authorizing element or by other channels the AuthCode will contain the auth code that was received during the preauthorization process. This is sometimes referred to as submitting financial transactions. In this case B-Gateway will store the financial transaction in its database and not request authorization from the issuer to ensure that the card account does not get reserved twice. B-Gateway will then later submit the transaction tothe acquirer automatically.

In either case the transaction number and batch number are always returned from the web service. If Transaction and Batch variables are notset in input requests they are created and returned in the response.

Refund

This element is referred as TransType 3 in the XML sheet. This transaction type is used when a merchant wants to refund an amount to a customer. If the refund is successful the response to the merchant contains the AuthCode of the reversal, as well as Transaction and Batch numbers. In other case the response contains an error code.

Partial Reversal

This element is referred as TransType 4 in the XML sheet. This transaction type lowers the amount on a currently existing sale and advices the issuer to change the cardholder’s withdrawal limit by the same amount. The transaction type can only be used on a sale created on the same day and therefore in an open batch. The message must contain the original amount, and the new amount.
If the partial reversal is successful the response to the merchant contains the AuthCode of the reversal, as well as Transaction and Batch numbers. In other case the response contains an error code.

Pre-authorizations

This element is referred as TransType 5 in the XML sheet. This transaction type is used when the merchant wants to reserve an amount from a customer’s credit card. An Authorization Request is then sent to the acquirer. If the request was authorized the transaction is added to a system database containing the new AuthCode. Transaction and batch numbers are not assigned to the transaction as the transaction is only a pre-authorization request. The response sent to the merchant therefore only contains AuthCode, not Transaction and Batch.

Recurring Zero amount authorization

The Payment Gateway does support zero amount to be sent to verify cards for MasterCard and VISA. The only requirement is that the authorization must be a pre-authorization. This is most often used in recurring sales.

Dynamic Descriptors

DD information is sent by adding the following parameters to the authorization message.
MerchantName        AN 1..22
MerchantHome        AN 1..20
MerchantCity           AN 1..13
MerchantZipCode    AN 1..10
MerchantCountry     A2, two letter country code
MerchantName must always have value and the proper way is to fill in all the parameters. If a parameter is missing then the gateway will fill out the rest with pre-configured values which might not properly represent the merchant. DD works with all authorization requests except cancelAuthorization. For pre-authorization (Transtype 5) MerchantName, MerchantCity and MerchantContry will be sent (limited by card schema regulation), for financial authorization (Transtype 1, 3, 4) all parameters are sent, that also applies when pre-authorizations arecaptured with sale (Transtype 1). For pre-authorization with capture it is recommended that the pre-authorization also contains the DD since it is a requirement from VISA, MasterCard uses the financial record.

The merchant contract numbers have to be specifically configured through business channels to allow use dynamic descriptors, if not then these parameters will be ignored.

Name, ZipCode and City can contain AlphaNumeric letters along with common characters such as *, +, - _ . While no characters are explicitly forbidden then the reality is that several issuer dislike uses of characters such as &, <, >, ?, /,. \ and they should be avoided.

All parameters must be completed and contain correct data if dynamic descriptors are to work
MasterCard has a restriction that requires home, zipcode and country to referr to an actual address.fs

See example below.

Getting authorizations - XML explanations

Table GA.1 – Field explanations for a sent XML

Field Length Form Type Explanation
Version 4 AN Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor 7 N Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantID ..8 AN Mandatory An Id in B-Gateway of the merchant requesting services
TerminalID ..8 Optional A terminal id in B-Gateway for the merchant requesting services. Must be set if default terminal is not defined for merchant.
TransType 1 N Mandatory 1 = Normal purchase transaction
3 = Refund
4 = Partial Reversal
5 = Pre-Authorize
TrAmount ..12 Mandatory Amount, in general it includes two decimal points, i.e. 100 USD is 10000.
Currently JPY is the only exception, it contains no decimal points.
NewAmount ..12 Mandatory Only used by transtype 4. Contains the new amount to override the original sale amount.
TrCurrency 3 N Mandatory Transaction currency ISO 4217

352 => ISK
978 => EUR
DateAndTime 12 N Mandatory YYMMDDhhmmss. When repeated use original date and time
PAN LL..19 N Conditional Card number – Used if a card number is entered manually. See also Track1/Track2. Card number can be a virtual card (see function getVirtualCard).
If TransType is refund then PAN can be empty, PAN from a transaction of TransType=1 with the same DateAndTime + RRN will be used.
ExpDate 4 N Conditional Expiration date – YYMM not used if Track1/Track2
Track1 LL..6 AN Conditional Mandatory if magnetic stripe read and not Track2
Track2 LL--37 Z Conditional Mandatory if magnetic stripe read
RRN 12 AN Mandatory Retrieval Reference Number – Reference number for transaction. Must be exactly 12 characters. Recommended format is a fixed value followed by a sequence, for example ACME00012345. The last six letters must contain a numeric value.
AuthCode ..6 AN Conditional Authorization code of a previous preauthorized transaction. Include this code to use the previously gotten authorization code
CVC2 3 N Optional Used in cardholder not present situations such as internet sales. Code is printed on the back of the cardholder´s card
SecurityLevelInd 1 AN Optional Security Level Indicator – Used with Secure Code to indicate the security level used in electronic transactions
This property is mandatory in electronic commerce and is used to identify the level of security used when doing the transaction.
0 = UCAF not supported by merchant
1 = UCAF supported by merchant but not provided by issuer
2 = UCAF is present

Mapping from MPI is
MPI(1) 2
MPI(2,3,4) 1
MPI(5,6,7,8) 1
UCAF 32 AN Conditional Universal Cardholder Authentication Field – Used with Secure Code
CAVV 28 AN Conditional Verified by Visa, Base64 encoded cardholder authentication verification value, f.ex AAACCRSQJ4lShoBncZAnAAAAAAA=
XID 28 AN Conditional Verified by Visa. The unique transaction action id identifier encode by Base64.
MerchantName 1..22 AN Conditional Name of merchant.
MerchantHome 1..20 AN Conditional Merchant home
MerchantCity 1..13 AN Conditional City of merchant or contact information (f.ex. The Shop, +123456789)
MerchantZipCode 1..10 AN Conditional ZipCode of merchant shop
MerchantCountry 2 A Conditional Two letter country code in uppercase (f.ex. GB, US)

Refund and Partial Refunds must refer to the original transaction by having exactly the same DateAndTime and RRN as the original authorization.

Table GA.2 – Field explanations for a received XML

Field Type Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantID Mandatory An Id in B-Gateway of the merchant requesting services
TerminalID Optional A terminal id in B-Gateway for the merchant requesting services.
TransType Echo 1 = Normal purchase transaction
3 = Refund
5 = Pre-Authorize
TrAmount Echo Amount, note for example 100 USD is 10000 because the amount is represented in cents
TrCurrency Echo Transaction currency ISO 4217

352 => ISK
978 => EUR
DateAndTime Echo YYMMDDhhmmss. When repeated use original date and time
PAN Conditional Card number – Used if a card number is entered manually. See also Track1/Track2
RRN Mandatory Retrieval Reference Number – Reference number for transaction.
Transaction Conditional Unique number of the transaction within batch.
Batch Conditional Unique number of the batch in use for this terminal.
CVCResult Conditional If available indicates how the issuer processed theCVC.
Values:
M = Valid CVC
N = Invalid CVC
P = CVC not processed (issuer unavailable)
CardAccId Mandatory Card Acceptor Identification Code

Code Identifying the card acceptor. This Id is issued by the acquirer
CardAccTerminal Optional Card Acceptor Terminal Identification Code

Code Identifying the terminal the card acceptor is using
CardAccName Mandatory Card Acceptor Name and Location

Name\Street\City\Postal Code\Region (two digit US state code or three digit ISO alpha country code if outside US)\Country Code as in ISO3166
AuthCode Mandatory Authorization code if the transaction was accepted
ActionCode Mandatory Reason code for response
StoreTerminal Mandatory A numeric code that identifies the store and terminal within each merchant chain.
CardType Mandatory If available this will indicate the name of the card type
Message Optional Contains a text message if form error occurs

Getting authorizations - XML examples

GAXML.1 – An example of authorization request

<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>2</MerchantID>
<TerminalID>1</TerminalID>
<TransType>5</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>0705</ExpDate>
<RRN>TESTING00001</RRN>
<CVC2>123</CVC2>
</getAuthorization>

GAXML.2 – An example of an authorization capture

<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>2</MerchantID>
<TerminalID>1</TerminalID>
<TransType>1</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<RRN>TESTING00001</RRN>
<AuthCode>060215012345</ AuthCode >
</getAuthorization>

GAXML.3 – An example of refund of sale

<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>1</MerchantID>
<TerminalID>1</TerminalID>
<TransType>3</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<RRN>TESTING00001</RRN>
</getAuthorization>

GAXML.4 – An example of partial reversal of sale

<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>1</MerchantID>
<TerminalID>1</TerminalID>
<TransType>4</TransType>
<TrAmount>100000</TrAmount>
<NewAmount>30000</NewAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<RRN>TESTING00001</RRN>
</getAuthorization>

GAXML.1 – An example of authorization request with Dynamic Descriptor

<?xml version='1.0' encoding="utf-8"?>
<getAuthorization>
<Version>1000</Version>
<Processor>2</Processor>
<MerchantID>2</MerchantID>
<TerminalID>1</TerminalID>
<TransType>1</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>0705</ExpDate>
<RRN>TESTING00001</RRN>
<CVC2>123</CVC2>
<MerchantName>The Shop</MerchantName>
<MerchantHome>The Road 123</MerchantHome>
<MerchantCity>+123456789</MerchantCity>
<MerchantZipCode>AL123</MerchantZipCode>
<MerchantCountry>UK</MerchantCountry>
</getAuthorization>

Cancelling authorizations

This operation cancels a previously authorized transaction. The previously authorized transaction is found by searching for the AuthCode of the transaction. If no AuthCode is present in a request, the most recent transaction that matches the criteria (i.e. the rest of the input request) is cancelled. Transactions authorized with TransType=1 can only be cancelled while the batch they belong to is still open. Transactions authorized with TransType=5 can always be cancelled as they don’t belong to any batches.

The card number and amount must be the same as in the original transaction. In the event of an error, such as timeout in communications, the RRN number of the transaction in the error must be included in the cancelling process.

Authorizations can be cancelled if the batch they belong to is still open. If it is closed then a refund transaction must be used. Pre-Authorize transaction can be cancelled after the batches are closed since pre-authorized transactions do not belong to batches.

Cancelling authorizations - XML explanations

Table CA.1 – Field explanations for a sent XML

Field Length Form Type Explanation
Version 4 AN Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor 7 N Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantID ..8 AN Mandatory An Id in B-Gateway of the merchant requesting services
TerminalID ..8 AN Optional A terminal id in B-Gateway for the merchant requesting sevices. Must be set if default terminal is not defined for merchant.
TransType 1 N Mandatory Same as the original transaction
TrAmount ..12 N Mandatory Same as the original transaction
TrCurrency 3 N Mandatory Same as the original transaction
DateAndTime 12 N Mandatory YYMMDDhhmmss. Same as the original transaction
PAN LL..19 N Conditional Card number – Same as the original transaction. If PAN is empty then DateAndTime + RRN will be used to find PAN in original transaction.
Track1 LL..76 AN Conditional Same as the original transaction
Track2 LL..37 Z Conditional Same as the original transaction
RRN 12 AN Mandatory Retrieval Reference Number – Reference number for transaction. Same as the original transaction
AuthCode ..6 AN Conditional Same as the original transaction

Table CA.2 – Field explanations for a received XML

Field Type Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantID Mandatory An Id in B-Gateway of the merchant requesting services
TerminalID Optional A terminal id in B-Gateway for the merchant requesting sevices. Must be set if default terminal is not defined for merchant.
TransType Echo Same as the original transaction
TrAmount Echo Same as the original transaction
TrCurrency Echo Same as the original transaction
DateAndTime Echo YYMMDDhhmmss. Same as the original transaction
PAN Conditional Card number – Same as the original transaction
RRN Mandatory Retrieval Reference Number – Reference number for transaction. Same as the original transaction
Transaction Conditional Number of the transaction. Same as the original transaction
Batch Conditional Number of the batch in use. Same as the original transaction
CardAccId Mandatory Code Identifying the card acceptor. Same as the original transaction
CardAccTerminal Mandatory Same as the original transaction
CardAccName Mandatory Card Acceptor Name and Location
Name\Street\City\Postal Code\Region (two digit US state code or three digit ISO alpha country code if outside US)\Country Code as in ISO3166
AuthCode Mandatory Authorization code if the transaction was accepted
ActionCode Mandatory Reason code for response
StoreTerminal Mandatory A numeric code that identifies the store and terminal within each merchant chain.
CardType Mandatory If available this will indicate the name of the card type
Message Optional A message in comprehension with the Action Code

Cancelling authorizations – XML examples

CAXML.1 – An example of sent XML

<?xml version='1.0' encoding="utf-8"?>
<cancelAuthorization>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantID>2</MerchantID>
<TerminalId>1</TerminalId>
<TransType>1</TransType>
<TrAmount>000000100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>1405</ExpDate>
<RRN>060215012345</RRN>
<AuthCode>809285</AuthCode>
</cancelAuthorization>

Virtual card numbers

Credit card numbers need not be sent into getAuthorization, instead virtual card numbers can be used. This enhances security as it eliminates the need to store sensetive credit card information in local data sources.

Virtual card numbers - XML explanations

Table VA.1 – Field explanations for a sent XML

Field Length Form Type Explanation
MerchantContractNumber 7 AN Mandatory Contract number issued by Borgun.
PAN 16 N Mandatory Card number

Table VA.2 – Field explanations for a received XML

Field Type Explanation
VirtualCard Mandatory Card number that can be used as reference to the real card number in authorization.

Cancelling authorizations – XML examples

VCXML.1 – An example of sent XML

<?xml version='1.0' encoding="utf-8"?>
<getVirtualCard>
<MerchantContractNumber>7891234</MerchantContractNumber>
<PAN>5555544433331111</PAN>
</ getVirtualCard >

Creating new batches

New batch closes the currently open batch and opensa new one.

If the currently open batch has no transactions associated with it, the batch will be considered as being the new batch, thus it will not be closed nor will a new batch be opened.

Batch numbers controlled by the Authorization Services

This is the preferred way of handling batches. The merchant sends in authorization requests to the Authorization Services. The Authorization Services will add the batch and transaction numbers to the transaction as needed. When the merchant wants to close the batch the merchant can use the NewBatch function orthe Authorization Services can take care of this daily at predefined time.

Batch numbers controlled by the merchant

The merchant adds the batch and transaction numbers to the authorization request. In order to start a new batch the merchant simply increments the batch number and starts the transaction number back at number 1. The batch number must be unique for particular terminal within the year and in ascending sequence.Transaction numbers must be unique within a batch number.

Creating new batches – XML explanations

Table CNB.1 – Field explanations for a sent XML

Field Length Form Type Explanation
Version 4 AN Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor 7 N Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantId ..8 AN Mandatory An Id in B-Gateway of the merchant requesting services
TerminalId ..8 AN Optional If not set then the batch for the default terminal will be closed. If set then the insent terminal will be close.
DateAndTime 12 AN Optional YYMMDDhhmmss. Only used for documentation purposes

Table CNB.2 – Field explanations for a received XML

Field Type Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantId Mandatory An Id in B-Gateway of the merchant requesting services
TerminalId Optional A terminal id in B-Gateway for the merchant requesting sevices
DateAndTime Echo YYMMDDhhmmss. Same as the request
NewBatch Conditional Number of the new batch in use
OldBatch Conditional Number of the batch just closed
CardAccTerminal Optional Terminal id
ActionCode Mandatory Reason code for response
StoreTerminal Mandatory If available this will indicate the name of the card type

Creating new batches – XML examples

CNBXML.1 – An example of a sent XML

<?xml version='1.0' encoding="utf-8"?>
<newBatch>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantId>2</MerchantId>
<TerminalId>1</TerminalId>
<DateAndTime>060216103700</DateAndTime>
</newBatch>

Getting transaction lists

Client applications can request a transaction list from the authorization service listing on either batch or transaction level details about transactions processed through the service.

It is possible to specify a batch number in the request to get all transactions that belong to that given batch. It is also possible to get a listof transactions for a given time period.

Getting transaction lists – XML explanations

Table TL.1 – Field explanations for a sent XML

Field Type Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantId Mandatory An Id in B-Gateway of the merchant requesting services
TerminalId Optional A terminal id in B-Gateway for the merchant requesting services. Must be set if default terminal is not defined for merchant.
BatchNumber Conditional Batch number. If the BatchNumber is omitted, the response will only include batchnumbers processed during the given time period. Otherwise a list of transactions for the given batchnumber is returned.
FromDate Conditional Format:YYYYMMDD. Mandatory field if BatchNumber is empty.
ToDate Conditional Format:YYYYMMDD. Only used if BatchNumber is empty. If this parameter is not set, current date will be used as ToDate.
RRN Conditional Searches all batches for transactions with the given RRN

Tables TL.2 and TL.3 – Field explanations for a received XML

Field Type Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantID Mandatory An Id in B-Gateway of the merchant requesting services
ActionCode Mandatory Reason code for response

Explanations for each transaction within the batch

Field Type Explanation
TransType Mandatory 1 = Normal purchase transaction
3 = Refund
5 = Pre-Authorize
TransactionNumber Mandatory Number of the transaction
BatchNumber Mandatory Number of the requested batch
TransactionDate Mandatory YYMMDDhhmmss. Date and time of the transaction
PAN Mandatory Card number – Used if a card number is entered manually
RRN Mandatory Retrieval Reference Number –Reference number for transaction
ActionCode Conditional Reason code for response
AuthorizationCode Mandatory Authorization code of a previous pre-authorized transaction. Include this code to use the previously gotten authorization code
TrAmount Mandatory Amount, note for example 100 USD is 10000 because the amount is represented in cents
TrCurrency Mandatory Transaction currency ISO 4217

352 => ISK
978 => EUR
CardType Conditional If available this will indicate the name of the card type
Voided Mandatory Voided can have values T (True) and V (Void transactions). A transaction that is voided will get Voided as T, the voiding transaction (cancelAuthorization) will get voided as V. The void status can only be created by cancelAuthorization().
Status Mandatory Status on transaction can have the following values
1: Sale initial status
2: Sale successful
3: Sale failed
4: Refund initial status
5: Refund successful
6: Refund failed
7: Pre-authorization initial status 8: Pre-authorization successful
9: Pre-authorization failed
10: Reversal initial status
11: Reversal successful
12: Reversal failed
14: Financial record sent

A successful transaction will be in state 2 (or 6 for refund) and end up in state 14 when the financial record has been sent to the card schema. Other statuses are more for information purposes, i.e.
have no financial impact.
TerminalNr Id of terminal being used during authorization
Credit Conditional Contains 1 if OCT/CFT transaction

Getting transaction lists – XML examples

TLXML.1 – An example of a sent XML

<?xml version="1.0" encoding="utf-8"?>
<TransactionListRequest>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantId>2</MerchantId>
<BatchNumber>3</BatchNumber>
</TransactionListRequest>

Getting Disputed Transactions

Client applications can request a list of disputed transactions. All authorization transactions have a unique numbernamed Acquiring Reference, for each transaction that has a chargeback there will be a list (1 or more) of chargeback records detailing the history of the chargeback. They can be fetched by using the Acquiring Reference.

Dispute types returned are as follows

  • Chargeback
    • Issuer to acquirer. Chargeback of the original transaction, short code is ‘C’. If the chargeback is partial, that is only partial amount of the original transaction is used, then the short code is ‘PC’
  • Retrieval Request / Information Retrieval
    • Issuer to acquirer. Request for information regarding the original transaction, non financial impact, short code is ‘RR’.
  • Chargeback Reversal
    • Issuer to acquirer. Reverses the chargeback, short code is ‘CR’.
  • Second Presentment / Re-Presentment
    • Acquirer to Issuer. Negates the chargeback by sending the financial transaction again, initiated by merchant, short code is ‘SP’.
    • If the re-presentment is partial, that is only partial amount of the original transaction is used, then the short code is ‘PSP’
  • Second Chargeback / Arbitration Chargeback
    • Issuer to acquirer. Chargeback in response to the re-presentment, short code is ‘AC’. If the arbitration chargeback is partial, that is only partial amount of the original transaction is used, then the short code is ‘PAC’
  • Second Presentment Reversal
    • Acquirer to Issuer. Negates a Second Presentment /Re-Presentment, can be caused by second presentment being denied by schemaor manual mistakes. Rarely used. short code is ‘SPR’.

The chargeback list describes the communication between acquirer and issuer during dispute, a path for a long running dispute might becreating the following four records

  1. Retrieval Request / Information Retrieval: Issuer needs more information to determine if the original transaction should be accepted or a chargeback sent.
  2. Chargeback: Issuer requests a chargeback from acquirer. Issuer can always back out of the chargeback by doing a chargeback reversal.
  3. Second Presentment / Re-Presentment: Acquirer does not accept the chargeback and resends the transaction.
  4. Second Presentment Reversal: Acquirer negates a second presentment.
  5. Issuer might then end with Second Chargeback(Issuerre-request for chargeback)

A rare occurrence that still happens once in a while is double registration of chargeback.

  1. Chargeback: Issuer requests a chargeback from acquirer
  2. Chargeback: A second chargeback from issuer to acquirer
  3. Chargeback Reversal: Issuer reverses one chargeback for acquirer does a representment.

Getting disputed transactions

Table DT.1 – Parameters for getDisputedTransactions ()

Field Type Explanation
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantContractNumber Mandatory Contract number issued by Borgun.
DateFrom Mandatory Returns all disputed transactions from date DateFrom. Date format YYYYMMDD.
DateTo Mandatory Returns all disputed transactions up to and including date DateFrom. Date format YYYYMMDD.

Table DT.2 – Field explanations for the status record contained in received XML

Field Type Explanation
ResultCode Mandatory Can have values 0 = “Success”, 10 = “Information” (f.ex. No Data Found), 30 = “Error”
ResultText Mandatory Text description for ResultCode, f.ex. “Success”, “Error”, “No Data Found”
ErrorMessage Mandatory Detailed error description
MessageId Mandatory Error description code of ErrorMessage if applicable
ReferenceValue Mandatory Id of record within list where error occurred. Onlyreturned if applicable
StackTrace Mandatory Stacktrace of error if applicable

Table DT.3 – Field explanations for a received XML

Field Type Explanation
MerchantNumber Mandatory Merchant contract number
ProcessingTime Mandatory Date and time of record processing at Borgun, yyyy-mmddThh:mm:ss
Date Mandatory Date of record creation, yyyy-mm-dd
Brand Mandatory Card brand type
Type Mandatory See table above
Amount Mandatory Current amount
Currency Mandatory Current currency
ReasonCode Mandatory Code describing reason for dispute
ReasonText Mandatory Text describing reason for dispute
AcquiringReferenceData Mandatory Acquirer reference
BatchDate Mandatory Batch date of transaction, yyyy-mm-dd
TerminalId Mandatory Transaction terminal id
RRN Mandatory Retrieval Reference Number – Reference number for transaction
CardNumber Mandatory Masked cardnumber in transaction
OriginalAmount Mandatory Amount in transaction
OriginalCurrency Mandatory Currency of transaction
OriginalDate Mandatory Date of transaction, yyyy-mm-dd
AuthorizationCode Mandatory Tranasction authorization number

Getting disputed transaction list – XML examples

DTXML.1 – An example of a sent and received received XML

<?xml version="1.0" encoding="utf-8"?>
<getDisputedTransactions>
<Processor>21</Processor>
<MerchantContractNumber>9275444</MerchantContractNumber>
<DateFrom>20101021</DateFrom>
<DateTo>20111025</DateTo>
</getDisputedTransactions>

<?xml version="1.0"?>
<DisputedTransactionResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Success</ResultText>
</Status>
<DisputedTransactionList>
<DisputedTransaction>
<MerchantNumber>9275444</MerchantNumber>
<ProcessingTime>2008-09-18T00:00:00</ProcessingTime>
<Date>2008-09-18</Date>
<Brand>MC</Brand>
<Type>C</Type>
<Amount>2000000</Amount>
<Currency>352</Currency>
<ReasonCode>4809</ReasonCode>
<ReasonText>TRANSACTION NOT RECONCILED</ReasonText>
<AcquiringReferenceData>5414838259002000123123</AcquiringReferenceData>
<BatchDate>2008-06-23</BatchDate>
<TerminalId>00010002</TerminalId>
<RRN>111222</RRN>
<CardNumber>002359*********3123</CardNumber>
<OriginalAmount>20000</OriginalAmount>
<OriginalCurrency>352</OriginalCurrency>
<OriginalDate>2008-06-21</OriginalDate>
<AuthorizationCode>0</AuthorizationCode>
</DisputedTransaction>
</DisputedTransactionList>
</DisputedTransactionResponse>

Getting Fraud Transactions

Client applications can request a list of fraud transactions.

Getting fraud transactions

Table FT.1 – Parameters for getFraudTransactions ()

Field Type Explanation
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantContractNumber Mandatory Contract number issued by Borgun.
DateFrom Mandatory Returns all fraud transactions from date DateFrom. Date format YYYYMMDD.
DateTo Mandatory Returns all disputed transactions up to and including date DateFrom. Date format YYYYMMDD.

Table FT.2 – Field explanations for the status record contained in received XML

Field Type Explanation
ResultCode Mandatory Can have values 0 = “Success”, 10 = “Information” (f.ex. No Data Found), 30 = “Error”
ResultText Mandatory Text description for ResultCode, f.ex. “Success”, “Error”, “No Data Found”
ErrorMessage Mandatory Detailed error description
MessageId Mandatory Error description code of ErrorMessage if applicable
ReferenceValue Mandatory Id of record within list where error occurred. Only returned if applicable
StackTrace Mandatory Stacktrace of error if applicable

Table DT.3 – Field explanations for a received XML

Field Type Explanation
MerchantNumber Mandatory Merchant contract number
ProcessingTime Mandatory Date and time of record processing at Borgun, yyyymm-ddThh:mm:ss
Date Mandatory Date of record creation, yyyy-mm-dd
Brand Mandatory Card brand type
Type Mandatory Currently can only have the value ‘F’ (Fraud)
ReasonCode Mandatory Code describing reason for dispute
ReasonText Mandatory Text describing reason for dispute
AcquiringReferenceData Mandatory Acquirer reference to the original authorization transaction that this dispute record relates to. For each disputed transaction there exists 1 or more dispute record that all will have the same acquirer reference.
NotificationCode Mandatory Notification code
1 = Addition2 = Addition of subsequent duplicate transaction
3 = Change
4 = Delete
5 = Reactivate
IssuerGeneratedAuthorization Mandatory VISA specific,
Y = Issuer authorized transaction
X = Transaction authorized but not by issuer
N = Transaction not authorized
AccountSequenceNumber Mandatory VISA specific, identifies a transaction within the account number.
A maximum of 1000 transactions on a specific account may be added to the Visa fraud master file. The member may also pre-assign a sequence number within the 4000–4999 range. account
FraudInvestigationStatus Mandatory VISA specific, member-assigned, may be 00 through 99 or AA through ZZ
CustomerReference Mandatory VISA specific
BatchDate Mandatory Batch date, yyyy-mm-dd
TerminalId Mandatory Transaction terminal id
RRN Mandatory Retrieval Reference Number – Reference number for transaction
CardNumber Mandatory Masked cardnumber in transaction
OriginalBatchId Mandatory VISA specific, original batch id
OriginalAmount Mandatory Amount in transaction
OriginalCurrency Mandatory Currency of transaction
OriginalDate Mandatory Date of transaction, yyyy-mm-dd
AuthorizationCode Mandatory Tranasction authorization number

Getting fraud transaction list – XML examples

DTXML.1 – An example of a received XML

<?xml version="1.0"?>
<FraudTransactionResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Success</ResultText>
</Status>
<FraudTransactionList>
<FraudTransaction>
<MerchantNumber>9577851</MerchantNumber>
<ProcessingTime>2009-10-14T10:25:00.60831</ProcessingTime>
<Date>2009-03-12</Date>
<Brand>MC</Brand>
<Type>F</Type>
<ReasonCode>4</ReasonCode>
<ReasonText>COUNTERFEIT</ReasonText>
<AcquiringReferenceData>5414838196002000012345</AcquiringReferenceData>
<NotificationCode>1</NotificationCode>
<IssuerGeneratedAuthorization></IssuerGeneratedAuthorization>
<AccountSequenceNumber></AccountSequenceNumber>
<FraudInvestigationStatus></FraudInvestigationStatus>
<CustomerReference></CustomerReference>
<BatchDate>2008-06-23</BatchDate>
<TerminalId>00010002</TerminalId>
<RRN></RRN>
<CardNumber>398320******2345</CardNumber>
<OriginalBatchId>1</OriginalBatchId>
<OriginalAmount>10000</OriginalAmount>
<OriginalCurrency>352</OriginalCurrency>
<OriginalDate>2008-06-21</OriginalDate>
<AuthorizationCode>0</AuthorizationCode>
</FraudTransaction>
</FraudTransactionList>
</FraudTransactionResponse>

Getting Settlement Data

Client applications can fetch settlement data.

Settlement can contain one or more batches, and each batch contains one or more transaction.

B-Gateway


Settlement data can be fetched with the following calls

Getting settlement list

Table SD.1 – Parameters for getSettlement ()

Field Type Explanation
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantContractNumber Mandatory Contract number issued by Borgun.
DateFrom Mandatory Returns all settlements from date DateFrom. Date format YYYYMMDD.
DateTo Mandatory Returns all settlement up to and including DateTo. Date format YYYYMMDD.

Getting a list of batches in settlement

Table SD.2 – Parameters for getSettlementBatch()

Field Type Explanation
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantContractNumber Mandatory Contract number issued by Borgun.
SettlementNumber Mandatory Unique number of settlement

Getting a list of transactions in batches. BatchDate and BatchNumber are unique for each batch.

Table SD.3 – Parameters for getSettlementTransactions()

Field Type Explanation
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantContractNumber Mandatory Contract number issued by Borgun.
BatchNumber Mandatory Batch number
BatchDate Mandatory Batch date, format YYYYMMDD

Getting a list of chargebacks in settlement

Table SD.4 – Parameters for getSettlementChargeback()

Field Type Explanation
Processor Mandatory An ID issued by Borgun to the processor using this interface on behalf of the merchant
MerchantContractNumber Mandatory Contract number issued by Borgun.
SettlementNumber Mandatory Unique number of settlement

Table SD.4 – Field explanations for the status record contained in received XML

Field Type Explanation
ResultCode Mandatory Can have values 0 = “Success”, 10 = “Information” (f.ex. No Data Found), 30 = “Error”
ResultText Mandatory Text description for ResultCode, f.ex. “Success”, “Error”, “No Data Found”
ErrorMessage Mandatory Detailed error description
MessageId Mandatory Error description code of ErrorMessage if applicable
ReferenceValue Mandatory Id of record within list where error occurred. Only returned if applicable
StackTrace Mandatory Stacktrace of error if applicable

Tables SD.5 – Settlement

Field Type Explanation
SettlementNumber Mandatory Settlement number
SettlementDate Mandatory Date of settlement
MastercardDomesticAmount Conditional Not in use
MastercardInternationalAmount Conditional Not in use
MastercardOtherAmount Conditional Not in use
JcbAmount Conditional Not in use
VisaAmount Conditional Not in use
AmexAmount Conditional Not in use
TotalAmount Mandatory Total amount in settlement
TransactionCountInSettlement Mandatory Number of transactions in settlement
SettlementCurrencyCode Mandatory Currency code of settlement
DeductionAmount Mandatory Deduction amount of settlement amount
RefundAmount Mandatory Refund amount in settlement

Tables SD.6 – Settlement deductions

Field Type Explanation
SettlementNumber Mandatory Settlement number
Code Mandatory Code describing deduction type
CodeDescription Mandatory Text describing deduction type
Amount Mandatory Deduction amount
DeductionCurrencyCode Mandatory Currency code of deduction

SDXML.5 and SDXML.6 – An example of a received XML with settlement and deduction

Request:

<?xml version="1.0" encoding="utf-8"?>
<getSettlements>
<Processor>1</Processor>
<MerchantContractNumber>9999999</MerchantContractNumber>
<DateFrom>20110129</DateFrom>
<DateTo>20110930</DateTo>
</getSettlements>

Response:

<?xml version="1.0"?>
<SettlementResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Success</ResultText>
</Status>
<Settlement>
<MerchantNumber>9999999</MerchantNumber>
<SettlementNumber>4290310</SettlementNumber>
<SettlementDate>2014-06-04T00:00:00</SettlementDate>
<MastercardDomesticAmount>0.0</MastercardDomesticAmount>
<MastercardInternationalAmount>0.0</MastercardInternationalAmount>
<MastercardOtherAmount>0</MastercardOtherAmount>
<JcbAmount>0</JcbAmount>
<VisaAmount>0</VisaAmount>
<AmexAmount>0</AmexAmount>
<TotalAmount>220</TotalAmount>
<TransactionCountInSettlement>0</TransactionCountInSettlement>
<SettlementCurrencyCode>USD</SettlementCurrencyCode>
<DeductionAmount>197.62</DeductionAmount>
<RefundAmount>0.0</RefundAmount>
<SettlementDeductions>
<SettlementNumber>4290310</SettlementNumber>
<Code>F_MSC_MC</Code>
<CodeDescription>Merchant Commission MC</CodeDescription>
<Amount>-21.04</Amount>
<DeductionCurrencyCode>USD</DeductionCurrencyCode>
<Id/>
</SettlementDeductions>
<SettlementDeductions>
<SettlementNumber>4290310</SettlementNumber>
<Code>F_CBK</Code>
<CodeDescription>Chargeback Fee</CodeDescription>
<Amount>-30</Amount>
<DeductionCurrencyCode>USD</DeductionCurrencyCode>
</SettlementDeductions>
</Settlement>
</SettlementResponse>

SD.7 –List of batches in settlement

Field Type Explanation
BatchNumber Mandatory Batch number
BatchDate Mandatory Date of batch
SettlementDate Mandatory Settlement date
SettlementNumber Mandatory Settlement number
TransactionCountInBatch Mandatory Number of transactions in batch
TransactionSumInBatch Mandatory Amount in transactions in batch
BatchCurrencyCode Mandatory Currency code of amounts

SDXML.7 – Example of received batchlist

Request:

<?xml version="1.0" encoding="utf-8"?>
<getSettlementBatch>
<Processor>1</Processor>
<MerchantContractNumber>9999999</MerchantContractNumber>
<SettlementNumber>4245</SettlementNumber>
</getSettlementBatch>

Response:

<?xml version="1.0"?>
<SettlementBatchResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Succcess</ResultText>
</Status>
<SettlementBatch>
<BatchNumber>116757</BatchNumber>
<BatchDate>2007-12-05T00:00:00</BatchDate>
<SettlementDate>2008-01-02T00:00:00</SettlementDate>
<SettlementNumber>4245</SettlementNumber>
<TransactionCountInBatch>9</TransactionCountInBatch>
<TransactionSumInBatch>18405.00</TransactionSumInBatch>
<BatchCurrencyCode>ISK</BatchCurrencyCode>
</SettlementBatch>
</SettlementBatchResponse>

SD.8 – Transactions in batches

Field Type Explanation
TransactionDate Mandatory Date of transaction
Amount Mandatory Transaction amount
CurrencyCode Mandatory Currency code of amounts in transaction
SlipNumber Mandatory Slip number
RRN Mandatory Retrieval reference number
CardNumber Mandatory Card number
CardType Mandatory Card type
OriginalAmount Mandatory Original amount on slip
OriginialAmountCurrencyCode Mandatory Amount in currency code
BatchNumber Mandatory Number of batch containing transaction
SettlementDate Mandatory Date of settlement
SettlementNumber Mandatory Number of settlement containing transaction

SDXML.8 – An XML example of a received transaction list

Request:

<?xml version="1.0" encoding="utf-8"?>
<getSettlementTransactions>
<Processor>1</Processor>
<MerchantContractNumber>9999999</MerchantContractNumber>
<BatchNumber>101166</BatchNumber>
<BatchDate>20110105</BatchDate>
</getSettlementTransactions>

Response:

<?xml version="1.0"?>
<SettlementTransactionResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>Success</ResultText>
</Status>
<SettlementTransaction>
<TransactionDate>2011-01-05T00:00:00</TransactionDate>
<Amount>687.00</Amount>
<CurrencyCode>ISK</CurrencyCode>
<Slipnumber>9372</Slipnumber>
<RRN>rr1402530644</RRN>
<Cardnumber>544602******8005</Cardnumber>
<Cardtype>MD</Cardtype>
<OriginialAmount>687.00</OriginialAmount>
<OriginialAmountCurrencyCode>SEK</OriginialAmountCurrencyCode>
<BatchNumber>101166</BatchNumber>
<SettlementDate>2008-01-02T00:00:00</SettlementDate>
<SettlementNumber>2727</SettlementNumber>
</SettlementTransaction>
</SettlementTransactionResponse>

SD.9 – Chargeback transactions in settlements

Field Type Explanation
TransactionDate Mandatory Date of transaction
Amount Mandatory Transaction amount
CurrencyCode Mandatory Currency code of amounts in transaction
SlipNumber Mandatory Slip number
RRN Mandatory Retrieval reference number
CardNumber Mandatory Card number
CardType Mandatory Card type
OriginalAmount Mandatory Original amount on slip
OriginialAmountCurrencyCode Mandatory Amount in currency code
BatchNumber Mandatory Number of batch containing transaction
SettlementDate Mandatory Date of settlement
SettlementNumber Mandatory Number of settlement containing transaction
AcquirerReference Mandatory Acquirer reference for chargeback. Unique number for the authorization transaction. Can be used to reference a list of dispute records related to the chargeback.
ChargebackDate Mandatory Date of chargeback registration
ChargebackAmount Mandatory Amount of chargeback

SDXML.9 – An XML example of a received chargeback list

Request:

<?xml version="1.0" encoding="utf-8"?>
<getSettlementChargeback>
<Processor>1</Processor>
<MerchantContractNumber>9999999</MerchantContractNumber>
<SettlementNumber>7566</SettlementNumber>
</getSettlementChargeback>

Response:

<?xml version="1.0"?>
<SettlementChargebackResponse>
<Status>
<ResultCode>0</ResultCode>
<ResultText>OK</ResultText>
</Status>
<SettlementChargeback>
<SettlementDate>2011-08-10T00:00:00</SettlementDate>
<SettlementNumber>7566</SettlementNumber>
<BatchNumber>162</BatchNumber>
<Amount>-34.9500000000000000</Amount>
<CurrencyCode>USD</CurrencyCode>
<Cardnumber>4060 42** **** 8831</Cardnumber>
<Cardtype>04</Cardtype>
<TransactionDate>2011-07-08T00:00:00</TransactionDate>
<OriginialAmountCurrencyCode>USD</OriginialAmountCurrencyCode>
<OriginialAmount>-34.95</OriginialAmount>
<Slipnumber>777003</Slipnumber>
<RRN>AA1234567890</RRN>
<AcquirerReference>5414811112222000025737</AcquirerReference>
<ChargebackDate>2011-08-03T00:00:00</ChargebackDate>
<ChargebackAmount>187</ChargebackAmount> </SettlementChargeback>
</SettlementChargebackResponse>

Sending detailed data

This addition to get Authorization is used to supply detailed invoice after the financial transaction has been processed. In order to match the detail transaction to the financial transaction some parameters must be supplied.

Sending detail data – XML explanations

Tables SDD.1, SDD.2 and SDD.3 – Field explanations for a sent XML
The input is split into a header and detail. Following the header is a detailed description of the invoice in XML format. The invoice itself is split into a header record (A4) and detail records (A6) as follows:

Main header

Field Type Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
Processor Mandatory An Id issued by Borgun to the processor using this interface on behalf of the merchant.
MerchantId Mandatory An Id in B-Gateway of the merchant requesting services
TerminalId Optional A terminal id in B-Gateway for the merchant requesting sevices.
TransType Mandatory Same as in the original transaction
TrAmount Mandatory Same as in the original transaction
TrCurrency Mandatory Same as in the original transaction
DateAndTime Mandatory Same as in the original transaction
PAN Mandatory Same as in the original reply
ExpDate Mandatory Expiration date – YYMM
RRN Mandatory Same as in the original reply
Transaction Optional Same as in the original reply
Batch Optional Same as in the original reply
AuthCode Conditional Same as in the original reply

Invoice header (A4):

Field Type Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”.
MessageNumber Mandatory Message number (sequence number of line within file)
InvoiceNumber Mandatory Invoice number
InvoiceDate Mandatory Invoice date (yyyymmdd)
Reference Optional Reference number
MerchantSSN Mandatory Merchant social security number
MerchantVATNumber Mandatory Merchant VAT number
Amount1 Mandatory Total (A6 Amount)
Discount Optional Total (A6*DiscountAmount) Discount
AmountWithDiscount Optional Total (A6*AmountWithDiscount) Amount with discount
Vgju Optional Total (A6*Vgju) (zero filled)
Amount3 Optional Total (A6*Amount3) (same as AmountWithDiscount)
TotalVAT Mandatory Total (A6*VATAmount) VAT
AmountWithVAT Mandatory Total (A6*AmountWithVAT) amount with VAT
InvoiceAmount Mandatory Total invoice
Rounding Optional Round off amount in “aurar”
RikiskaupFee Optional Total Rikiskaup fee
GLAccount Optional General ledger account number
RecordNumber Mandatory Record number within invoice (0001 for header)
NumberOfRecords Mandatory Number of records in invoice (A4+number of A6)
SlipNumber Optional Slip number
Comments Optional Comments
OrderNumber Optional Order number
OrderDate Optional Order date
DeliveryDate Optional Delivery date
DeliveryAddress Optional Delivery address

Invoice detail (A6):

Field Type Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”.
MessageNumber Mandatory Message number (sequence number of line within file)
ProductCode Mandatory Product code
ItemDescription Mandatory Item description
UNSPSCcode Optional UNSPSC code
UNSPSCdescription Optional UNSPSC description
CommodityCode Optional Commodity code
ItemQuantity Mandatory Item quantity
UnitOfMeasurement Optional Item unit of measure (ltr, km, kg....)
GrossValue Mandatory Unit price without VAT
Amount Mandatory Amount (ItemQuantity * GrossValue)
DiscountPercent Optional Discount percent (%)
DiscountAmount Optional Discount amount
AmountWithDiscount Optional Amount with discount (Amount – DiscountAmount)
Vgjp Optional “00000”
Vgju Optional “00000000000”
Amount3 Optional AmountWithDiscount
VATPercent Mandatory VAT %
VATAmount Mandatory VAT amount
AmountWithVAT Mandatory Amount with VAT (Amount3 + VATAmount)
RikiskaupFeePercent Optional Rikiskaup fee (%)
RikiskaupFee Optional Rikiskaup fee amount
GLAccount Optional General ledger account number
RecordNumber Mandatory Record number within invoice (0002-xxxx)
NumberOfRecords Mandatory Number of records in invoice (A4+number of A6)
SlipNumber Optional Slip number
Ref1 Optional Reference 1
Ref2 Optional Reference 2
Ref3 Optional Reference 3
Ref4 Optional Reference 4

Table SDD.4 – Field explanations for a received XML

Field Type Explanation
Version Mandatory Same value as in the request message
Processor Mandatory Same value as in the request message
MerchantId Mandatory Same value as in the request message
TerminalId Mandatory Same value as in the request message
TransType Mandatory Same value as in the request message
TrAmount Mandatory Same value as in the request message
TrCurrency Mandatory Same value as in the request message
DateAndTime Mandatory Same value as in the request message
PAN Mandatory Same value as in the request message
ExpDate Mandatory Same value as in the request message
RRN Mandatory Same value as in the request message
Transaction Mandatory Same value as in the request message
Batch Mandatory Same value as in the request message
CardAccID Mandatory Code Identifying the card acceptor. This Id is issued by the acquirer
CardAccTerminal Mandatory Code Identifying the terminal the card acceptor is using
AuthCode Mandatory Same value as in the request message
ActionCode Mandatory Reason code for response

Sending detail data – XML examples

SDDXML.1 – An example of a sent XML

<?xml version="1.0" encoding="utf-8"?>
<DetailData>
<Version>1000</Version>
<Processor>123</Processor>
<MerchantId>2</MerchantId>
<TransType>1</TransType>
<TrAmount>100000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>060216103700</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>0506</ExpDate>
<RRN>404</RRN>
<Batch>3</Batch>
<A4>
<Version>1000</Version>
<MessageNumber>2</MessageNumber>
<InvoiceNumber>071897</InvoiceNumber>
<InvoiceDate>20060118</InvoiceDate>
<MerchantSSN>5415986459</MerchantSSN>
<MerchantVATNumber>079318</MerchantVATNumber>
<Amount1>100000</Amount1>
<TotalVAT>24500</TotalVAT>
<AmountWithVAT>124500</AmountWithVAT>
<InvoiceAmount>125000</InvoiceAmount>
<RecordNumber>1</RecordNumber>
<NumberOfRecords>1</NumberOfRecords>
<A6>
<Version>1000</Version>
<MessageNumber>2</MessageNumber>
<ProductCode>054</ProductCode>
<ItemDescription>Chocolate</ItemDescription>
<ItemQuantity>5</ItemQuantity>
<GrossValue>20000</GrossValue>
<Amount>1000</Amount>
<VATPercent>0,245</VATPercent>
<VATAmount>24500</VATAmount>
<AmountWithVAT>124500</AmountWithVAT>
<RecordNumber>1</RecordNumber>
<NumberOfRecords>1</NumberOfRecords>
</A6>
</A4>
</DetailData>

Sending passenger itinerary

This addition to getAuthorization is used to supply passenger itinerary data after the financial transaction has been processed. It currently only supports itineraries with four legs or less.

Sending passenger itinerary – XML explanations

Tables SPI.1, SPI.2 – Field explanations for a sent/received XML

The input is split into a header and detail. Following the header is a detailed description of the invoice in XML format. The invoice itself is split into a header record (A4) and detail records (A6) as follows:

Table SPI.1 – Passenger Itinerary information field explanations for a sent XML

Field Type Length Explanation
Version Mandatory Indicates the version of these specifications the client is using. Current version is “1000”
TrDate Mandatory Same as in the original transaction
TrTime Mandatory Same as in the original transaction
PassengerName Mandatory 1..29 AN Name of passenger to whom the ticket was issued
FlightNumber_1 Mandatory 3 AN Flight number in leg 1
TravelDate_1 Mandatory 6 Traveldate of leg 1, format is YYMMDD.
DepartureAirport_1 Mandatory 3 AN Departure airport, airport code can be obtained from OAG or equivalent.
CarrierCode_1 Mandatory 2 AN Carrier code is a standard abbreviation for the airline carrier. Can be obtained from IATA, or an equivalent. Length
ServiceClassCode_1 Optional 3 N Service type, such as first class, etc. Can be obtained from OAG or equivalent.
DestinationAirport_1 Optional 3 AV Destination airport, airport code can be obtained from OAG or equivalent.
FareBaseCode_1 Optional 1..15 AN Fare basis code contains a code that carriers assign to particular ticket type such as business class or discounted/refundable.
FlightNumber_2 Optional Same as in leg 1
TravelDate_2 Optional Same as in leg 1
DepartureAirport_2 Optional Same as in leg 1
CarrierCode_2 Optional Same as in leg 1
ServiceClassCode_2 Optional Same as in leg 1
DestinationAirport_2 Optional Same as in leg 1
FareBaseCode_2 Optional Same as in leg 1
FlightNumber_3 Optional Same as in leg 1
TravelDate_3 Optional Same as in leg 1
DepartureAirport_3 Optional Same as in leg 1
CarrierCode_3 Optional Same as in leg 1
ServiceClassCode_3 Optional Same as in leg 1
DestinationAirport_3 Optional Same as in leg 1
FareBaseCode_3 Optional Same as in leg 1
FlightNumber_4 Optional Same as in leg 1
TravelDate_4 Optional Same as in leg 1
DepartureAirport_4 Optional Same as in leg 1
CarrierCode_4 Optional Same as in leg 1
ServiceClassCode_4 Optional Same as in leg 1
DestinationAirport_4 Optional Same as in leg 1
FareBaseCode_4 Optional Same as in leg 1
TravelAgencyCode Mandatory 8 Code of the travel agency issuing the ticket
TravelAgencyName Mandatory 25 Name of travel agency issuing the ticket
TicketNumber Mandatory 15 Number of the ticket

Sending detail data – XML examples

SDDXML.1 – An example of a sent XML

<?xml version="1.0" encoding="utf-8"?>
<getAuthorization xmlns="http://tempuri.org/getAuthorization.xsd">
<Version>1000</Version>
<Processor>3</Processor>
<MerchantID>3</MerchantID>
<TerminalID>1</TerminalID>
<TransType>1</TransType>
<TrAmount>10000</TrAmount>
<TrCurrency>352</TrCurrency>
<DateAndTime>120325120000</DateAndTime>
<PAN>5555544433331111</PAN>
<ExpDate>1412</ExpDate>
<CVC2>111</CVC2>
<RRN>TESTAIR00111</RRN>
 <PassengerItineraryData>
 <A1>

<Version>10</Version>
  <MessageNumber>1111111</MessageNumber>
  <TrDate>20120222</TrDate>
  <TrTime>151515</TrTime>
  <PassengerName>Jane Doe</PassengerName>
  <FlightNumber_1>111111</FlightNumber_1>
  <TravelDate_1>20120111</TravelDate_1>
  <DepartureAirport_1>KEF</DepartureAirport_1>
  <CarrierCode_1>CC</CarrierCode_1>
  <ServiceClassCode_1>123</ServiceClassCode_1>
  <DestinationAirport_1>JFK</DestinationAirport_1>
  <FareBaseCode_1>111111</FareBaseCode_1>
  <FlightNumber_2>222222</FlightNumber_2>
  <TravelDate_2>20120222</TravelDate_2>
  <DepartureAirport_2>KEF</DepartureAirport_2>
  <CarrierCode_2>CC</CarrierCode_2>
  <ServiceClassCode_2>123</ServiceClassCode_2>
  <DestinationAirport_2>JFK</DestinationAirport_2>
  <FareBaseCode_2>222222</FareBaseCode_2>
  <FlightNumber_3>333333</FlightNumber_3>
  <TravelDate_3>20120330</TravelDate_3>
  <DepartureAirport_3>KEF</DepartureAirport_3>
  <CarrierCode_3>CC</CarrierCode_3>
  <ServiceClassCode_3>123</ServiceClassCode_3>
  <DestinationAirport_3>JFK</DestinationAirport_3>
<FareBaseCode_3>333333</FareBaseCode_3>
  <FlightNumber_4>444444</FlightNumber_4>
  <TravelDate_4>20120404</TravelDate_4>
  <DepartureAirport_4>KEF</DepartureAirport_4>
  <CarrierCode_4>CC</CarrierCode_4>
  <ServiceClassCode_4>123</ServiceClassCode_4>
  <DestinationAirport_4>JFK</DestinationAirport_4>
  <FareBaseCode_4>444444</FareBaseCode_4>
  <TravelAgencyCode>A7654321</TravelAgencyCode>
  <TravelAgencyName>All travel</TravelAgencyName>
  <TicketNumber>900.123.222</TicketNumber>
 </A1>
 </PassengerItineraryData>
</getAuthorization>

Appendix - Action Codes

Action Code Explanation ISO Reply
100-199 Show reason for transaction dismissal by issuer, card pick-up not required.
000 Accepted 00
100 Do not honor (Not accepted) 05
101 Expired card 54
102 Suspected card forgery (fraud)
103 Merchant call acquirer 01, 66, 08
104 Restricted card 62
106 Allowed PIN retries exceeded 75, 76
109 Merchant not identified 03
110 Invalid amount 13, 64
111 Invalid card number 14
112 PIN required
116 Not sufficient funds 51
117 Invalid PIN 55
118 Unknown card
119 Transaction not allowed to cardholder 57
120 Transaction not allowed to terminal 12, 58
121 Exceeds limits to withdrawal 61, 65
125 Card not valid
126 False PIN block
129 Suspected fraud
130 Invalid Track2
131 Invalid Expiration Date
161 DCC transaction not allowed to cardholder
162 DCC cardholder currency not supported
163 DCC exceeds time limit for withdrawal
164 DCC transaction not allowed to terminal
165 DCC not allowed to merchant
166 DCC unknown error
200-299 Show reason for transaction dismissal by issuer, card pick-up required.
200 No not honor 04
201 Card not valid 33
202 Suspected card forgery (fraud)
203 Merchant contact acquirer 37
204 Limited card 36
205 Merchant contact police
206 Allowed PIN-retries exceeded 38
207 Special occasion
208 Lost card 41
209 Stolen card 43
210 Suspected fraud
902 False transaction 89, 06
904 Form error 30
907 Issuer not responding
908 Message can not be routed 15, 80, 81,
909 System error 83, 96
910 Issuer did not respond 68
911 Issuer timed out 82
912 Issuer not reachable 91
913 Double transaction transmission 94
914 Original transaction can not be traced
916 Merchant not found
950 No financial record found for detail data
951 Batch already closed
952 Invalid batch number
953 Host timeout
954 Batch not closed
955 Merchant not active
956 Transaction number not unique

#Demos#

Below are a few demos that can be downloaded to get started.

C# demo
Python demo
PHP demo

FAQ

Frequently Asked Questions

  1. Is it possible to perform partial refunds (TransType = 3)? Can this happen multiple times until reaching the total amount authorized?
    This is supported, for example
    1. Perform a normal purchase transaction (TransType= 1) with amount 10.
    2. Then, perform a refund transaction (TransType = 5) with amount 5.
    3. Finally, perform another refund transaction for the remaining 5.
      The sum of the refunds must be equal or lower than the original sale amount.

  2. Is it possible to send normal purchase transactions(TransType = 1) with less amount than the one specified in the original pre-authorization (TransType = 5) so that the final authorized amount is the one sent in the normal purchase?
    This is supported, for example
    1. Perform a pre-authorize transaction (TransType =5) with amount 10.
    2. Capture the previous pre-authorization performing a normal purchase transaction (TransType = 1) with amount 5.
      Note that the cardholder will have the withdrawal limit corrected 1-2 days later.

  3. Has RRN any kind of uniqueness restriction?
    RRN has must be size 12 alphanumeric, the last 6 letters cannot be 000000. For reference sake it is recommended to be a sequence with fixed first part, i.e. ACME12345678

  4. Are batches automatically closed at the same time every day? In that case, could you tell us the exact time and time zone when this happens? Can this time be configured or is It fixed?
    Default is to have the batch close time fixed, thenit will close at midnight GMT-0 (no daylight changes). It can be controlled by calling party by using the newBatch() command, at execution the old batch is closed and a new one is opened. This is the preferred way to use for custom closure.

  5. Should Refund or Partial Reversal be used?
    Refund should be preferred in general, it informs the issuer immediately that the authorization amount will be changed and the creditamount is on the cardholder account in 24-48hours.
    Partial Reversal is more suited to specific business cases where there is a high likelihood of an immediate change in the sale amount. An example of this is a vending machine that authorizes for the maximum amount at the beginning then has the sale amount as the actual item buying value.

  6. What is the date format
    The gateway uses either yyyymmddhhmmss or yymmddhhmmss depending on functions.
    The format is:
    yyyy: year in numeric form with four letters, f.ex. 2012 (or 12 if yy) mm: month in numeric format (f.ex. 12 as december) dd: date in numeric format (f.ex. 31) hh: hour in 24 hour numeric format (f.ex. 18) mm: minutes (f.ex. 18) ss: seconds (f.ex. 59)
    example
    20121231184059 44

  7. When are batches closed and financial records sent?
    Batches are closed at GMT+0 with no daylight savings. All dates at Borgun are running at GMT+0. Financial records are sent during the night. Merchants can control the batch close time by using newBatch(), the use cases for that are rare and tied to specific merchant segments.

  8. 3D-Secure, when is XID needed and where is VISA ECI
    MasterCard uses UCAF and SecurityLevelIndicator, there is no XID in MasterCard SecureCode.
    VISA uses CAVV, XID and SecurityLevelIndicator. SecurityLevelIndicator is VISA ECI, the insent value is converted to the equivalent ECIvalue. While CAVV and UCAF have the same function, and SecuityLevel and ECI also have the same function, then the XID is simply a merchant reference number and only used by VISA.

  9. How are credits differentiated/displayed in the settlement response
    Credits and deductions are represented with the minus sign in settlement reconciliation data.

  10. What is the preferred timeout?
    Borgun gateway waits for 35 seconds before cancelling requests. A suitable timeout is 40 seconds.

  11. How often can refund be sent for the original transaction?
    The cumulative amount of refunds cannot exceed the amount on the original transaction. The refunds can be as many as needed until the sum is equal to the original amount.

  12. What configuration items are used?
    As merchants are processed through the business channels they are registered and setup according to business usage. The Business channel will send back
    • MerchantId: used in payment gateway to send in authorization request
    • MID: used in payment gateway when fetching settlement/fraud/dispute, i.e. reconciliation data
    • Terminal information, usually some combination of the following terminal types
    Terminal 1 is ecommerce
    Terminal 2 is ecommerce with 3D-Secure
    Terminal 3 is recurrent
    Terminal 4 is MOTO
    It simplifies configuration setup if terminal 1 is always ecommerce and 4 is always MOTO etc., but if needed then they can be put in any order.
    Not all merchants have all terminals types and would then be sent for example the following
    Terminal 1 is ecommerce
    Terminal 4 is MOTO
    During initial setup a processor number is created that will follow all requests from the merchant, processor, ISO.

  13. Which ActionCodes constitutes errors and which success?
    Transactions will only be marked as approved if the returned code from issuer is 000.
    There are four ActionCodes that Borgun does returns, the rest are exclusively from issuers
    904: Malformed XML or incorrect data in insent XML
    909: System error or network connection to schema is lost
    953: Host timeout (can also come from network, but then sporadically)
    The difference between 909 and 953 is minimal, if 953 then we will send the request and wait for response, if 909 then we know that the line is down and there is no reason to send the request.
    If there are problems, then they start with 953 andthen change to 909 until the we problem is fixed.
    Note that 904, 909, 953 can also come from issuers or the card schema network. 904 should always be looked into.

  14. How to find information on authorization if no response is received?
    At midnight all open batches are closed, financial records are sent to the card schema and transaction status on financial transactions is set to value 14. getTransactionList() can be called on a regular basis to check on status value and use to reconcile authorization requests with unknown status.

  15. Do the xml elements in a request xml string parameter need to be in a particular order?
    No, the xml elements can be in any order.

  16. Common pitfalls?
    • Refunds and cancelAuthorization need the exact DateAndTime + RRN of the original transaction that is being referred.
    • ExpireDate in all authorization requests is of the form YYMM 46
    • Using cancelAuthorization or Partial Reversal against an original transaction that is in closed batch. After batch is closed the transaction cannot be changed but Refund can be used.
    • For historical reasons then the merchantid tag is in some functions and in others.
    • Sending in authorization request without TerminalId. The request will go through processing and return 909, the reason being that itis allowed to send in requests without terminal if one terminal has been marked asDefault. That function is not in common use.