Documentation

Borgun, all rights reserved. 2017 ©

Introduction

This document describes Merchant Settlement WCF services provided by Borgun hf.

User must be registered to load the services and have proper access to use them.

Communication is via SSL on a web server at Borgun.

Environment

A test service is available for use while client is being implemented. Contact Borgun for test access information.

The following merchant contract IDs can be used while testing.

Merchant IDs: 9275444, 9280286, 9401573, 9518042

When implementation is completed this information has to be replaced with the proper user account supplied by Borgun, production URL and production Merchant ID. Contact Borgun for production access.

Lastest service URLs

Test:
https://test.borgun.is/settlement/creditcard.svc
https://test.borgun.is/settlement/debitcard.svc
Production:
https://services.borgun.is/settlement_3_6/creditcard.svc
https://services.borgun.is/settlement_3_6/debitCard.svc

Overview of available services

Credit card service

Service method name Description
GetSettlementsByMerchant Returns credit card settlements for merchant. CreditCardSettlement[]
GetCollectedSettlementsByMerchant Returns collected (due) credit card settlements for merchant. CreditCardSettlement[]
GetBatchesByMerchant Returns credit card batches for merchant. CreditCardBatch[]
GetBatchesByRunNumber Returns credit card batches by settlement. CreditCardBatch[]
GetTransactionsByBatch Return credit card transactions by batch. CreditCardTransaction[]
GetTransactionsByRunNumber Return credit card transactions by batch. CredtiCardTransaction[]
GetSettlementDeductionItems Return settlement deduction items. CreditCardSettlementDeduction[]
GetCardTypeBatchesByMerchant Returns credit card batches, one for each card type, for merchant. CreditCardBatch[]. Obsolete
GetSettlementByRunNumber Returns credit card settlement with a given settlement run number for merchant. CreditCardSettlement
GetCardTypeBatchesByRunNumber Returns credit card batches, one for each card type, for merchant with a given settlement run number. CreditCardBatch[]. Obsolete
GetSettlementRunNumbers Returns a list of information about settlement s for a user over a given period. CreditCardSettlementInformation[]
GetLatestSettlementRunNumber Returns the latest settlement run number for a given user. Int32

Debit card service

Service method name Description
GetSettlementsByMerchant Returns debit card settlement by merchant. DebitCardSettlement[]
GetBatchesByMerchant Returns batches by merchant. DebitCardBatch[]
GetTransactionsByBatch Returns transactions by batch number. DebitCardTransaction[]

General usage guidelines

The response contains a ResultStatus which contains ResultCode, ResultText and ErrorMessage to describe result.

ResultCode ResultText ErrorMessage
0 Success NULL
10 Informational e.g.: Not found
20 Warning A warning message
30 Error Error condition explained

Objects

CreditCards

CreditCardSettlement

Field Type Description
MerchantID String 7 digit number starting with 9 supplied by Borgun to each merchant
SettlementDate DateTime Date of settlement
SettlementRunNumber String Unique number identifying a single settlement for a merchant. For unsettled batches (collected) the value is 0.
Amount Decimal Settled amount
Deduction Decimal Total fee deducted from the settled amount
Commission Decimal Total commission deducted from the settled amount
Payment Decimal Total amount paid
JcbAmount Decimal JCB amount
AmexAmount Decimal American Express amount
MasterCardAmount Decimal MasterCard amount
CupAmount Decimal CUP Amount.
VisaAmount Decimal VISA amount
DinersAmount Decimal Diners amount
CurrencyCode String Alpha string of the settlement currency
SlipCount Int Number of slips in settlement.
DeductionItems CreditCardSettlementDeduction[] See CreditCardSettlementDeduction
Batches CreditCardBatch[] See CreditCardBatch

CreditCardBatch

Field Type Description
MerchantID String 7 digit number starting with 9 supplied by Borgun to each merchant
BatchNumber String Unique number of the batch
BatchDate DateTime Date of batch
Sum Decimal Total sum of batch
Slips Integer Slip count
SettlementRunNumber String Unique number identifying a single settlement for a merchant. For unsettled batches (collected) this value is 0.
SettlementDate DateTime Date of settlement, if available.
CurrencyCode String Alpha string of the batch currency
CardType String Legacy code, usually null unless using CardTypeBatch functions.

