Documentation

Borgun, all rights reserved. 2017 ©


Release notes for latest version

Replacement card service (Icelandic)

Introduction

This document describes Payment Upload WCF service provided by Borgun. The user must be supplied with username and password and be granted access to the payment upload functionality to make use of the service. The service encapsulates all existing payment upload routes provided by Borgun and will replace the current interfaces over time.

  1. Flat file upload. Supported file formats are MCI10, UFUK, VISA (documentation in Icelandic).
  2. XML batch upload.

Environments

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

The following merchant contract ID / Processor ID can be used while testing.

Merchant ID: 9256684

Processor ID: 8006666

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

Lastest service URLs

Test:
https://test.borgun.is/paymentupload/paymentupload.svc
Production:
https://services.borgun.is/paymentupload_2_1/paymentupload.svc

Available Services

Method name Description
UploadPaymentsXml Upload recurring payments with XML form for processing
UploadPaymentsFlatFile Upload flat file containing recurring payments for processing
GetUploadStatus Check recurring payment processing
GetUploadReport Get a list of processed transactions.
GetUploadReportByDate Get a list of processed transactions.
GetVirtualCardNumber Convert an actual credit card number to a virtual card number.
GetCardInfo Get information about the credit card type, status, issuer etc.

The services can be grouped into the following usage categories

  • XML payment upload
    If there is no pre-existing upload then the XML payment upload is the preferred and fastest way to implement a payment upload. The call sequence used is as follows UploadPaymentsXml (transfer payment to processing) GetUploadStatus (Watch status of processing) GetUploadReport (Fetch transactions)
  • Flat file upload Supports older payment file formats. The call sequence used is as follows UploadPaymentsFlatFile (transfer payment to processing) GetUploadStatus (Watch status of processing) GetUploadReport (Fetch transactions)
  • Card Information PCI compliance can be simplified greatly by storing virtual card numbers at the merchant side rather than real card numbers. GetVirtualCardNumber converts card numbers to virtual card numbers that can be used in payment transfers.

Service documentation

Objects

ResultStatus object

Each service call takes in a ResultStatus parameter that, after the execution, contains the run result of the call. The actual data is returned either as an XML string, a string or an object list.

ResultCode ResultText ErrorMessage
0 Success NULL
10 Informational e.g. User does not have access
20 Warning Warning message
30 Error Error message

UploadedTransaction object

Field Type Description
BatchNumber String Unique number of the batch
CardNumber String Credit card number charged
Date String Date of upload
Time String Time of upload (if applicable)
Amount Decimal The amount charged
CurrencyCode String The currency code of the payment
SlipNumber String Transaction slip number
IsDeclined Bool True if the transaction was rejected
NewCardNumber String Updated credit card number of the customer. Clients need to update their local systems with this new card number to avoid rejections in the future.
TextReason String Reason for rejection or empty if valid transaction

CardInfo object

Field Type Description
Cardnumber String Credit card number
PaymentType String Possible types:
B = charge
C = credit
P = plus
D = debit
PaymentTypeText String Text accompanying the type
CardStatus String Card status, e.g. closed *
IssuingBank String Bank code of issuer *
IssuerName String Name of issuer *
DomesticOnly Boolean True if only domestic use is allowed *
CardScheme String Name of card scheme and issuing country, if no country is specified the card is Icelandic
CardnumberLength Int Length of card number, usually 15 or 16 digits
CardDescription String Name of credit card type, gold, silver, platinum etc.
InstallmentsAllowed Boolean True it is allowed to charge installments to the card *
RecurringAllowed Boolean True if it is allowed to charge recurring payments to the card *
ReplacementCard String If the given card number has been closed and a new card number is available otherwise empty
MaskedCardNumber String The masked creditcard number, applicable when merchant uses virtual numbers

✱ For cards not issued by Borgun (on behalf of issuing bank), this information is not available. String values will be empty or contain "Unknown" and boolean values will be false.

TransferStatus object

Field Type Description
DateUploaded DateTime Date when the payment list was uploaded
OriginalFileName String Name of the file that was uploaded (if flatfile is used)
ReferenceTicket String Unique reference of the payment list
ProcessingStatus String Processing status of a payment list, see Upload file status codes for details
StatusText String Processing status text description
ProcessingCompleted Boolean True if the payment list has been processed
Processor String Processor ID
TotalAmount Double Total transaction amount
TotalNumberOfTransactions Int Number of transactions received
TransmissionDate DateTime Date of transmission
TransmissionSequenceNumber String Unique sequence number of transmission

Upload file status codes

Code Description
1210 Payment transmission is waiting to be processed
2620 Payment transmission successfully processed
3210 Payment transmission denied, missing required information
3220 Payment transmission denied, duplicate sequence number found
3510 Payment transmission denied, format error in data
3520 Payment transmission denied, please contact Borgun
3550 Payment transmission deleted

