Documentation

SaltPay, all rights reserved. 2022 ©

Restful Onboarding Gateway

Introduction

This document describes the structure of SaltPay's Restful Onboarding Gateway which enables affiliates to submit an application for possible future merchants and fetch the status of an submitted applications. To begin with users of this gateway need to implement their own user interface on top of this gateway.

Environments

The Restful Onboarding Gateway is a restful web api. Communication between client and server can only happend over HTTPS. A username and password is required to use the service. User must get a security token from the web api using the username and password. This token must then be passed with all requests made to the web api.

Functionality

TestURL: https://test.borgun.is/Onboarding.API

Operation Route Method
Get Token /token GET
Get Countries /api/helpers/countries GET
Submit Application /api/application/ POST
Get Application Status /api/application/{id}/Status GET
Upload Application Documents /api/application/{id}/file POST
Get Contacts /api/application/{id}/contact GET
Add Contacts /api/application/{id}/contact POST
Add Fees /api/application/{id}/fees POST
Add Equipment /api/application/{id}/equipment POST
Add Note /api/application/{id}/note POST

API reference

API

Get token

To gain access to Restful Onboarding Gateway user must be registered with SaltPay, have a username and password. If a user is registered an access token can be requested from the API. Each time a equest is made to the sever the access token must be present in the header of the HTTP request under header key "Authorization" with the value "Bearer YOURACCESSTOKENKEY".

To get the token this is the HTML code:

POST /token HTTP/1.1
Host: API_URL/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
Postman-Token: dd07869c-b173-3d31-6c9c-3b58bdb1e0ab

grant_type=password&username=YOURUSERNAME&password=YOURPASSWORD

To test in CURL:

curl -X POST -H "Accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "Cache-Control: no-cache" -H "Postman-Token: 5b67d2ea-564a-0e59-39b7-1bafef9971ff" -d 'grant_type=password&username=YOURUSERNAME&password=YOURPASSWORD' "https://API_URL/token"

The API will answere with a JSON that looks something like this:

{
  "access_token": "ivxAfHb0hBxTm-bcaDl4azEhVWwALwpAHoRVzhQqTNmkvCtvAu_yOqilbaTRe95j8NqcfWR305NvSgH6oAEQVUUiwuuvosfFh98IRVeJFTbmpeUvF85W6nHRJsvo9E3GQVS68Wr1s2KEJOs2jVE5QPRF5n_xzsi6sq_33g72sCmJp9ex0qXY02aHWX196rqFB2_inUood6nbVol9nux-ri55vKe9zAAADFYe3szBu-N3qJ-dKAWaCBXEEANOL1vyqPpnfhmslQwUltwAE3HcfQ",
  "token_type": "bearer",
  "expires_in": 3599
}

The "access_token" in the code example above must be put in the header under Authorization. Like in this HTTP code:

GET /api/application HTTP/1.1
Host: API_URL:API_PORT
Authorization: Bearer ivxAfHb0hBxTm-bcaDl4azEhVWwALwpAHoRVzhQqTNmkvCtvAu_yOqilbaTRe95j8NqcfWR305NvSgH6oAEQVUUiwuuvosfFh98IRVeJFTbmpeUvF85W6nHRJsvo9E3GQVS68Wr1s2KEJOs2jVE5QPRF5n_xzsi6sq_33g72sCmJp9ex0qXY02aHWX196rqFB2_inUood6nbVol9nux-ri55vKe9zAAADFYe3szBu-N3qJ-dKAWaCBXEEANOL1vyqPpnfhmslQwUltwAE3HcfQ
Cache-Control: no-cache
Postman-Token: 6e532dc2-8659-6ea8-9ebc-228e531f92ec

To test with curl

