Documentation

Borgun, all rights reserved. 2017 ©

Updated 30.01.2017


Consumer Loans API
Version 2.0.1205

Introduction

This document describes the structure of Borgun's consumer loan Web service which enables merchants to offer consumer loans through a simple process. The process includes validation of customers, creating a payment schedule and creating the loan contract. Merchants can implement the loan process by either creating their own user interface (Merchant UI Integration) or use an interface provided Borgun (Borgun UI Integration).

Environments

Loan Service is WCF SOAP service and communication between client and server needs to be HTTPS and encrypted with TLS 1.1 or TLS 1.2. A username and password with access to Loan Service is required to use the service. It is advised to enable end user identification by submitting employee ID to the service. See CreateLoanContract. A test service is available for use while client is being implemented. After implementation phase the test URL and account information can be replaced with production data.

Contact Borgun for access information at borgun@borgun.is or 560 1600.

Usages

A simple example of usage is a merchant eCommerce website where customer pays for products by a personal consumer loan.

Merchant UI Integration

The following steps would be taken to service a loan to a customer.

  1. Call the GetLoanContractTypes functions to receive available loan types. Could allow the customer to choose from different types of loans (with or without interests) but usually merchant are fixed on a single loan type.
  2. Show loan information such as a payment plan to customer by calling the GetLoanCalculation function and display the results. This can be done by using a fixed number of payments (e.g. 12 months) or allow the customer to choose from a different range of payments. The GetFewestMonthsAvailable function would be utilized then to filter out months where APR is above the maximum allowed rate.
  3. The final thing is to create a loan contract by calling the CreateLoanContract that create a Borgun consumer loan.

Under some circumstances a merchant need to void a loan (e.g. customer returning a product). Loan can by voided by calling the VoidLoanContract function.

Borgun UI Integration

Customer is redirected to Borgun Consumer Loan web for the loan process. A detailed description of the process can be found here

POS Integration

POS pre-registers loan info and customer receives a SMS with URL that grants him access to Borgun Consumer Loan web for the loan process. A detailed description of the process can be found here

API

Merchant UI Integration Methods

CreateLoanContract

Summary

Creates and finalizes the contract.

Parameters

Field Type Description
merchantNumber string The merchant ID.
loanTypeId int Loan contract type id from GetLoanContractTypes.
amount decimal Loan amount.
numberOfPayments int Number of payments.
firstPaymentDate DateTime Date of first payment (2d m+1, if on or past 14th day of month 2d m+2).
monthsBetweenPayments int Number of months between payments, usually 1.
salesPerson string Employee/end user handling the sale.
contractDescription string Description of contract, usually a short description of items being bought.
socialSecurityNumber string Social security number of cardholder.
customerAddress string Address of cardholder.
customerCity string City of cardholder.
customerPostalCode string Postal code of address (e.g. 101).
customerCountryCode string Country code (e.g. IS, UK).
customerPhoneNumber string Cardholder phone number.
customerCreditCardNumber string Cardholder credit card number.
customerCardExpirationDate string Card expiration date (YYMM).
customerCardCVC string CVC on credit card.
cardholderIdentityConfirmed bool Employee confirmation that he/she has confirmed the identity of cardholder by examining identification card of some sort.
errorLanguage string Error language (e.g. IS, EN).
status ResultStatus Output parameter for run result.

Returns

Returns object of type LoanContract.

GetFewestMonthsAvailable

Summary

Calculates the fewest months a loan can be divided to given the precondition before APR becomes too high according to EU regulations. Returns -1 if no available month is applicable.

Parameters

Field Type Description
principal decimal The loan amount.
firstPayment DateTime Date of first payment (2d m+1, if past 14th day of month 2d m+2).
loanTypeId int Loan contract type id from GetLoanContractTypes.
merchantNumber string The merchant ID.
status ResultStatus Output parameter for run result.

Returns

Returns primitive type integer.

GetLoanCalculation

Summary

Calculates payment schedule and costs.

Parameters

Field Type Description
merchantNumber string The merchant ID.
loanTypeId int Loan contract type id from GetLoanContractTypes.
amount decimal Loan amount.
numberOfPayments int Number of payments.
firstPaymentDate DateTime Date of first payment (2d m+1, if past 14th day of month 2d m+2).
monthsBetweenPayments int Number of months between payments, usually 1.
status ResultStatus Output parameter for run result.

Returns

Returns object of type LoanCalculation.

GetLoanContractsByDate

Summary