Upload functionality

UploadPaymentsXml

Summary

Upload an XML document containing payment for pr that can be used to poll status information later.

Parameters

Name Description
Status Out parameter for run result
Xml XML batch to process, see chapter on XML data

UploadPaymentsFlatFile

Summary

The file content is sent to Borgun to be processed and charged. The call returns a unique reference that can be used to poll status information later.

Parameters

Name Description
Status Out parameter for run result
Filename The name of the file, for reference
fileStream The content of the file to process

GetUploadStatus

Summary

Query the processing status of a previously uploaded payment list. Returns a TransferStatus object.

Parameters

Name Description
Status Out parameter for run result
Ticket A unique reference ticket returned by UploadPaymentsFlatFile to query the status

GetUploadReport

Summary

Get a list of transactions from a processed payment list. The list marks rejected transactions to be specially handled by client. Returns a list of UploadedTransaction objects.

Parameters

Name Description
status Out parameter for run result
ticket A unique reference ticket returned by UploadPaymentsFlatFile to query the status
merchantContract The merchant ID number

GetUploadReportByDate

Summary

Retrieve same information as GetUploadReport but by different parameters. Useful if, e.g. connection problems occur and no unique reference is received. Returns a list of UploadedTransaction objects.

Parameters

Name Description
Status Out parameter for run result
processorId The processor ID in the batch XML
transmissionDate Date of transmission
transmissionSequenceNo Transmission sequence number

Card Information functionality

GetVirtualCardNumber

Summary

Convert a credit card number to a virtual number that can be stored and referenced. Returns a virtual card number.

Parameters

Name Description
status Out parameter for run result
cardNumber The credit card number to convert to a virtual card number
merchantNumber The number of the merchant requesting the virtual number

GetCardInfo

Summary

Basic information about a credit card, such as the type, issuer etc. If a card has been re-issued or otherwise replaced a new card number is returned. Card may exists and be valid even if ResultCode is 10 (no data found), since Borgun does not have information on all issued cards. For Icelandic debit cards, the property CardInfo.PaymentType is set to D even though other card information is not available. For other card payment types the property is left empty if the information isn’t available. Returns a CardInfo object.

Parameters

Name Description
status Out parameter for run result
cardNumber The credit card number to get basic information for, can be actual cardnumber or a virtual cardnumber
merchantNumber This field is only required if cardNumber is virtual number, it can left blank for actual card numbers.
safe If set to true card numbers are returned masked with only first 6 and last 4 digits visible.

XML data format

Column explanations

M/O columns

M = Mandatory

O = Optional

Exponential column

0 = Numeric field, 0 implied decimals, with 0 as a filler

2 = Numeric field, 2 implied decimals, with 0 as a filler

Payment Batch request

H1 Header record

TransmissionDate and TransmissionSeqNumber are unique for sender

Field Length Exp M/O Description
TransmissionDate 8 M Yyyymmdd
TransmissionTime 6 M hhmmss
ProcessorId 7 0 M Merchant ID
TransmissionSeqNumber 4 M Sequence number of transmission, supplied by and stored by sender to later be able to query upload status.
TransmissionTestflag 4 M Test flag
“PROD” = Production
“TEST” = Test

B1 Batch record

There are one or more batches within one transmission.

Field Length Exp M/O Description
MerchantId 7 0 M If no categorization of payment is used then merchant ID is the same as processor ID in header record.
BatchNumber 7 0 M Must be unique within the day for the merchant
StoreNumber 4 0 O Store number
PosNumber 4 0 O POS number
CurrencyCode 3 M Alpha currency code, e.g. “ISK” for Icelandic krona. All transactions in a batch must have the same currency.
BatchReference 25 O Reference number for merchant

F1 Transaction record

There are one or more transactions within each batch.

Field Length Exp M/O Description
CardNumber 19 M Credit card number
TransactionDate 8 0 yyyymmdd
TransactionTime 6 0 hhmmss
Amount 11 2 M Amount with digits included, 12.34 is sent as 1234
CardDataInput 1 M ‘D’=Card swiped
‘T’ = Manually entered
For recurring transactions the value should be ‘T’
CardDeviceType 1 M ‘P’ = POS
‘A’ = ATM
‘B’ = Recurring
‘N’ = Manual
This value should be ‘B’ except under special circumstances.
TransactionType 2 0 M 01 = Sale
03 = Cash adv.
04 = ATM
09 = Credit
AuthorizationType 1 0 O 0 = Has not been authorized
1 = Approved online
3 = Within floor limits
4 = Reserved
5 = Reserved
AuthorizationNumber 6 O All blanks if AuthorizationType is 0
SlipNumber 7 0 M Slip number
ExpDate 4 O Card expiry date in YYMM format.