Curl example:
curl -X GET -H "Authorization: Bearer ivxAfHb0hBxTm-bcaDl4azEhVWwALwpAHoRVzhQqTNmkvCtvAu_yOqilbaTRe95j8NqcfWR305NvSgH6oAEQVUUiwuuvosfFh98IRVeJFTbmpeUvF85W6nHRJsvo9E3GQVS68Wr1s2KEJOs2jVE5QPRF5n_xzsi6sq_33g72sCmJp9ex0qXY02aHWX196rqFB2_inUood6nbVol9nux-ri55vKe9zAAADFYe3szBu-N3qJ-dKAWaCBXEEANOL1vyqPpnfhmslQwUltwAE3HcfQ" -H "Cache-Control: no-cache" -H "Postman-Token: 3a7ce164-654a-928d-61f2-96fcbaafa303" "https://API_URL:API_PORT/api/application"

We recommend using Postman or similar tool to test.

Get Countries

Returns a list of countries containing name and a two digit ISO code. Example 

{
    "iso": "AF",
    "name": "Afghanistan"
  }

ISO field is supposed to be used when entering name of country.

Submit Application

Fill out the Application object, see API swagger site link. If everything is successful an application ID will be returned. Below is a detailed list of the object required to send in application.

Application

Field Type Explanation
type ApplicationType Type of application
euCompany Company EU company information
nonEUCompanty Company Non EU company information
business Business Information about the business
website Array Website List of websites connected to this application
settlement Settlement Settlement bank account
processing Processing Reason for applying for this merchant account
paymentServiceProvider PaymentServiceProvider Payment service provider in use
warehouseAndShipmentDetails WarehouseProductShipment Warehouse and product shipment details (If applicable, only if physical goods are being sold and delivered)

ApplicationType

Enum: "PreApproval", "Merchant", "PF", "SubMerchant"

Company

Field Type Explanation
registrationNumber string Company registration number
legalName string Legal name of company
registeredTrademark string Trading name (if other than legal name)
totalNumberOfEmployees integer number of employees that work at the company
applyingForTerminal boolean true or false.
applyingForECommerce boolean true or false

Business

Field Type Explanation
startupBusiness boolean true if this is a startup business, else false
timeInBusiness string if this is not a startup business then this field is needed
typeOfBusiness string Type of business
descriptor string Descriptor (DBA or doing business as, max 22 letters, appears on the card statement)
cityField string Customer support phone number (max 13 figures)
acquirer string Previous/current acquirer
monthlySalesVolumes Amount Current monthly sales volume (per currency)
productServiceForSale string Products/Service for sale on website
paymentType string Payment type (Recurring/subscription fee, one-time payment, pay-per minute, pay-per download, etc.)
paymentTime string When does the payment take place? (upon purchase, on delivery, with download, etc.)
threeDSecure ThreeDSecure 3D secure to be used?
processingCurrencies Array Currency array of currency
terminals Array Terminal array of terminals
cardOptions Array Card array of cards
companyTurnover TotalAnnualTurnover Total annual company turnover
cardTurnover TotalAnnualTurnover Total annual card turnover
deposit Deposit Do you take any deposits?
prePayment PrePayment Do you take a full payment for goods/service in advance?
usesAffiliatesForMarketing boolean The merchant uses affiliates for marketing purposes?
marketCoverages Array MarketCoverage list of market coverage

Website

Field Type Explanation
url string Url
loginUsername string Login username (if applicable)
loginPassword string Login password (if applicable)
ipAddress string IP address

Settlement

Field Type Explanation
owner string Owner of bank account
bankName string Bank name
bankAddress Address Bank address
bankTelephone string Bank telephone number
accounts Array Account Bank accounts details
comments string Addidtional comments
settlementFrequency SettlementFrequency The frequency of settlements shall be

Processsing

Field Type Explanation
projectedProcessingVolume ProjectedProcessingVolume Projected processing volume (split down by currency)
projectedNumberOfTransactions ProjectedNumberOfTransactions Projected number of transactions (split down by currency)
priceRange ProductServicePriceRange Product/Service price range (per currency)
customerOrderPercentage CustomerOrderPercentage Split for customer orders (%)
volumeByContinentPercentage VolumeByContinentPercentage Volume divided by continent (%)
volumeCardTypes Array VolumeByCardTypes Volume divided by card types (%)
fraudPreventionTechniques string Fraud prevention techniques in place
countriesBlockedForTransaction Array string Country by two digit ISO code

PaymentServiceProvider