CreditCardTransaction

Field Type Description
MerchantID String 7 digit number starting with 9 supplied by Borgun to each merchant
TransactionDate DateTime Date of transaction
Amount Decimal Transaction amount
CurrencyCode String Three letter currency code of transaction.
SlipNumber String Transaction slip number
CardNumber String Masked card number so only first 6 and the last 4 digits are shown
CardType String Card brand, can be VISA, MC etc. See appendix 2 for a list of codes.
OriginalAmount Decimal Transaction amount before any currency conversions
OriginalCurrencyCode String Alpha string of the original currency of the transaction
SettlementRunNumber String Unique number identifying a single settlement for a merchant. For unsettled batches (collected) this value is 0.
BatchNumber String Batch number
BatchDate DateTime Batch date
AuthorizationCode
TransactionType String Type of transaction. See appendix 3 for a list of transaction types.
RRN String Reference Number
IsCorporate Bool Indicates if the credit card used is a corporate card.
TerminalId String The ID of the terminal
CardholderCountry String Country of the card issuer, 3 letter ISO code (availability not guaranteed)

CreditCardSettlementDeduction

Field Type Description
MerchantID String 7 digit number starting with 9 supplied by Borgun to each merchant
SettlementRunNumber String Unique number identifying a single settlement for a merchant. For unsettledbatches (collected) this value is 0.
Amount Decimal Deduction amount
Code String Deduction code
CurrencyCode String Alpha string of the deduction currency
Text String Deduction description
Fee String Exact amount of a single fee or the fee percentage, depending on the type of fee
FeeCount Double Transaction count the fee applies to (if applicable)
InterchangeFee Decimal Total interchange fee part

CreditCardSettlementInformation

Field Type Description
MerchantID String 7 digit number starting with 9 supplied by Borgun to each merchant
SettlementDate DateTime Date of settlement
SettlementRunNumber String Unique number identifying a single settlement for a merchant

DebitCards

DebitCardSettlement

Field Type Description
MerchantID String 7 digit number starting with 9 supplied by Borgun to each merchant
ReconciliationDate DateTime Date of reconciliation
TransactionFeeAmount Decimal Total transaction fee amount
MinTransactionFeeCount Integer Number of transactions with minimum transaction fee
MinTransactionFeeAmount Decimal Minimum transaction fee amount
MaxTransactionFeeCount Integer Number of transactions with maximum transaction fee
MaxTransactionFeeAmount Decimal Maximum transaction fee amount
PercentageTransactionFeeCount Integer Number of transactions with percentage fee
PercentageTransactionFeeAmount Decimal Percentage fee amount
MinTransactionTurnOver Decimal Turnover of transactions with minimum transaction fee
MaxTransactionTurnOver Decimal Turnover of transactions with maximum transaction fee
PercentageTransactionTurnOver Decimal Turnover of transactions with percentage transaction fee
ReconciliationSlipCount Integer Slip count
ReconciliationAmount Decimal Amount

DebitCardBatch

Field Type Description
MerchantID String 7 digit number starting with 9 supplied by Borgun to each merchant
StoreNumber String Store number
PosNumber String POS number
BankAccount String Bank account
TransmissionDate DateTime Date of transmission
ReconciliationDate DateTime Date of reconciliation
TransactionDate DateTime Date of transaction
BatchNumber String Batch number
Amount Decimal Batch amount
SlipCount Integer Slip count
TransactionFeeAmount Decimal Transaction fee amount
MinTransactionFeeCount Integer Number of transactions with minimum fee
MinTransactionFeeAmount Decimal Minimum transaction fee amount
MaxTransactionFeeCount Integer Number of transactions with maximum fee
MaxTransactionFeeAmount Decimal Maximum transaction fee amount
PercentageTransactionFeeCount Integer Number of transactions with percentage fee
PercentageTransactionFeeAmount Decimal Percentage fee amount
MinTransactionTurnOver Decimal Turnover of transactions with minimum transaction fee
MaxTransactionTurnOver Decimal Turnover of transactions with maximum transaction fee
PercentageTransactionTurnOver Decimal Turnover of transactions with percentage transaction fee
ReconciliationSlipCount Integer Total number of reconciliation slips
ReconciliationAmount Decimal Total reconciliation amount