Example

<?xml version="1.0" encoding="UTF-8"?>
<H1>
    <TransmissionDate>20081205</TransmissionDate>
    <TransmissionTime>151617</TransmissionTime>
    <ProcessorId>9111111</ProcessorId>
    <TransmissionSeqNumber>001</TransmissionSeqNumber>
    <TransmissionTestflag>TEST</TransmissionTestflag>
    <B1>
        <MerchantId>9111111</MerchantId>
        <BatchNumber>000001</BatchNumber>
        <StoreNumber></StoreNumber>
        <PosNumber></PosNumber>
        <CurrencyCode>ISK</CurrencyCode>
        <F1>
            <CardNumber>9352400949429010</CardNumber>
            <TransactionDate>20081125</TransactionDate>
            <TransactionTime>151617</TransactionTime>
            <Amount>200</Amount>
            <CardDataInput>T</CardDataInput>
            <CardDeviceType>B</CardDeviceType>
            <TransactionType>01</TransactionType>
            <AuthorizationType>0</AuthorizationType>
            <AuthorizationNumber></AuthorizationNumber>
            <SlipNumber>325607</SlipNumber>
            <ExpDate>1301</ExpDate>
        </F1>
    </B1>
    <B1>
        <MerchantId>9333333</MerchantId>
        <BatchNumber>000002</BatchNumber>
        <StoreNumber></StoreNumber>
        <PosNumber></PosNumber>
        <CurrencyCode>ISK</CurrencyCode>
        <F1>
            <CardNumber>9352400948625014</CardNumber>
            <TransactionDate>20081104</TransactionDate>
            <TransactionTime></TransactionTime>
            <Amount>469200</Amount>
            <CardDataInput>T</CardDataInput>
            <CardDeviceType>B</CardDeviceType>
            <TransactionType>01</TransactionType>
            <AuthorizationType>0</AuthorizationType>
            <AuthorizationNumber></AuthorizationNumber>
            <SlipNumber>6000059</SlipNumber>
        </F1>
    </B1>
</H1>

Example Test Procedure

Test card numbers

Cardnumber Expected result
5587402000012001 Card number does not pass validation using the Luhn algorithm. Will not receive virtual card number.
5414830000000009 Transactions made with this card number, or it’s virtual card number, will be denied with “Invalid card number”.
5414830037608105 Transactions made with this card number, or it’s virtual card number, will be accepted if the amount is divisible by 100. (f.ex. 200 -> OK, 105 -> Rejected).
5587402000012003 After sending a transaction using this card number it will be replaced with a new card number (5414830037608105). Transactions made with this card number, or it‘s virtual card number, will be accepted if the amount is divisible by 100.
377846029992006 After getting the virtual card number for this card number it will be replaced with a new card number (377846029992014). Transactions made with this card number, or it‘s virtual card number, will be accepted if the amount is divisible by 100.

Test procedure

  • Get virtual card numbers for test card numbers
  • Send transaction records on the four virtual numbers received. -- 3 Transactions should be accepted, 1 rejected. -- For 2 of those transactions the card number should have been replaced.

Code examples

C# code example

PaymentUploadService.PaymentUploadClient client = new PaymentUploadService.PaymentUploadClient();
string referenceTicket = string.Empty;

// Username and password is required to use the service
client.ClientCredentials.UserName.UserName = username;
client.ClientCredentials.UserName.Password = password;

// out parameter
PaymentUploadService.ResultStatus status;
referenceTicket = client.UploadPaymentsFlatFile(out status, "myfile.txt", stream);
if (status.resultCode.Equals("0"))
{
   Console.WriteLine("File uploaded"); 
}
else
{
    Console.WriteLine("File not uploaded, result code: {0}, message: {1}", 
    status.resultCode, status.errorMessage);
}

// Always close the client
client.Close();

C# virtual card example

public string GetVirtualCardNumber(string contract, string cardnumber, out ResultStatus res)
{
    PaymentUploadService.PaymentUploadClient client = new PaymentUploadService.PaymentUploadClient();        
    string virtualCardNumber = string.Empty;        

    // Username and password is required to use the service
    client.ClientCredentials.UserName.UserName = username;
    client.ClientCredentials.UserName.Password = password;

    if (!string.IsNullOrEmpty(contract) && !string.IsNullOrEmpty(cardnumber))
    {
        // clean up the cardnumber
        cardnumber = cardnumber.Replace(" ", "").Replace("-", "");        
        virtualCardNumber = client.GetVirtualCardNumber(out res, cardnumber, contract)
    }

    // Always close the client
    client.Close();

    // the virtual cardnumber is then stored in local database and used as a regular credit cardnumber
    return virtualCardNumber; 
}