Field Type Explanation
companyName string Name of company
website Website Website
country string Country by two digit ISO code
serviceProvided string Service provided (pls. specify)
pcidssCompliance PCIDSSCompliance PCI DSS compliance
additionalInfo string Additional information

WarehouseProductShipment

Field Type Explanation
goods string ENUM "PhysicalGoods", "DigitalContentViaInternet"
contact Contact Contact person
method string ENUM "InHouse", "FullfilmentHouse", "ThirdPartyAgent", "Other"
warehouseLocationSameAsOfficeAddress boolean If in-house, where is the warehouse location
warehouseLocation Address If other, please specify the warehouse location
fulfilmentHouseCompanyName string Fulfilment house or third party agent details: Company name
fulfilmentHouseAddress Address Fulfilment house or third party agent details: Address
fulfilmentHouseContact Contact Fulfilment house or third party agent details: Contact person

Contact

Field Type Explanation
roles Array ContactType List of roles this contact has
firstName string first name
lastName string last name
email string email
phone string phone
address Address Current home address
passportNumber string Passport number
dateOfBirth string Date of birth
ownership number Ownership (%)
nature NatureOfOwnership Nature of ownership (Direct or indirect? If indirect please describe)

ContactType

PrimaryContact, BeneficialOwner, Director, MerchantTechnicalContact, PFTechnicalContact, IntegrationTechnicalContact, FinancialContact, ChargebackContact, ChargebackNotification, CustomerSupport, SettlementContact, WarehouseContact

Address

Field Type Explanation
street string street
postCode string postal code, zip
state string state
city string city
country string Country by two digit ISO code

Amount

Field Type Explanation
currency Currency what currency
amountNumber number the actual amount

ThreeDSecure

Field Type Explanation
active boolean If yes, MPI used?
borgunMPI boolean SaltPay´s MPI used
otherMPI string Other MPI used

Terminal

Field Type Explanation
type string "OneTime", "Moto", "Recurring", "ThreeDSecure", "eCommerce", "PayByLink", "VirtualTerminal", "Other",
otherExplanation string explanation for other

Card

Field Type Explanation
cardScheme string "VISA", "MasterCard", "AMEX", "UnionPay", "Diners", "Discover", "JCB", "CUP", "Other"
cardType string "Debet", "Credit", "PrePaid", "GiftCard", "Other"

TotalAnnualTurnover

Field Type Explanation
actualOrEstimated Amount Annual / Estimated
projected Amount Projected

Deposit

Field Type Explanation
depositAllowed boolean Do you take any deposits?:
cardTurnoverPercentage number What % of total card turnover is taken as a deposit?
goodsServicesPercentage number What % of goods/service value is taken as a deposit?
daysInAdvance number How far in advance do you take the deposit?

PrePayment

Field Type Explanation
fullPaymentsInAdvance boolean Do you take a full payment for goods/service in advance?
daysInAdvance number How far in advance do you take full payment?
percentageOfCardTurnover number What % of the total Card Turnover is taken as Full Pre-Payment?

MarketCoverage

Field Type Explanation
country string Country by two digit ISO code
percentage number Please specify market coverage, major countries where the customers come from

Account

Field Type Explanation
currency Currency what currency
swiftCode string Swift Code
ibaNnumber string IBAN number
referenceCode string Reference code (if needed)
sortCode string Sort code

SettlementFrequency

Field Type Explanation
frequency string enum: "Daily3daysDelay", "Daily7daysDelay", "WeeklyOnWednesdays", "Other"
otherExplanation string other

ProjectedProcessingVolume

Field Type Explanation
month1 Amount 1st month
month2 Amount 2nd month
month3 Amount 3rd month
month4 Amount 4th month
month5 Amount 5ht month
month6 Amount 6th month
month7To12 Amount Month 7-12
year2 Amount Year 2
year3 Amount Yaer 3

ProjectedNumberOfTransactions

Field Type Explanation
month1 number 1st month
month2 number 2nd month
month3 number 3rd month
month4 number 4th month
month5 number 5ht month
month6 number 6th month
month7To12 number Month 7-12
year2 number Year 2
year3 number Yaer 3