DebitCardTransaction

Field Type Description
MerchantContractNumber String 7 digit number starting with 9 supplied by Borgun to each merchant
CardNumber String The masked debit card number
BatchNumber String Batch number
TransmissionDate DateTime Date of transmission
ReconciliationDate DateTime Date of reconciliation
TransactionDate DateTime Date of transaction
AuthorizationNumber String The number of the authorization
Amount Decimal Transaction amount
Fee Decimal Fee amount
StoreNumber String Store number
PosNumber String POS number
BankNumber String Bank number of the card

Service usage

Credit Cards

GetSettlementsByMerchant

Summary
Returns all credit card settlements for a given merchant ID over a time period.

Parameters

Name Optional Description
status No Out parameter that contains the result status
merchantID No Merchant ID (Contract number) issued by Borgun
dateFrom No Returns all settlements from and including dateFrom.
dateTo No Returns all settlements up to and including dateTo.
includeDeductionItems No True if deduction items should be included
includeBatches No True if batches should be included

GetSettlementByRunNumber

Summary
Returns a credit card settlement with a given run number for a merchant.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contract number) issued by Borgun
settlementRunNumber Run number of settlement
includeDeductionItems No True if deduction items should be included
includeBatches No True if batches should be included

GetCollectedSettlementsByMerchant

Summary
Returns the sum of unsettled transactions for the given merchant ID.

Parameters

Name Optional Description
status No Out parameter that contains the result status
merchantID No Merchant ID (Contract number) issued by Borgun

GetBatchesByMerchant

Summary
Returns all credit card batches for the given merchant ID over a time period.

Parameters

Name Optional Description
status No Out parameter that contains the result status
merchantID No Merchant ID (Contract Number) issued by Borgun
dateFrom No Returns all batches from and including dateFrom.
dateTo No Returns all batches up to and including dateTo.

GetBatchesByRunNumber

Summary
Returns all credit card batches in a given settlement.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contract number) issued by Borgun
settlementRunNumber Run number of settlement

GetCardTypeBatchesByMerchant

Summary
Obsolete function, will not be supported in future versions.

Returns a list of credit card batches for the given merchant ID over a time period, with one credit card batch object per each card type within a batch with summarized card type turnover. See card types in appendix 2.

Parameters

Name Optional Description
status No Out parameter that contains the result status
merchantID No Merchant ID (Contract Number) issued by Borgun
dateFrom No Returns all batches from and including dateFrom.
dateTo No Returns all batches up to and including dateTo.

GetCardTypeBatchesByRunNumber

Summary
Obsolete function, will not be supported in future versions.

Returns a list of credit card batches for the given merchant ID and settlement, with one credit card batch object per each card type within a batch with summarized card type turnover. See card types in appendix 2.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contract number) issued by Borgun
settlementRunNumber Run number of settlement

GetTransactionsByBatch

Summary
Returns all credit card transactions in a given batch on a single date.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contract number) issued by Borgun
batchNumber Batch number
batchDate Batch date

GetTransactionsByRunNumber

Summary

Returns all credit card transactions in a given settlement.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contractnumber) issued by Borgun
settlementRunNumber Run number of settlement

GetSettlementDeductionItems

Summary
Returns all deduction items in a settlement for a given merchant.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contract number) issued by Borgun
settlementRunNumber Run number of settlement

GetSettlementRunNumbers

Summary
Returns settlement run numbers, settlement dates and merchant IDs for a user over a given period.

Parameters

Name Description
status Out parameter that contains the result status
dateFrom Returns all batches from and including dateFrom.
dateTo Returns all batches up to and including dateTo.

GetLatestSettlementRunNumber