Retrieves all loan contracts created by the authenticated user for a given time period, no longer than one month.

Parameters

Field Type Description
fromDate DateTime Get loans created after this date.
toDate DateTime Get loans before this date.
status ResultStatus Output parameter for run result.

Returns

Returns a list of objects of type ConsumerLoan.

VoidLoanContract

Summary

Voids a contract previously created with CreateLoanContract method.

Parameters

Field Type Description
contractNumber int Unique ID for the loan contract.
employeename string Name of person voiding the contract.
merchantNumber string The merchant ID.
status ResultStatus Output parameter for run result.

Returns

Returns nothing.

Borgun UI Integration Methods

GetPaymentMethods

Summary

Get a list of available payments methods. Returns empty list if all payments options calculation is above allowed APR.

Parameters

Field Type Description
amount decimal Loan amount.
merchantNumber string The merchant ID.
status ResultStatus Output parameter for run result.

Returns

Returns a list of objects of type PaymentMethodInfo.

CreateOnlineLoanToken

Summary

Generates a token that allows temporary access to Borgun consumer loan website for eCommerce customers to self service credit card loans.

Parameters

Field Type Description
onlineLoan OnlineLoan The online loan information.
customerInfo CustomerInfo The customer information.
status ResultStatus Output parameter for run result.

Returns

Returns token as primitive type string.

CreateOnlineLoanTokenSMS

Summary

Sends a SMS with generated URL allows temporary access to Borgun consumer loan website for eCommerce customers to self service credit card loans.

Parameters

Field Type Description
onlineLoan OnlineLoan The online loan information.
phoneNumber string Customer mobile phone number.
urlValidMinutes int How long URL that customer receives in SMS is valid.
progressValidMinutes int How long customer has to finish loan process before it times out.
status ResultStatus Output parameter for run result.

Returns

Returns token as primitive type string.

ValidateOnlineLoan

Summary

Validates that an eCommerce customer has created an online loan during checkout process.

Parameters

Field Type Description
token string Authentication token from CreateOnlineLoanToken or CreateOnlineLoanTokenSMS.
redirectUrl string Customer redirect URL from Borgun consumer loan website.
merchantNumber string The merchant ID.
status ResultStatus Output parameter for run result.

Returns

Returns object of type ConsumerLoan if loan is valid.

CheckOnlineLoanStatus

Summary

Returns a status code for customer online loan progress.

Parameters

Field Type Description
token string Authentication token from CreateOnlineLoanToken or CreateOnlineLoanTokenSMS.
merchantNumber string The merchant ID.
status ResultStatus Output parameter for run result.

Returns

Returns one of following status code as primitive type string.

Status Code Description
CREATED Loan access as been created.
TOKENEXPIRED Loan access has expired.
INPROGRESS Token has been used and borrower is in loan progress.
PROGRESSEXPIRED Loan progress is expired and loan can not be created.
SUCCESS Loan has been succesfully validated.
FAILED Loan could not be validated.
CANCELED Borrower canceled the loan process.

Helper Methods

GetLoanAdvert

Summary

Calculates key information for consumer loan to be displayed on merchant website for advertising purpose for products.

Parameters

Field Type Description
amount decimal The loan amount
loanTypeId int Loan contract type id from GetLoanContractTypes.
numberOfPayments int Number of payments the loan is divided into.
merchantNumber string The merchant ID.
status ResultStatus Output parameter for run result.

Returns

Returns object of type LoanAdvert.

GetLoanContractTypes

Summary

Get a list of contract types.

Parameters

Field Type Description
merchantNumber string The merchant ID.
status ResultStatus Output parameter for run result.

Returns

Returns a list of objects of type LoanContractType.

Objects

ResultStatus

All methods have a ResultStatus output parameter containing ResultCode, ResultText and ErrorMessage describing the result.

ResultCode ResultText ErrorMessage
0 Success NULL
20 Warning e.g., Annual cost ratio to exceeds limit.
30 Error e.g., User doesn't have access.

LoanCalculation

Field Type Description
APR double Annual percentage rate.
InterestRate decimal Loan interest rate.
InterestType string Type of interests, can be fixed or floating.
LoanFee decimal Loan fee.
NumberOfPayments int Loan payment count.
TotalPaymentAmount decimal Total amount to be paid.
Totalinterest decimal Total interest amount to be paid.
TotalFees decimal Total fee amount to be paid.
TotalAmount decimal Total amount to be paid.
Payments List List of itemized payments to be paid.

LoanContract

