POS API Endpoint Overview

The Flexiti POS API Endpoints is divided into 5 categories:

Authentication - Required mechanisms to authenticate a 3rd party session.
Customers - Endpoints required to identify a Flexiti customer.
CreditApps - Endpoints that allow Merchant customers to apply for new credit.
Transactions - - Endpoints required to post transactions (purchases and returns).
Merchants - Endpoints that allow the retrieval of transaction information for daily activities.

https://flexiti.atlassian.net/wiki/spaces/ONL/pages/9502856/POS+API+v2.5+-+Widget+Implementation

Endpoints: Authentication

Required mechanisms to authenticate a 3rd party session and trigger the integration to the API.

POST /oauth/token

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.

Parameters:

Type	Parameter	Required	Details
FORMDATA	client_id	Yes	ASCII string This is the Client ID given in the Developer User Account section
FORMDATA	client_secret	Yes	ASCII string 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'

Validations:

Parameter	Case	Error Type

Example Value:

{
    "client_id": "flexitidemo",
    "client_secret": "77fde15a-9d33-4e15-930a-76e4b3ae33e9",
    "grant_type": "client_credentials"
}

Success Response:

200 - Success

{
    "token_type": "bearer",  
    "access_token": "3d8f373a9a2b1e61baf5abb69930ff4f0e08cdb0",  
    "expires_in": 1200,  
    "refresh_token": "36e0fc3d7415185f4b1d71512c459fd6eaa13aa8"
}

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.

Parameters:

Type	Parameter	Required	Details
HEADER	authorization	Yes	ASCII string 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 This is the Client ID given in the Developer User Account section
QUERY	lang		ASCII string Customer Preferred language Available values: (en=English) or (fr=French)
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

Validations:

Parameter	Case	Error Type

Example Value:

{
    "merchant_username": "merchantonline",
    "merchant_password": "dice-manila-purism"
}

Success Response:

200 - Success