ProductServicePriceRange

Field Type Explanation
min Amount Min
max Amount Max
avg Amount Average

CustomerOrderPercentage

Field Type Explanation
online number Online
moto number MO/TO
other number Other

VolumeByContinentPercentage

Field Type Explanation
europe number Europe
northAmerica number USA
other number Other

VolumeByCardTypes

Field Type Explanation
card Card Visa, Mastercard,...
percentage number Volume divided by card types (%)

PCIDSSCompliance

Field Type Explanation
verified boolean Verified
verifiedBy string Verified by (Verified by a certified Qualified Security Assessor (QSA) or Approved Scanning Vendor (ASV))
expiry string Expire date

NatureOfOwnership

Field Type Explanation
direct boolean Direct ownership
descriptionOfOwnership string If indirect please describe

Currency

List of currencies: "USD", "EUR", "GBP", "SEK", "NOK", "DKK", "AUD", "CAD", "CHF", "YEN", "HUF", "CZK", "PLN", "ISK", "Other"

Get Application Status

Returns the status of a single application. Returned values include:

  • stage (Application Stage)
  • stageClassifier (reason for application being in either the OnHold or Declined stages)
  • stageComments (further comments regarding the OnHold or Declined stage)
  • mcc (MCC code)

  • mid (Merchant ID number)

    The application can be in one of the following stages:

    New,
ReceiveCheck,
PendingReview,
Review,
AcceptedPendingInfo,
PendingSetup,
Setup,
PendingContractReview,
ContractFinalization,
Declined,
Closed,
Boarded,
OpenChangeRequest,
PreApproved,
OnHold

Upload Application Documents

Upload documents that are connected to the application. Total size of payload is limited to 50MB. Multiple files can be uploaded. Allowed file endings are following:

- .doc
- .docx
- .xls
- .xlsx
- .png
- .jpg
- .tif
- .tiff
- .pdf
- .odt
- .ods
- .zip

Get Contacts

Returns að list of all Contacts connected to one application.

Add Contact

Adds multiple Contact to selected application. The contact object must be in the body of the POST request.

If the contact object is not correct an HTTP 400 with a list of first name and the reason why the object is not valid. Example

{
    "message": "John: The Roles field is required", "Alex: The Email field is required"
}

Add Fees

Adds Fees to a seller application. The fees object must be in the body of POST request.

Fees

Field Type Explanation
ContactName string name of contact
ContactEmail string email of contact
EmailForSettlement string email settlement information is sent to
CardSchemes Array [string] these enum members are valid: "VISA", "MasterCard", "AMEX", "UnionPay", "Diners", "Discover", "JCB", "CUP", "Other"
RefundsAllowed boolean true or false
MOTO boolean true or false
MOTOPercentage decimal percentage of MOTO
ProcessingCurrency1 Currency what currency
ProcessingCurrency2 Currency what currency
SettlementCurrency1 Currency what currency
SettlementCurrency2 Currency what currency
ServiceFeesMasterCardCP ServiceFees Card Present service fees MasterCard
ServiceFeesMasterCardCnP ServiceFees Card not Present service fees MasterCard
ServiceFeesVISACP ServiceFees Card Present service fees VISA
ServiceFeesVISACnP ServiceFees Card not Present service fees VISA
ServiceFeesOtherCardsCP ServiceFees Card Present service fees other cards
ServiceFeesOtherCardsCnP ServiceFees Card not Present service fees other cards
TransactionFeesCP TransactionFees Card Present transaction fees
TransactionFeesCnP TransactionFees Card not Present transaction fees
OtherFeesCP CurrencyFees Card Present other fees
OtherFeesCnP CurrencyFees Card not Present other fees
RollingReserveAggreement boolean true or false
RollingReserve string rolling reserve

Service fees