Field Type Description
ContractNumber int Unique ID for the loan contract.
AuthorizationNumber string The authorization number received in the credit card authorization process.
LegalTerms string The terms the customer agreed to when taking the loan, may be different between loans.
LoanCalculation LoanCalculation Payment details for loan contract.
LoanApplicationEvaluation LoanApplicationEvaluation Loanevaluation outcome, status and description.

LoanApplicationEvaluation

When CreateLoanContract is called it returns the loan application evaluation, success or failure.

Code Description
0 NULL
101 Borrower must be at least 18 years old.
102 Borrower must have an Icelandic identification number.
201 Prepaid cards are not allowed.
202 Only Icelandic credit cards are allowed.
203 Creditcard not authorized.
301 Cardholder did not pass loan authorization, contact Borgun for further information.
302 Borrower already has the maximum number of allowed loans.
303 Borrower has exceeded the allowed loan amount total.
304 Annual percentage rate goes over the allowed 50% mark.
401 User is not connected to this merchant number.
501 Unexpected error.
601 Loan authorization check in progress for this identification number.

LoanContractType

Field Type Description
LoanTypeId int Unique ID of loan contract type.
Name string Name of contract type.
MinNumberOMonths int Minimum number of months a loan of this type can be divided to.
MaxNumberOfMonths int Maximum number of months a loan of this type can be divided to.
MaxPaymentDelay int Maximum delay of first payment.
MaxAmount int Maximum amount for a loan of this type.
MaxPaymentinterval int Maximum number of months between installments.

ConsumerLoan

Field Type Description
ContractNumber int Loan contract number.
CreatedAt DateTime Create time of loan contract.
LoanType string Name of loan type.
SSN string Id number of customer/cardholder.
BorrowerName string Name of the person taking the loan.
Amount int Loan amount.
CardType string Type of credit card used, Amex, MasterCard, Visa.
CreatedBy string User creating the loan.
Employee string ID of end user/employee.
Status string Current state of loan, e.g. new, voided, bought.
Terms string The terms the customer agreed to when taking the loan, may be different between loans.
MerchantNumber string The merchant number in question.
MerchantName string Name of merchant.
AuthorizationNumber int Number of card authorization.
IssueDate DateTime Issue date of loan.
CardNumber string Credit card number to be charged.
CardTypeName string Type of credit card (Amex, MasterCard, Visa).
CustomerAddress string Street address of customer.
CustomerCity string Customer home city.
CustomerZipCode int Customer zip code.
CustomerPhonenumber string Customer mobile number, may be used when authenticating the cardholder.
Description string Purchase information.
APR decimal Annual percentage rate.
interestRate decimal Loan interest rate.
interestType string Type of loan interest.
LoanCharge decimal Cost of taking a loan.
TotalAmountText string Total amount to be paid in text for displaying on loan contract.
FirstPaymentDate DateTime Date of first payment, must be no sooner than 1. or 2. day of next month and one month later if loan contract is created late in the month.
Payments Payment[] List of itemized payments to be paid.
NumberOfPayments int Payment count.
TotalPaymentAmount decimal Total amount to be paid.
Totalinterest decimal Total interest amount to be paid.
TotalFees decimal Total fee amount to be paid.
TotalAmount decimal Sum of all total amounts to be paid.
TotalLoanCost decimal Total additional cost to be paid (fees + interest + charge).
interestRateType string Type of interests, can be fixed or floating.
FullAddress string Full address in one string.

Payment

Field Type Description
Number int The payment number, starting at 1.
PaymentDate DateTime Due date of payment.
Amount decimal Loan amount to be paid.
Interest decimal interest amount to be paid.
Fee decimal Fee amount to be paid.
TotalAmount decimal Total amount to be paid (Amount + Interest + Fee).

LoanAdvert

Field Type Description
AprRatio decimal Annual percentage rate.
InterestRate decimal Loan interest rate.
InterestType string Type of interests, can be fixed or floating.
LoanFeeRate decimal Loan fee percent rate.
NumberOfPayments int Loan payment count.
TotalPayment decimal Total amount to be paid.
Amount decimal Loan principal amount.
PaymentFee decimal Loan payment fee.
AveragePayment decimal Loan average amount per payment.
Created DateTime Loan creation date.
FirstPayment DateTime Loan first payment date.
LastPayment DateTime Loan last payment date.

PaymentMethodInfo