Summary
Returns the most recent settlement run number the user has access to. If run number could not be retrieved, either not found or an error occured, -1 is returned.

Parameters

Name Description
status Out parameter that contains the result status

Debit Cards

Only for the domestic Icelandic market. For other markets the debit card transactions are returned with credit card transactions. To differentiate between the two look at CreditCardTransaction.CardType.

GetSettlementsByMerchant

Summary
Returns all debit card settlements for a given merchant ID over a time period.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contract number) issued by Borgun
dateFrom Returns all settlements from and including dateFrom.
dateTo Returns all settlements up to and including dateTo.
merchantSSN Optional. Identification number of company, joins together multiple merchantIDs.

GetBatchesByMerchant

Summary
Return all debit card batches for a given merchant ID over a time period.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contract Number) issued by Borgun
dateFrom Returns all batches from and including dateFrom.
dateTo Returns all batches up to and including dateTo.
merchantSSN Optional. Identification number of company, joins together multiple merchantIDs.

###GetTransactionsByBatch### Summary
Returns all debit card transactions for a given batch.
Batch data for the parameters can be retrieved by method GetBatchesByMerchant.

Parameters

Name Description
status Out parameter that contains the result status
merchantID Merchant ID (Contract Number) issued by Borgun
batchNumber The batch number to get transactions in
reconsiliationDate The reconsiliation date of the batch

Appendix 1

Deduction items

Below is a list of common deduction items.