Field Type Explanation
DomesticConsumerCredit decimal Domestic consumer credit fee
IntraConsumerCredit decimal Intra consumer credit fee
InterConsumerCredit decimal Inter consumer credit fee
DomesticConsumerDebit decimal Domestic consumer debit fee
IntraConsumerDebit decimal Intra consumer debit fee
InterConsumerDebit decimal Inter consumer debit fee
DomesticCommercialCredit decimal Domestic commercial credit fee
IntraCommercialCredit decimal Intra commercial credit fee
InterCommercialCredit decimal Inter commercial credit fee
DomesticCommercialDebit decimal commercial consumer debit fee
IntraCommercialDebit decimal Intra commercial debit fee
InterCommercialDebit decimal Inter commercial debit fee

Transaction fees

Field Type Explanation
Currency Currency what currency
Authorised string Authorised and settled
Declined string Declined/voided

Currency fees

Field Type Explanation
Currency Currency what currency
ChargebackFee string Chargeback fee
StatementFee string Statement fee
RefundFee string Refund fee
OneTimeSetUpFee string One time set-up fee
MonthlyFee string Monthly fee
MonthlyFeePlusVAT string Monthly fee plus VAT
AnnualFee string Annual fee
PaymentPageSetupFee string Secure hosted payment page setup fee
PaymentPagMonthlyFee string Secure hosted payment page monthly fee
GatewayConnectionFee string Gateway connection fee
GatewayMonthlyFee string Gateway monthly fee
PayByLinkFee string Pay by link fee
VirtualTerminal string Virtual terminal fee
MinimumMonthlyFee string Minimum monthly fee

Add Equipment

Adds Equipment to a seller application. The equipment object must be in the body of POST request.

Equipment

Field Type Explanation
TerminalInfos Array[TerminaInfol] Terminal information
VerifoneTerminals Array[VerifoneTerminal] List of Verifone terminals
OptomanyTerminals Array[OptomanyTerminal] List of Optomany terminals
HandpointTerminals Array[HandpointTerminal] List of Handpoint terminals
SpireTerminals Array[SpireTerminal] List of Spire terminals
SpireDelivery SpireDelivery Spire delivery information

TerminalInfos

Field Type Explanation
DBAName string DBA on slip, max 22 chars
Address string Address on slip
City string City on slip
Postcode string Postcode on slip
AdditionalComments string Additional comments

VerifoneTerminal

Field Type Explanation
TerminalType string One of "VX680GPRS", "VX680WIFI", "VX520IP", "VX690GPRS", "VX690WIFI", "VX820IP"
Quantity number Number of terminals
MOTO boolean MOTO payments allowed
PreAuth boolean PreAuth payments allowed
Gratuity boolean Gratuity allowed
Base boolean Base required
Comment string Additional comments regarding terminal

OptomanyTerminal

Field Type Explanation
TerminalType string One of "PaxS800IP", " "PaxS900WIFIGPRS"
Quantity number Number of terminals
MOTO boolean MOTO payments allowed
PreAuth boolean PreAuth payments allowed
Gratuity boolean Gratuity allowed
Base boolean Base required
AMEX boolean AMEX payments allowed
Comment string Additional comments regarding terminal

HandpointTerminal

Field Type Explanation
TerminalType string One of "HiLite", "HiPro", "HiFive"
Quantity number Number of terminals
Gratuity boolean Gratuity allowed
Base boolean Base required
Comment string Additional comments regarding terminal

SpireTerminal

Field Type Explanation
TerminalType string One of "SPW70GPRS", "SPW60WIFI", "SPC50IP", "SPp10PINPad"
Quantity number Number of terminals
MOTO boolean MOTO payments allowed
PreAuth boolean PreAuth payments allowed
Gratuity boolean Gratuity allowed
Base boolean Base required
AP number Number of APs
TailwindStand boolean TailwindStand required
AMEX boolean AMEX payments allowed
Comment string Additional comments regarding terminal

SpireDelivery

Field Type Explanation
TerminalDeliveryAddress string Terminal delivery address
SameAsRegisteredAddress boolean Same address as registered address?
SameAsTradingAddress boolean Same address as trading address?
ContactName string Contact name
ContactEMail string Contact email
ContactMobile string Contact mobile number

Add Note

Adds Note to a seller application. The note object must be in the body of POST request.

Note

Field Type Explanation
Title string Title of note
Description string Content of note