Field Type Description
LoanTypeId int Unique ID of loan contract type.
MaxNumberOfPayments int Maximum number of payments allowed for payment method.
PaymentName string Name of payment method.
PaymentInfo string Information about payments.
LogoUrl string Raðgreiðslur logo URL.

OnlineLoan

Field Type Description
MerchantNumber string The merchant number in question.
LoanTypeId int Loan contract type id from GetLoanContractTypes.
Amount decimal Loan amount.
Description string Product description.
NumberOfPayments int The number of payments for the loan.
FlexibleNumberOfPayments bool Allow customer to choose number of payments lower or equal to submitted value of NumberOfPayments. Can never be lower than the APR minimum.
SuccessUrl string Redirect URL for loan that was successfully created.
CancelUrl string Redirect URL if customer decides not to go ahead with the loan.

CustomerInfo

Field Type Description
NationalRegistryId string Customer national registry id.
Name string Customer full name.
Address string Customer address.
PostalCode string Customer postal code.
City string Customer city.
PhoneNumber string Customer phone number.
Email string Customer email.

Code Examples

C# code example

Web.Config settings.

...
<basicHttpBinding>
    <binding name="BasicHttpBinding_IConsumerLoans" openTimeout="00:00:10" closeTimeout="00:00:10" sendTimeout="00:01:00" maxReceivedMessageSize="2147483647">
        <security mode="Transport">
        <transport clientCredentialType="Basic" proxyCredentialType="None" realm=""/>
        <message clientCredentialType="UserName" algorithmSuite="Default"/>
        </security>
    </binding>
</basicHttpBinding>
...
<endpoint address="https://test.borgun.is/clapi/v1/clservice.svc" binding="basicHttpBinding"
 bindingConfiguration="BasicHttpBinding_IConsumerLoans" contract="clapi.IConsumerLoans" name="BasicHttpBinding_IConsumerLoans"/>
...

Client connection example and calling the GetLoanAdvert function.

var client = new LoanService.LoanServiceClient();

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

var status = new LoanService.ResultStatus();

decimal amount = 59995;
int loanTypeId = 24;
string merchantNumber = "1234567";

var loanAdvert = client.GetLoanAdvert(principal, loanTypeId, 12, merchantNumber, out status);

foreach (PropertyDescriptor descriptor in TypeDescriptor.GetProperties(loanAdvert))
{
    string name = descriptor.Name;
    object value = descriptor.GetValue(loanAdvert);

    Console.WriteLine("{0}={1}", name, value);
}

PHP code example

Client connection example and calling the CreateOnlineLoanToken function.

$onlineLoan = new StdClass();
$onlineLoan->MerchantNumber = "1234567";
$onlineLoan->LoanTypeId = 24;
$onlineLoan->Amount  = 50000;
$onlineLoan->Description = "Test loan";
$onlineLoan->NumberOfPayments = 12;
$onlineLoan->FlexibleNumberOfPayments = true;
$onlineLoan->SuccessUrl = 'https://www.bwebstore.is/CheckoutComplete?transactionId=a4c5gd64lod5';
$onlineLoan->CancelUrl = 'https://www.bwebstore.is/Shoppinghart';
$onlineLoan->RequireIdentification = true;

$customerInfo = new StdClass();
$customerInfo->NationalRegistryId = "1234537809";
$customerInfo->Name = "Jón Borgunarson";
$customerInfo->Address = "Ármúla 30";
$customerInfo->PostalCode = "108";
$customerInfo->City = "Reykjavík";
$customerInfo->PhoneNumber = "1234567";
$customerInfo->Email = "radgreidslur@borgun.is";

try 
{
    $soap_options = array('encoding' => 'utf-8', 'login' => 'loginname', 'password' => 'loginpassword', 'uri' => 'https://test.borgun.is/clapi/v1/clservice.svc');
    $webservice = new SoapClient('theWSDL loaction', $soap_options);

    $token = $webservice->CreateOnlineLoanToken(array('loanInfo' => $onlineLoan, 'customer' => $customerInfo));    
    echo $token;

    $result = $token->status->resultCode;
    echo $result;

    $errorMsg = $token->status->errorMessage;
    echo $errorMsg;
} 
catch (SOAPFault $f) 
{
    echo $f;
}

Note: This code is only for demonstration purposes.

Version History

Version 1.0.25940 - December 2016

  • Added new method GetPaymentMethods
  • Performance improvements
  • Minor bug fixes

    Version 1.0.25499 - July 2016

  • Support for Merchant Integrated Loans and Borgun Integrated Loans
  • Authorization roles added
  • Improved logging
  • Bug fixes