{
    "merchant_name": "European Restorations",
    "merchant_id": "382",
    "form_values": {
        "salutation": {
            "options": {
                "mr": "Mr.",
                "ms": "Ms.",
                "mrs": "Mrs.",
                "mss": "Miss."
            }
        },
        "province": {
            "options": {
                "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_qid": {
            "options": {
                "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_type": {
            "options": {
                "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_by": {
            "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"
                }
            }
        },
        "offer_types": [
            {
                "plan_name": "90 Days Grace, Equal Payments Regular Interest",
                "term_options": [
                    18,
                    36,
                    48,
                    72
                ],
                "plan_id": "1",
                "offer_category": "equal_billing"
            },
            {
                "plan_name": "Equal Payments, Low Interest",
                "term_options": [
                    3,
                    6,
                    40,
                    60
                ],
                "plan_id": "2",
                "offer_category": "equal_billing"
            },
            {
                "plan_name": "Equal Payments, Regular Interest",
                "term_options": [
                    3,
                    6,
                    18,
                    36,
                    72
                ],
                "plan_id": "4",
                "offer_category": "equal_billing"
            },
            {
                "plan_name": "Equal Payments, No Interest",
                "term_options": [
                    3,
                    6,
                    10,
                    20,
                    30,
                    40
                ],
                "plan_id": "5",
                "offer_category": "equal_billing"
            },
            {
                "plan_name": "No Interest, No Payments  (S.A.C.)",
                "term_options": [
                    3,
                    6,
                    8
                ],
                "plan_id": "6",
                "offer_category": "deferred_payment"
            },
            {
                "plan_name": "No Interest, No Payments ",
                "term_options": [
                    3,
                    12
                ],
                "plan_id": "7",
                "offer_category": "deferred_payment"
            },
            {
                "plan_name": "No Interest, Minimum monthly payments",
                "term_options": [
                    3,
                    6,
                    9,
                    12,
                    18
                ],
                "plan_id": "9",
                "offer_category": "deferred_payment"
            }
        ]
    }
}

Endpoints: CreditApps

Endpoints that allow Customers to Apply for new Credit.

GET /client-id/{client_id}/terms-and-conditions

https://posapi-training.flexiti.fi/flexiti/pos-api/v2.5/client-id/flexitidemo/terms-and-conditions?lang=en&province=QC

Serves a HTML of the terms and conditions a Customer must approve for a Credit Application with Flexiti.

Applicants from Quebec will be served terms and conditions specific to Quebec Residents in compliance with the QCPA. All other provinces will be served terms and conditions for the rest of Canada.

Parameters:

Type	Parameter	Required	Details
HEADER	authorization	Yes	ASCII string 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 This is the Client ID given in the Developer User Account section
QUERY	lang		ASCII string Customer Preferred language Available values: (en=English) or (fr=French) Default value: en
QUERY	province		ASCII string 2 character syntax (ex. ON for Ontario) Available values: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT Not passing a province value will default to the ROC terms and conditions

Validations:

Parameter	Case	Error Type

Example Value:

Success Response:

200 - Success

<div id='tcs'>...
</div>

POST /client-id/{client_id}/apply

https://posapi-training.flexiti.fi/flexiti/pos-api/v2.5/client-id/flexitidemo/apply

This endpoint is used for new Customer applications.

Quebec applicants must pass the monthly_housing_expenses parameter. Upon successful adjudication, Quebec applicant responses will include a debt_ratio parameter which must be displayed to the applicant along with the available credit. The applicant must then be given the option to cancel the adjudicated application (through the POST /client-id/{client_id}/customers/close-account endpoint).

Parameters:

Type	Parameter	Required	Details
HEADER	authorization	Yes	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 This is the Client ID given in the Developer User Account section
BODY	amount_requested	Yes	number Amount Requested
BODY	phone_number	Yes	ASCII string Customer Mobile Phone Number This will be used for MFA via SMS
BODY	email	Yes	ASCII string Customer Email
BODY	language		ASCII string Preferred Language (Locale) Available values: en-CA, fr-CA Default value: en-CA
BODY	salutation	Yes	ASCII string Salutation Available values: (mr = Mr./M.), (ms = Ms./Mme.), (mrs = Mrs.), (mss = Miss.)
BODY	first_name	Yes	ASCII string Customer First Name
BODY	middle_name		ASCII string Customer Middle Name
BODY	last_name	Yes	ASCII string Customer Last Name
BODY	dob	Yes	ISO 8406 Date Customer Date of Birth (YYYY-MM-DD)
BODY	address_1		ASCII string Customer Address Line 1
BODY	address_2	Yes	ASCII string Customer Address Line 2
BODY	city	Yes	ASCII string Customer City
BODY	province	Yes	ASCII string Customer Province (2 character syntax, ex. ON for Ontario) Available values: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT.
BODY	postal_code	Yes	ASCII string Customer Postal Code
BODY	govid_type		ASCII string Required for in-store implementations Customer Government Identification Type: for Driver’s License use CADL; for Health Card use CAHC; for Provincial ID Card use CAPID; for Passport use CAP; for Permanent Resident Card use CAPRC; for Insurance Corporation of British Columbia use CAICBC; for Alberta Registries use CAAR; for Saskatchewan Government Insurance use CASGI; for Department of Service Nova Scotia and Municipal Relations use CADSNS; for Department of Transportation and Public Works of the Province of Prince Edward Island use CADPPEI; for Service New Brunswick use CASNB; for Department of Government Services and Lands of the Province of Newfoundland and Labrador use CADGSNF; for Department of Transportation of the Northwest Territories use CADTNW; for Department of Community Government and Transportation of the Territory of Nunavut use CADCTN; for Correctional Service Canada identification card use CACSC; for Government of Canada Employee Identity Card use CAGCEC; for Liquor Control Board Age of Majority (BYID) Card use CALCB; for Canadian Firearms Licence use CACFL; for Canadian Forces Identification Card use CACFID; for MPIC Card issued by the Manitoba Public Insurance Corporation use CAMPIC; for NEXUS or CANPASS Air Membership Card (issued by Canada Border Services Agency) use CACAID.
BODY	govid_issuedby		ASCII string Required for in-store implementations Issuing Authority (2/3 character syntax, ex. ON for Ontario, CANADA for Canada); if type selected is DL or CALCB, available values are AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT; if CAHC available values are BC, NB, NL, NT, NU, QC, SK, YT; if CAPID, available value is ON; if CAP or CAPRC, available value CANADA; if CAICBC, available value is BC; if CAAR, available value is AB; if CASGI, available value is SK; if CADSNS, available value is NS; if CADPPEI, available value is PE; if CASNB, available value is NB; if CADGSNF, available value is NL; if CADTNW, available value is NT; if CADCTN, available value is NU; if CACSC or CAGCEC, available value is CANADA; if CACFL or CAFCID or CACAID, available value is CANADA; if CAMPIC, available value is MB.
BODY	govid_number		ASCII string Required for in-store implementations Customer Government Identification Number
BODY	govid_expiry		ISO 8406 Date Required for in-store implementations Customer Government Identification Expiry Date (YYYY-MM-DD)
BODY	input_type		ASCII string How the information has been provided Available values: 'scanned', 'manual' Default value: 'manual'
BODY	personal_income	Yes	integer Customer Personal Income (ex. 100000; round to the dollar value, no decimals; do not enter commas or periods.)
BODY	household_income	Yes	integer Customer Household Income (ex. 100000; round to the dollar value, no decimals; do not enter commas or periods.)
BODY	monthly_housing_expenses		integer Required if province is QC Customer monthly housing expenses (ex. 100000; round to the dollar value, no decimals; do not enter commas or periods.)
BODY	housing_type	Yes	ASCII string Customer Housing Type Available values: Rent, Owned, Relatives, Other.
BODY	occupation_id	Yes	ASCII string Customer Occupation ID:, for Full-Time Employment use FE; for Part-Time Employment use PE; for Self-Employed use SE; for Retired use RT; for Student use ST; for Homemaker use HM; for Disabled use DS; for Seasonal Worker use SW; for Unemployed with Income use UE; for Unemployed without Income use UW; for Other use OT.
BODY	occupation_title	Yes	ASCII string Customer Job Title
BODY	employer_name		ASCII string Customer Employer Name
BODY	employer_phone		ASCII string Customer Employer Phone Number
BODY	sin		ASCII string Customer Social Insurance Number
BODY	security_qid	Yes	ASCII string Customer Security Question ID Select value from list
BODY	security_answer	Yes	ASCII string Customer Security Answer
BODY	piw	Yes	ASCII string Customer Personal Identification Word
BODY	tos_agreement	Yes	boolean Acceptance of the Cardholder Agreement (must be true at the time of submission). Default value: false

Example Value:

{
  "amount_requested": 5000,
  "phone_number": "5551231231",
  "language": "en-CA",
  "salutation": "mr",
  "first_name": "John",
  "middle_name": "Grey",
  "last_name": "Doe",
  "dob": "1990-01-01",
  "address_1": "123 Any Street",
  "address_2": "Apt C",
  "govid_expiry": "2020-12-12",
  "city": "Montreal",
  "province": "QC",
  "postal_code": "A1A0H1",
  "govid_type": "CAP",
  "monthly_housing_expenses": 1000,
  "govid_issuedby": "CANADA",
  "govid_number": "ab121212",
  "input_type": "manual",
  "personal_income": 123123,
  "household_income": 223123,
  "housing_type": "Rent",
  "email": "email@address.com",
  "occupation_id": "FE",
  "occupation_title": "Baker",
  "employer_name": "Tasty Bakery",
  "employer_phone": "1231231231",
  "sin": "123123123",
  "security_qid": "8",
  "security_answer": "Horse",
  "piw": "Cloud",
  "tos_agreement": true
}

Success Response:

200 - Success - ROC applicant

{
  "vcc_number": 6374980100408234,
  "account_number": 20035156,
  "customer_id": 43353,
  "available_credit": 5000,
  "credit_limit": 5000,
  "risk_rating": "L"
}

200 - Success - QC applicant

{
    "vcc_number": 6374980100408234,
    "account_number": 20035156,
    "customer_id": 43353,
    "available_credit": 5000,
    "credit_limit": 5000,
    "risk_rating": "L",
    "offer_types": [
        {
            "plan_name": "90 Days Grace, Equal Payments Regular Interest",
            "plan_id": "1",
            "offer_category": "equal_billing",
            "term_options": [
                "12",
                "18",
                "24",
                "36"
            ]
        }
    ],
    "debt_ratio": 0
}

Error Responses:

401 - Unauthorized - Invalid Token

{
    "code": 401,
    "error": "invalid_token",
    "error_description": "The access token provided is invalid."
}

400 - Conflict - Invalid Client

{
    "code": 400,
    "error": "invalid_client",
    "error_description": "Client credentials are invalid"
}

400 - Conflict - Invalid client ID

{
    "code": 400,
    "error": "invalid_client",
    "error_description": "Invalid or missing client_id parameter"
}

400 - Conflict - Invalid grant type

{
    "code": 400,
    "error": "invalid_request",
    "error_description": "Invalid or missing grant_type parameter"
}

409 - Required Parameters

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "Some inputs are wrong!",
    "error": "wrong_inputs",
    "field_errors": [
        {
            "param": "phone_number",
            "msg": "required"
        }
    ]
}

409 - No TOS

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "It has been following errors:",
    "error": "tos_agreement_required"
}

409 - Existing Customer

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "It has been following errors:",
    "error": "customer_already_exists"
}

409 - Credit App Not Found

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "Credit app id Information not found.",
    "error": "creditapp_id_not_found"
}

