Consumer Loans API
Version 2.1.2.1680

Introduction

This document describes the structure of SaltPay'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 SaltPay (SaltPay 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 SaltPay for access information at help@saltpay.co 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 SaltPay 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.

SaltPay UI Integration

Customer is redirected to SaltPay 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 SaltPay 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.

Returns

Returns run status in object of type ResultStatus.

SaltPay 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 SaltPay 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 SaltPay 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 SaltPay 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.

CancelOnlineLoan

Summary

Cancel online loan progress by setting status as CANCELED. Progress can only be canceled if status is CREATED or INPROGRESS.

Parameters

Field	Type	Description
token	string	Authentication token from CreateOnlineLoanToken or CreateOnlineLoanTokenSMS.
merchantNumber	string	The merchant ID.

Returns

Returns run status in object of type ResultStatus.

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.
INPROGRESS	Token has been used and borrower is in loan progress.
PENDING	Loan authorization is in progress
PROGRESSEXPIRED	Loan progress is expired and loan can not be created.
TOKENEXPIRED	Token expired before used
SUCCESS	Loan has been succesfully validated.
FAILED	Loan could not be validated.
CANCELED	Borrower or pos 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 SaltPay 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.