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.
- Flat file upload. Supported file formats are MCI10, UFUK, VISA (documentation in Icelandic).
- 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;
}