409 - Application Declined

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "<p>For more information, please call our customer support centre at <span class='no-break'>1-877-259-3750</span> Monday to Friday 9am to 12am ET, Saturday and Sunday from 9am to 9pm ET and we'd be happy to help.</p>",
    "error": "application_declined"
}

409 - Application Creation Error

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "<h1>We are currently experiencing some technical difficulties that we are trying to fix as soon as possible.</h1><p>Unfortunately, as a result, we are unable to proceed with your application right now.<br/><br/>Have questions? We’re happy to help. Just give us a call at 1-877-259-3750.</p>",
    "error": "application_create_error"
}

409 - Application Marked Pending

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "<p>For more information, please call our customer support centre at <span class='no-break'>1-877-259-3750</span> Monday to Friday 9am to 12am ET, Saturday and Sunday from 9am to 9pm ET and we'd be happy to help.</p>",
    "error": "application_marked_pending"
}

409 - Application Declined 2

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "<p>For more information, please call our customer support centre at <span class='no-break'>1-877-259-3750</span> Monday to Friday 9am to 12am ET, Saturday and Sunday from 9am to 9pm ET and we'd be happy to help.</p>",
    "error": "application_declined_2"
}

409 - Application Declined 3

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "<h1>Unfortunately we can’t seem to find a credit history for you.</h1><p>If you think this is an error, please give us a call at 1-877-259-3750 Monday to Friday 9am to 12am ET, Saturday and Sunday 9am to 9pm ET and we’d be happy to help.</p>",
    "error": "application_declined_3"
}