Deduction code Text example Description
ÁLAGDEBK Álag á debetkort Debit card fee
ÁLAGKREK Álag á erl.kreditkort International credit card fee
FÆRSLUGJ Færslugjald Transaction fee
STMTFEE Uppgj. og útskriftargjald Settlement fee
UMBLAMX v/Amex y kr*x% Amex commission
UMBLJBC v/JCB y kr*x% JCB commission
UMBLMCI v/MCI y kr*x% MasterCard commission
UMBLVIS v/VISA y kr*x% VISA commission
UMBLVISINTER Commission VISA y*x% Visa commission
UMBTVSCOM Com VISA Commerc y*x% Visa credit card commercial
UMBTVSKRECON Com VISA Credit Cons y*x% Visa credit card consumer
UMBUMCCRCMDO MC Cred Comm Domestic y*x% MC credit card commercial domestic
UMBUMCCRCMND MC Cred Comm None-Dom y*x% MC credit card commercial non-domestic
UMBUMCDEND MC Deb None-Dom y*x% MC debit non-domestic
UMBUVSCRCMDO VISA Cred Comm Domestic y*x% Visa credit commercial domestic
UMBUVSDEDO VISA Deb Domestic y*x% Visa debit domestic
UMBSMCIINTER Service Fee MC Inter Region
UMBSMCIINTRA Service Fee MC Intra Region
UMBSMCIDDOM Com MC Domestic y*x% MC credit card domestic
UMBSVISINTER Service Fee VISA Inter Region
UMBSVISINTRA Service Fee VISA Intra Region
UMBSVISDOM Þjónustugjald innlendra VISA korta Visa domestic commission
UMBTMCKRECON Service fee MC Credit Consumer
UMBTVSDEBCON Service fee VISA Debit Consumer
UMBTMCCOM Com MC Commerc y*x% MC credit card commercial
UMB2VISKRK Commission VISA y*x% Commission VISA
UMB2VISELT Commission Electron y*x% Commission Visa Electron
UMB2MCIKRK Commission MC y*x% Commission MasterCard
UMB2DEBMST Commission Maestro y*x% Commission Maestro
UMBUVSDEND VISA Deb None-Dom y*x% Commission Visa debit, non-domestic
UMBUVSCRCNND VISA Cred Consum None-Dom y*x% Visa credit card consumer non-domestic
UMBUVSCRCNDO VISA Cred Consum Dom y*x% Visa credit card consumer domestic
UMBUVSCRCMND VISA Cred Comm None-Dom y*x% Visa credit card commercial non-domestic
UMBUMCDEDO MC Deb Domestic y*x% Service fee, MC debit domestic
UMBUMCCRCNND MC Cred Consum None-Dom y*x% Service fee, MC credit card consumer non-domestic
UMBUMCCRCNDO MC Cred Consum Domestic y*x% Service fee, MC credit card consumer domestic
CHARGEBACK Chargeback Chargeback deducted from settlement
BRTLEIÐR Endurkrafa Corrections, can be a refund to card holder, batch transfer, incorrect card number in payment file etc. Text field contains a more detailed explanation
GÍRÓ Afsláttur v/ekorta Miscellaneous fees calculated during card holder billing run. Text field contains a more detailed explanation
VIÐSKF Flutt frá fyrra yfirliti Business transactions, usually manual corrections
DCC DCC þóknun 1.0% Dynamic currency conversion fee
REIKNGJ Setup fee Account setup fee
AUTDECL Declined Fee
RESVENDGR Reserved released from
CHARGEFEE Chargeback fee
RESERVED Reserved Reserved amount
UMBAMCCITER Service fee MC Commecial Inter
UMBAMCCITRA Service fee MC Commecial Intra
UMBAMCDITER Service fee MC Debet Consumer Inter
UMBAMCDITRA Service fee MC Debet Consumer Intra
UMBAMCKITER Service fee MC Credit Consumer Inter
UMBAMCKITRA Service fee MC Credit Consumer Intra
UMBAVSCITER Service fee VISA Commecial Inter
UMBAVSCITRA Service fee VISA Commecial Intra
UMBAVSDITER Service fee VISA Debet Consumer Inter
UMBAVSDITRA Service fee VISA Debet Consumer Intra
UMBAVSKITER Service fee VISA Credit Consumer Inter
UMBAVSKITRA Service fee VISA Credit Consumer Intra
UMBCMCCDOM Service fee MC Commecial Domestic
UMBCMCCITER Service fee MC Commecial Inter
UMBCMCCITRA Service fee MC Commecial Intra
UMBCMCDDOM Service fee MC Debit Consumer Domestic
UMBCMCDITER Service fee MC Debit Consumer Inter
UMBCMCDITRA Service fee MC Debit Consumer Intra
UMBCMCKDOM Service fee MC Consumer Credit Domestic
UMBCMCKITER Service fee MC Credit Consumer Inter
UMBCMCKITRA Service fee MC Credit Consumer Intra
UMBCVSCDOM Service fee VISA Commecial Domestic
UMBCVSCITER Service fee VISA Commecial Inter
UMBCVSCITRA Service fee VISA Commecial Intra
UMBCVSDDOM Service fee VISA Consumer Debit Domestic
UMBCVSDITER Service fee VISA Debit Consumer Inter
UMBCVSDITRA Service fee VISA Debit Consumer Intra
UMBCVSKDOM Service fee VISA Consumer Credit Domesti
UMBCVSKITER Service fee VISA Credit Consumer Inter
UMBCVSKITRA Service fee VISA Credit Consumer Intra
SWIFT SWIFT SWIFT payment fee
RESERVEDNET Reserved payment x% Reserved payment
REFUND Refund Fee x*y Refund Fee
TRANSFEE Authorization Fee x*y Authorization Fee

Appendix 2

Card types

Below is a list of card types with a code representing each type. Each transaction is labeled with a card type code.

Code prefix D indicates the transaction being a debit card transaction, so D03 would be a debit card from MasterCard, D04 a debit card from Visa etc.

Code Card type
01 Domestic Issuers (Iceland only)
03 MasterCard
04 VISA
06 UPI (Union Pay International)
H UPI (Union Pay International)
07 JCB
J JCB
08 American Express
X American Express
10 Diners
C Diners
MD Icelandic MasterCard

Appendix 3

Transaction Types

Below is a list of transaction types and their descriptions.

Transaction Type Description
C Unmanned cash advance ATM/POS
F Iceland domestic only (Framlag)
P POS transaction
5 Retail sales (i. Handskráð)
6 Credit transaction
7 Cash advance
8 Unique transaction
9 ATM Cash disbursement
B Recurring payment
L Iceland domestic only (Léttgreiðslur)
E Iceland domestic only (Raðgreiðslur)