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; 
}