409 - Application Marked Pending 2

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "<p>For more information, please call our customer support centre at <span class='no-break'>1-877-259-3750</span> Monday to Friday 9am to 12am ET, Saturday and Sunday from 9am to 9pm ET and we'd be happy to help.</p>",
    "error": "application_marked_pending_2"
}

409 - SIN Wrong Format

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/apply",
    "message": "Some inputs are wrong!",
    "error": "wrong_inputs",
    "field_errors": [
        {
            "param": "SIN",
            "msg": "wrong format"
        }
    ]
}

POS API v2.5 - Reference

POS API Endpoint Overview

POS API - Widget

Endpoints: Authentication

POST /oauth/token

Parameters:

Validations:

Example Value:

Success Response:

200 - Success

POST /client-id/{client_id}/merchants/login

Parameters:

Validations:

Example Value:

Success Response:

200 - Success

Endpoints: CreditApps

GET /client-id/{client_id}/terms-and-conditions

Parameters:

Validations:

Example Value:

Success Response:

200 - Success

POST /client-id/{client_id}/apply

Parameters:

Example Value:

Success Response:

200 - Success - ROC applicant

200 - Success - QC applicant

Error Responses:

401 - Unauthorized - Invalid Token

400 - Conflict - Invalid Client

400 - Conflict - Invalid client ID

400 - Conflict - Invalid grant type

409 - Required Parameters

409 - No TOS

409 - Existing Customer

409 - Credit App Not Found

409 - Application Declined

409 - Application Creation Error

409 - Application Marked Pending

409 - Application Declined 2

409 - Application Declined 3

409 - Application Marked Pending 2

409 - SIN Wrong Format