Endpoints: Authentication
Required mechanisms to authenticate a 3rd party session and trigger the integration to the API.
POST /oauth/token
| Code Block |
|---|
https://posapi-training.flexiti.fi/flexiti/pos-api/v2.5/oauth/token |
Please note the parameters should not be passed as Query string, the service is expecting an application/x-www-form-url encoded payload.
This service Authenticates the developer user and provides a Bearer Token that needs to be used as part of every future request.
The refresh token is used to get a new access token once the current one has expired.
In order to use it add the refresh token (provided in the original /oauth/token call) and change the grant_type to refresh_token.
Scope Parameter Usage
For the token endpoint there are two possible scopes: merchant or customer.
A token with a merchant scope will be allowed for all endpoints
A token with a customer scope will be allowed in all endpoints required by customer facing UI, other endpoints will considered this token invalid.
The endpoints that should be called using a customer scope should be:
...
POST /client-id/{client_id}/merchants/login
...
POST /client-id/{client_id}widget/init
...
POST /client-id/{client_id}/apply
...
GET /client-id/{client_id}/terms-and-conditions
...
POST /client-id/{client_id}/information
...
These endpoints support Merchant integrations of Flexiti services.
| Table of Contents |
|---|
...
POST /oauth/token
| Code Block |
|---|
https://{posapi_url}/flexiti/pos-api/v2.5/oauth/token |
Please note the parameters should not be passed as Query string, the service is expecting an application/x-www-form-url encoded payload.
This service Authenticates the developer user and provides a Bearer Token that needs to be used as part of every future request.
The refresh token is used to get a new access token when the current one is about to expire. It cannot be refreshed after it is expired
In order to use it add the refresh token (provided in the original /oauth/token call) and change the grant_type to refresh_token. More information available here: How to Implement the Refresh Token
Scope Parameter Usage (IMPORTANT)
For the token endpoint there are two possible scopes: merchant or customer.
A token with a customer scope will be allowed in all endpoints required by customer facing UI, other endpoints will considered this token invalid
When to use: for Online channel implementations during the application and authorization flows (outlined below).
A token with a merchant scope will be allowed for all endpoints
When to use: for In-store channel implementations, or Online channel back office processes like capturing an authorization, releasing, refunding/returning, etc.
The endpoints that should be called using a customer scope should be:
POST /client-id/{client_id}/i18n
GET /client-id/{client_id}/accounts/:account_number/calculate-interestterms-and-conditions
POST /client-id/{client_id}/customers/driverslicense
POST /client-id/{client_id}widget/authorization
Request Parameters:
...
Type
...
Parameter
...
Required
...
Details
...
FORMDATA
init
POST /client-id/{client_id
...
Yes
...
ASCII string (100)
This is the Client ID given in the Developer User Account section
...
FORMDATA
...
client_secret
...
Yes
...
ASCII string (100)
This is the Client Secret given in the Developer User Account section
...
BODY
...
grant_type
...
ASCII string
This is the client's access type
possible values: 'password', 'refresh_token', 'client_credentials'
default value: 'client_credentials'
...
BODY
...
refresh_token
...
ASCII string
only to be used with the grant_type: refresh_token.
It should be the refresh_token attribute in the last response of this method.
...
BODY
...
scope
...
ASCII string
Available values: ‘customer', 'merchant’
Default value: merchant
Example Request:
| Code Block | ||
|---|---|---|
| ||
{
"client_id": "flexitidemo",
"client_secret": "77fde15a-9d33-4e15-930a-76e4b3ae33e9",
"grant_type": "client_credentials",
"scope": "merchant"
} |
Response Parameters:
...
Type
...
Parameter
...
Required
...
Details
...
BODY
...
access_token
...
Yes
...
Bearer token to be used in subsequent calls
...
BODY
...
expires_in
...
Yes
...
Time, in seconds, that the token will last
...
BODY
...
refresh_token
...
Yes
...
Token to be used to refresh the access_token
Success Response:
| Code Block |
|---|
{
"token_type": "bearer",
"access_token": "3d8f373a9a2b1e61baf5abb69930ff4f0e08cdb0",
"expires_in": 1200,
"refresh_token": "36e0fc3d7415185f4b1d71512c459fd6eaa13aa8"
} |
POST /client-id/{client_id}/merchants/login
| Code Block |
|---|
https://posapi-training.flexiti.fi/flexiti/pos-api/v2.5/client-id/flexitidemo/merchants/login?lang=en |
This service will log in the Merchant session and provide back an updated version of the list of parameters based on the language variable provided. This is required within the session to ensure the Merchant has the latest version of all parameters.
Request Parameters:
...
Type
...
Parameter
...
Required
...
Details
...
HEADER
...
bearer token
...
Yes
...
ASCII string (1000)
This is the word “Bearer” with a space and then the access_token given in oauth/token API response
Default value: Bearer {insert_bearer_token_from_oauth_here/token_api}
...
PATH
...
client_id
...
Yes
...
ASCII string (100)
This is the Client ID given in the Developer User Account section
...
QUERY
...
lang
...
ASCII string (2)
Customer Preferred language
Available values: (en=English) or (fr=French)
Default: en
...
BODY
...
merchant_username
...
ASCII string
Optional information to log in a specific Sales Representative or Merchant location
...
BODY
...
merchant_password
...
ASCII string
Optional information to log in a specific Sales Representative or Merchant location
Example Request:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"merchant_username": "merchantonline",
"merchant_password": "dice-manila-purism"
} |
Response Parameters:
...
Type
...
Parameter
...
Required
...
Details
...
BODY
...
merchant_name
...
Yes
...
ASCII string (130)
Name of the merchant authenticated
...
BODY
...
merchant_id
...
Yes
...
number (10)
ID of the merchant authenticated
...
BODY
...
form_values
...
Yes
...
ASCII strings
Various values used in the credit application form
Success Response:
...
| breakoutMode | wide |
|---|---|
| language | json |
...
}/apply
POST /client-id/{client_id}/accounts/{account_number}/close
POST /client-id/{client_id}/accounts/{account_number}/calculate-interest
POST /client-id/{client_id}/account/{account_number}/verify
POST /client-id/{client_id}/authorization
Request Parameters:
Type | Parameter | Required | Details |
|---|---|---|---|
FORMDATA | client_id | Yes |
|
FORMDATA | client_secret | Yes |
|
HEADER | x-reference-id | Yes |
|
BODY | grant_type |
| |
BODY | refresh_token |
| |
BODY | scope |
|
Example Request:
| Code Block | ||
|---|---|---|
| ||
{
"client_id": "flexitidemo",
"client_secret": "77xde15a-9d33-4c15-930a-3se4b3as33e9",
"grant_type": "client_credentials",
"scope": "merchant"
} |
Response Parameters:
Type | Parameter | Details |
|---|---|---|
BODY | access_token |
|
BODY | expires_in |
|
BODY | refresh_token |
|
Success Response:
| Code Block |
|---|
{
"token_type": "bearer",
"access_token": "2d8f373a3c2b1e61baf5a7769930ff4f0e08cdb0",
"expires_in": 1200,
"refresh_token": "36e0fc3d7415145f4b1d71512c459fd6eaa13aa8",
"scope": "merchant"
} |
...
GET /client-id/{client_id}/i18n
| Code Block |
|---|
https://{posapi_url}/flexiti/pos-api/v2.5/client-id/{client_id}/i18n |
Or
| Code Block |
|---|
https://{posapi_url}/flexiti/pos-api/v2.5/client-id/{client_id}/i18n/{key} |
This endpoint will return information for application form values and customer facing messaging like disclaimers
You can retrieve all information or filter for specific messages using a key in the URL
Request Parameters:
Type | Parameter | Required | Details |
|---|---|---|---|
HEADER | authorization | Yes |
|
HEADER | x-reference-id | Yes |
|
PATH | client_id | Yes |
|
QUERY | lang |
| |
QUERY | {key} |
|
Success Response:
| Code Block |
|---|
{ "salutations": { " |
...
mr": |
...
"Mr.", |
...
" |
...
ms": |
...
"Ms.", |
...
"mrs": "Mrs.", " |
...
mss": " |
...
Miss." |
...
}, "provinces": { " |
...
AB": " |
...
Alberta", "BC": "British Columbia", " |
...
MB": " |
...
Manitoba", |
...
"NB": " |
...
New Brunswick", "NL": "Newfoundland & Labrador", |
...
|
...
"NS": "Nova Scotia", " |
...
NT": |
...
"Northwest Territories", |
...
" |
...
NU": |
...
"Nunavut", |
...
" |
...
ON": " |
...
Ontario", |
...
|
...
" |
...
PE": " |
...
Prince Edward |
...
Island", "QC": "Quebec", " |
...
SK": " |
...
Saskatchewan", "YT": "Yukon Territory" |
...
}, "security_ids": { |
...
" |
...
4": " |
...
What |
...
is |
...
the name of your favourite |
...
childhood friend?", " |
...
5": " |
...
What |
...
is the country of your ultimate dream vacation?", |
...
" |
...
6": " |
...
What |
...
was the first concert |
...
you attended?", " |
...
7": " |
...
What is the name of the street you grew up on?", " |
...
8": " |
...
What is the name of your first grade teacher?", " |
...
9": " |
...
What |
...
is |
...
your favourite movie?" |
...
}, " |
...
govid_types": |
...
{ |
...
"CADL": " |
...
Driver's Licence", |
...
|
...
"CAHC": " |
...
Health |
...
Card", "CAPID": "Provincial ID Card", |
...
|
...
"CAP": "Passport", " |
...
CAPRC": |
...
"Permanent Resident Card", |
...
" |
...
CAICBC": |
...
"Insurance Corporation of British Columbia", |
...
" |
...
CAAR": " |
...
Alberta |
...
Registries", |
...
|
...
|
...
|
...
|
...
|
...
|
...
"CASGI": "Saskatchewan Government Insurance", |
...
" |
...
CADSNS": " |
...
Department |
...
of |
...
Service |
...
Nova |
...
Scotia |
...
and |
...
Municipal Relations", "CADPPEI": "Department of Transportation and Public Works of |
...
the Province of Prince Edward Island", "CASNB": "Service New Brunswick", " |
...
CADGSNF": " |
...
Department of Government Services and Lands of the |
...
Province |
...
of |
...
Newfoundland |
...
and |
...
Labrador", "CADTNW": "Department of Transportation of the Northwest |
...
Territories" |
...
, |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
"CADCTN" |
...
: "Department of Community Government and Transportation of the Territory of Nunavut", " |
...
CACSC": " |
...
Correctional |
...
Service |
...
Canada |
...
identification |
...
card (with the individual's name and photograph)", |
...
"CAGCEC": "Government of Canada employee identity card |
...
(with the |
...
individual's name and |
...
photograph)", |
...
" |
...
CALCB": |
...
"Liquor Control Board Age of Majority |
...
(BYID) card", " |
...
CACFL": " |
...
Canadian Firearms licence", |
...
"CACFID": " |
...
Canadian Forces identification card", "CAMPIC": "MPIC card issued by the Manitoba Public |
...
Insurance Corporation" |
...
, |
...
|
...
"CACAID": "NEXUS or CANPASS Air membership card (issued by Canada Border Services |
...
Agency)" |
...
|
...
}, "govid_issued_bys": { " |
...
option_depends": |
...
{ |
...
|
...
"CADL": { |
...
"AB": " |
...
Alberta", " |
...
BC": " |
...
British |
...
Columbia", " |
...
MB": " |
...
Manitoba", " |
...
NB": " |
...
New Brunswick", " |
...
NL": " |
...
Newfoundland |
...
& |
...
Labrador", |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
"NS": "Nova Scotia", " |
...
NT": " |
...
Northwest |
...
Territories", " |
...
NU": |
...
"Nunavut", "ON": "Ontario", " |
...
PE": " |
...
Prince |
...
Edward Island", " |
...
QC": " |
...
Quebec", "SK": "Saskatchewan", " |
...
YT": " |
...
Yukon |
...
Territory" |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
}, " |
...
CAHC": |
...
{ |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
"BC": "British Columbia", |
...
"NB": "New Brunswick", " |
...
NL": " |
...
Newfoundland |
...
& |
...
Labrador", " |
...
NT": " |
...
Northwest Territories", " |
...
NU": " |
...
Nunavut", |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
"QC": "Quebec", |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
"SK": "Saskatchewan", |
...
"YT": "Yukon Territory" |
...
|
...
}, " |
...
CAPID": { " |
...
ON": |
...
"Ontario" }, |
...
|
...
"CAP": { " |
...
CANADA": " |
...
Canada" |
...
}, |
...
|
...
"CAPRC": { " |
...
CANADA": " |
...
Canada" |
...
}, |
...
|
...
|
...
|
...
"CAICBC": { " |
...
BC": " |
...
British |
...
Columbia" |
...
}, |
...
|
...
|
...
"CAAR": { " |
...
AB": " |
...
Alberta" |
...
}, |
...
|
...
"CASGI": { " |
...
SK": " |
...
Saskatchewan" |
...
|
...
}, " |
...
CADSNS": |
...
{ |
...
" |
...
NS": " |
...
Nova Scotia" |
...
}, |
...
|
...
|
...
"CADPPEI": { |
...
"PE": "Prince Edward Island" |
...
}, "CASNB": { |
...
" |
...
NB": " |
...
New |
...
Brunswick" |
...
}, |
...
|
...
|
...
"CADGSNF": { "NL": "Newfoundland & Labrador" |
...
}, |
...
|
...
|
...
"CADTNW": { " |
...
NT": " |
...
Northwest Territories" |
...
|
...
}, |
...
"CADCTN": |
...
{ |
...
" |
...
NU": " |
...
Nunavut" |
...
|
...
},
|
...
" |
...
CACSC": { |
...
" |
...
CANADA": " |
...
Canada" |
...
}, |
...
|
...
" |
...
CAGCEC": { |
...
"CANADA": "Canada"
|
...
}, |
...
|
...
" |
...
CALCB": { |
...
" |
...
AB": " |
...
Alberta", |
...
"BC": "British Columbia", " |
...
MB": |
...
"Manitoba", |
...
" |
...
NB": " |
...
New |
...
Brunswick", |
...
"NL": "Newfoundland & Labrador", " |
...
NS": |
...
"Nova Scotia", |
...
" |
...
NT": " |
...
Northwest Territories", |
...
"NU": "Nunavut", " |
...
ON": |
...
"Ontario", |
...
" |
...
PE": " |
...
Prince Edward Island", |
...
"QC": "Quebec", " |
...
SK": |
...
"Saskatchewan", |
...
" |
...
YT": " |
...
Yukon |
...
Territory" |
...
}, |
...
|
...
" |
...
CACFL": { |
...
"CANADA": "Canada" |
...
},
|
...
" |
...
CACFID": { |
...
" |
...
CANADA": " |
...
Canada" }, |
...
" |
...
CAMPIC": { |
...
" |
...
MB": " |
...
Manitoba" |
...
},
|
...
" |
...
CACAID": { |
...
" |
...
CANADA": " |
...
Canada" |
...
} |
...
} }, " |
...
occupation_ids": { "options": { " |
...
FE": " |
...
Full-time Employment", "PE": "Part-time Employment", |
...
"SE": "Self-Employed", |
...
|
...
"RT": "Retired", " |
...
ST": " |
...
Student", |
...
"HM": "Homemaker", |
...
" |
...
DS": |
...
"Disability", |
...
"SW": " |
...
Seasonal Worker", "UE": "Unemployed with |
...
income", |
...
" |
...
UW": |
...
"Unemployed without income", |
...
"OT": " |
...
Other" |
...
} |
...
}, |
...
" |
...
transaction_types": |
...
{ |
...
"promotional_purchase": "Financed Purchase", |
...
" |
...
regular_purchase": " |
...
Revolving Purchase" |
...
}, |
...
"plan_ids": { " |
...
1": " |
...
90 Days Grace, Equal Payments Regular Interest", "2": "Equal Payments, Low Interest", " |
...
4": " |
...
Equal Payments, Regular Interest", "5": "Equal Payments, No Interest", " |
...
6": " |
...
No Interest, No Payments (S.A.C.)", "7": "No Interest, No Payments", " |
...
9": " |
...
No |
...
Interest, Minimum monthly payments" }, "qcpa_disclosure": "...", "insurance": "...", " |
...
insurance_tc": " |
...
...", "annual_fees": "...", "housing_type": { " |
...
Rent": " |
...
Rent", "Owned": "Owned", |
...
" |
...
Relatives": " |
...
Lives |
...
with |
...
Relatives", |
...
"Other": "Other"
}
} |
...
POST /client-id/{clientId}/widget/init
| Code Block |
|---|
https://{posapi_url}/flexiti/pos-api/v2.5/client-id/{client_id}/widget/init |
The Flexiti widget is used for the Online channel only, and is for high orchestration scenarios, such as customer verification and multiple account selection. It is a UI component that’s an entry point to the Flexiti purchase flow.
For full Widget documentation start here - Flexiti Widget - POS API Online Channel Purchase Flow