Online API Endpoints Reference

Owned by Sahana Sivakumar (Deactivated)
Last updated: Oct 12, 2022 by Arthur Zhao
15 min read

POST /oauth/token

https://onlineapi.flexiti.fi/flexiti/online-api/oauth/token

This service Authenticates the developer user and provides a Bearer Token that needs to be used as part of every future request.

The auth token is active for 20 minutes and 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. You can follow the guide here on how to implement the refresh token: https://flexiti.atlassian.net/l/c/UxFd6Vg5

To use it add the refresh token (provided in the original /oauth/token call) and change the grant_type to refresh_token.

 NOTE: The API request must be passed in the x-www-form-urlencoded format, or you will receive an error.

Request Parameters:

Type

Parameter

Required

Details

FORMDATA/BODY

client_id

Yes

  • ASCII string (100)

  • This is the Client ID given in the Developer User Account section

FORMDATA/BODY

client_secret

Yes

  • ASCII string (100)

  • This is the Client Secret given in the Developer User Account section

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

FORMDATA/BODY

grant_type

No

  • ASCII string

  • This is the client's access type

  • possible values: 'password', 'refresh_token', 'client_credentials'

  • default value: 'client_credentials'

FORMDATA/BODY

refresh_token

Yes - If grant_type = “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.

FORMDATA/BODY

scope

No

  • ASCII string

  • Available values: ‘customer', 'merchant’

  • Default value: merchant

 Example Request:

Response Parameters:

Type

Parameter

Details

Type

Parameter

Details

BODY

access_token

  • Bearer token to be used in subsequent calls

BODY

expires_in

  • Time, in seconds, that the token will last

BODY

refresh_token

  • Token to be used to refresh the access_token

 

Success Response:

{ "token_type": "bearer",   "access_token": "2d8f373a3c2b1e61baf5a7769930ff4f0e08cdb0",   "expires_in": 1200,   "refresh_token": "36e0fc3d7415145f4b1d71512c459fd6eaa13aa8", "scope": "merchant" }

POST /online/v2/client-id/{clientId}/systems/init

https://onlineapi.flexiti.fi/flexiti/online-api/online/v2/client-id/{{client_id}}/systems/init

This endpoint will return the Flexiti Online Flow as a Redirect URL, which can be hosted in a Modal (Preferred presentation method).

*NOTE: If you are integrating the APPLY-ONLY flow, please remove ‘/v2’ from the API URI, this will ensure that the flow opened immediately starts the application flow.

Request Parameters:

Type

Parameter

Required

Details

HEADER

authorization

Yes

  • ASCII string (40)

  • 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}

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

PATH

client_id

Yes

  • ASCII string (100)

  • This is the Client ID given in the Developer User Account section

BODY

merchant_orderid

Optional

  • ASCII String

  • Optional field provided by the merchant (Typically the order ID in the Merchant Shopping Cart). This value can be used to request information from Flexiti regarding the transaction in the GET /notifications/merchant-order-id/{merchant-order-id} endpoint.

BODY 

is_guest

Optional

  • Boolean

  • Identifies if the current shopping cart user is running a guest session. Is useful to identify the application risk

  • Default value: false

 BODY

customer_id

Optional - Required for Buy Flow if VCC is not provided

  • ASCII string (20)

  • Value helps in identifying customer if their customer-id is already known (i.e. Merchant can save a customer’s Flexiti customer-id to be associated with their merchant profile). This makes it easier for the Flexiti Online flow to identify the customer account, taking them directly to checkout.

 BODY

vcc

Optional - Required for Buy Flow if customer_id is not provided

  • ASCII string (16)

  • The FlexitiCard Number (VCC) of the Customer. If provided, takes the customer directly to the checkout flow.

 BODY

has_previous_purchase

Optional

  • Boolean

  • Help identify if the current shopping cart user has previously purchased using your online site. This field helps us to identify if the user’s information is trusted.

 BODY

lang

Yes

  • ASCII string (5)

  • Language to be displayed to the customer: French or English

  • Possible Values: “en-CA” or “fr-CA” ← Case Sensitive.

 BODY

flow

Yes

  • ASCII string (10)

  • Flow field indicates the action the customer is looking to perform, either a:

    • stand-alone application: Customer only wants to do an application, does not want to complete purchase immediately

    • buy: customer already a FlexitiCard holder, and is able to provide the VCC #

    • apply/buy (Customer is not yet a FlexitiCard holder, and wishes to apply in the cart and proceed to purchase directly after as a single action)

  • Possible Values: “apply”, “buy”, “apply/buy”

 BODY

amount_requested

Yes

  • number (18,2)

  • Credit amount requested by the customer, means different things depending on the flow value:

    • If flow is “buy” or “apply/Buy, “amount_requested” is the cart total the customer is trying to checkout with using Flexiti.

    • If flow is “apply”, “amount_requested” is the amount the customer is applying credit for. Uses a default value parameterized in your account if no value is provided.

 BODY

salutation

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (4)

  • Salutation

  • Available values: (mr = Mr./M.), (ms = Ms./Mme.), (mrs = Mrs.), (mss = Miss.)

 BODY

email

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (75)

  • Characters allowed: Email format and [a-z A-Z 0-9 .!#$%&'+/=?^_`{|}~-]+

  • Customer Email

  • This will be used for MFA

 BODY

phone_number

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (10)

  • Customer Mobile Phone Number

    • Phone number should not start with a 0/1

    • Phone number should only contain numeric values

    • Phone numbers using only single digit will not be allowed (ex. 5555555555)

    • Phone number should be 10 digits (i.e. not include country codes)

  • This will be used for MFA via SMS

 BODY

fname

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (35)

  • Characters allowed: Alphanumeric and _ . ‘ -

  • Customer First Name

 BODY

mname

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (114)

  • Characters allowed: Alphanumeric and _ . ‘ -

  • Customer Middle Name

 BODY

lname

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (50)

  • Characters allowed: Alphanumeric and _ . ‘ -

  • Customer Last Name

 BODY

dob

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (10)

  • Format: DD/MM-YYYY

  • Customer Date of Birth

BODY

address_1

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (150)

  • Characters allowed: Alphanumeric and # _ - .

  • Customer Address Line 1

 BODY

address_2

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (143)

  • Characters allowed: Alphanumeric and # _ - .

  • Customer Address Line 2

 BODY

city

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (50)

  • Characters allowed: Alphanumeric and _ . ‘ -

  • Customer City

 BODY

province

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (2)

  • 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

Optional - Helps pre-populate application form during “Apply” and “Apply/Buy” flow if information is available

  • ASCII string (6)

  • Customer Postal Code

BODY

billing_information.first_name

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (80)

  • Information used to match/verify the Account details on file

  • Billing Address Customer’s First Name

BODY

billing_information.last_name

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (130)

  • Information used to match/verify the Account details on file

  • Billing Address Customer’s Last Name

BODY

billing_information.address_1

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (250)

  • Information used to match/verify the Account details on file

  • Billing Address Line 1

BODY

billing_information.address_2

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (100)

  • Information used to match/verify the Account details on file

  • Billing Address Line 2

BODY

billing_information.city

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (100)

  • Information used to match/verify the Account details on file

  • Billing address city

BODY

billing_information.province

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (2)

  • Information used to match/verify the Account details on file

  • Billing Address Province (2 character syntax, ex. ON for Ontario)

  • Available values: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT.

BODY

billing_information.postal_code

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (10)

  • Information used to match/verify the Account details on file

  • Billing Address Postal Code

BODY

shipping_information.first_name

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (80)

  • Information used to match/verify the Account details on file

  • Shipping Address Customer’s First Name

BODY

shipping_information.last_name

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (130)

  • Information used to match/verify the Account details on file

  • Shipping Address Customer’s Last Name

BODY

shipping_information.address_1

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (250)

  • Information used to match/verify the Account details on file

  • Shipping Address Line 1

BODY

shipping_information.address_2

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (100)

  • Information used to match/verify the Account details on file

  • Shipping Address Line 1

BODY

shipping_information.city

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (100)

  • Information used to match/verify the Account details on file

  • Shipping Address City

BODY

shipping_information.province

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (2)

  • Information used to match/verify the Account details on file

  • Shipping Address Province (2 character syntax, ex. ON for Ontario)

  • Available values: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT.

BODY

shipping_information.postal_code

Yes if Flow is “Buy” or “Apply/Buy”

  • ASCII string (10)

  • Information used to match/verify the Account details on file

  • Shipping Address Postal Code

 

 Example Request - Flow = “apply”:

 Example Request - Flow = “buy”:

 Example Request - Flow = “apply/buy”:

 

Response Parameters:

Type

Parameter

Details

BODY

online_order_id

  • Integer

  • Flexiti-generated online order id assigned to the transaction, can be used to retrieve transaction status

BODY

redirection_url

  • ASCII string

  • Redirection URL that opens up the Flexiti Online Experience.

 Success Response:

GET /online/v2/client-id/{clientId}/systems/payment-calculator

Request Parameters:

Type

Parameter

Required

Details

HEADER

authorization

Yes

  • ASCII string (40)

  • 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}

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

PATH

client_id

Yes

  • ASCII string (100)

  • This is the Client ID given in the Developer User Account section

QUERY

price

Yes 

  • NUMBER (18,2)

  • This is the price for the product/cart that needs calculation on

 QUERY

lang

Yes 

  • ASCII string (2)

  • customer’s preferred language for localization of the PC

  • Available values: en, fr

  • Default value: en

 

Sample Request:

Response Parameters:

Type

Parameter

Details

BODY

htmlRender

  • ASCII string

  • HTML-formatted text containing the Flexiti Logo + Payment Calculator language.

BODY

paymentPlan.monthlyPayment

  • ASCII string

  • Monthly payment customer is expected to pay on the item if they checked out using Flexiti for financing

BODY

paymentPlan.months

  • ASCII string

  • Term length of the Flexiti payment plan

Success Response:

GET /online/client-id/{clientId}/notifications/order-id/{orderId}

Request Parameters:

Type

Parameter

Required

Details

HEADER

authorization

Yes

  • ASCII string (40)

  • 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}

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

PATH

client_id

Yes

  • ASCII string (100)

  • This is the Client ID given in the Developer User Account section

PATH

orderId

Yes 

  • Integer

  • The online order id given in the /systems/init endpoint response - used to retrieve information about the transaction 

 

Example Request:

Response Parameters:

Type

Parameter

Details

BODY

transaction_id

  • Integer

  • Flexiti-generated online order id assigned to the transaction, can be used to retrieve transaction status

BODY

flow

  • ASCII string (10)

  • Flow field indicates the action the customer is performed, either a:

    • stand-alone application: Customer only wants to do an application, does not want to complete purchase immediately

    • buy: customer already a FlexitiCard holder, and is able to provide the VCC #

    • apply/buy (Customer is not yet a FlexitiCard holder, and wishes to apply in the cart and proceed to purchase directly after as a single action)

  • Possible Values: “apply”, “buy”, “apply/buy”

BODY

callback_url

  • ASCII string

  • Merchant URL that the Flexiti widget redirected post-transaction processing

BODY

date

  • DATE

  • Date & Time of transaction

BODY

purchase.status

  • ASCII string

  • Status of Purchase

BODY

purchase.administrative_fee

  • ASCII string

  • Applicable administrative fees for the customer on their completed purchase

BODY

purchase.promo_id

  • ASCII string

  • Flexiti Promo id assigned to the order

BODY

purchase.term

  • Number

  • Flexiti financing term, in months

BODY

purchase.plan_id

  • ASCII string

  • Flexiti financing plan_id, represents the specific financing option selected by the customer

BODY

purchase.purchase_amount

  • Number

  • Purchase Total submitted for the customer

BODY

purchase.transaction_total_amount

  • Number

  • Purchase Total inclusive of applicable administrative fee added by Flexiti

BODY

purchase.customer_id

  • ASCII string

  • Flexiti customer identifier, safe for storage

BODY

purchase.customer_comparison_result.shipping_information.province

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.postal_code

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.city

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.address_2

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.address_1

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.dob

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.last_name

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.first_name

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.province

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.postal_code

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.city

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.address_2

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.address_1

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.dob

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.last_name

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.first_name

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

apply.customer_id

  • ASCII string

  • Flexiti customer identifier, safe for storage

BODY

apply_status

  • ASCII string

  • Application Status for the customer

 

Example Response: Buy Flow

Example Response: Apply Flow

GET /online/client-id/{clientId}/notifications/merchant-order-id/{merchantOrderId}

Request Parameters:

Type

Parameter

Required

Details

HEADER

authorization

Yes

  • ASCII string (40)

  • 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}

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

PATH

client_id

Yes

  • ASCII string (100)

  • This is the Client ID given in the Developer User Account section

PATH

merchantOrderId

Yes 

  • ASCII String

  • Provided by the merchant (Typically the order ID in the Merchant Shopping Cart). This value can be used to request information from Flexiti regarding the transaction in the GET /notifications/merchant-order-id/{merchant-order-id} endpoint.

 

Example Request:

Response Parameters:

Type

Parameter

Details

BODY

transaction_id

  • Integer

  • Flexiti-generated online order id assigned to the transaction, can be used to retrieve transaction status

BODY

flow

  • ASCII string (10)

  • Flow field indicates the action the customer is performed, either a:

    • stand-alone application: Customer only wants to do an application, does not want to complete purchase immediately

    • buy: customer already a FlexitiCard holder, and is able to provide the VCC #

    • apply/buy (Customer is not yet a FlexitiCard holder, and wishes to apply in the cart and proceed to purchase directly after as a single action)

  • Possible Values: “apply”, “buy”, “apply/buy”

BODY

callback_url

  • ASCII string

  • Merchant URL that the Flexiti widget redirected post-transaction processing

BODY

date

  • DATE

  • Date & Time of transaction

BODY

purchase.status

  • ASCII string

  • Status of Purchase

BODY

purchase.administrative_fee

  • ASCII string

  • Applicable administrative fees for the customer on their completed purchase

BODY

purchase.promo_id

  • ASCII string

  • Flexiti Promo id assigned to the order

BODY

purchase.term

  • Number

  • Flexiti financing term, in months

BODY

purchase.plan_id

  • ASCII string

  • Flexiti financing plan_id, represents the specific financing option selected by the customer

BODY

purchase.purchase_amount

  • Number

  • Purchase Total submitted for the customer

BODY

purchase.transaction_total_amount

  • Number

  • Purchase Total inclusive of applicable administrative fee added by Flexiti

BODY

purchase.customer_id

  • ASCII string

  • Flexiti customer identifier, safe for storage

BODY

purchase.customer_comparison_result.shipping_information.province

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.postal_code

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.city

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.address_2

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.address_1

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.dob

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.last_name

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.shipping_information.first_name

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.province

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.postal_code

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.city

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.address_2

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.address_1

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.dob

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.last_name

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

purchase.customer_comparison_result.billing_information.first_name

  • number (3,2)

  • Matching score against the customer information Flexiti has on file

BODY

apply.customer_id

  • ASCII string

  • Flexiti customer identifier, safe for storage

BODY

apply_status

  • ASCII string

  • Application Status for the customer

 

Example Response: Buy Flow

Example Response: Apply Flow

POST /online/client-id/{clientId}/merchants/payment-availability

This endpoint compares the checkout total against the available merchant plan ranges to determine if Flexiti should be enabled as a checkout option. 

Request Parameters:

Type

Parameter

Required

Details

HEADER

authorization

Yes

  • ASCII string (40)

  • 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}

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

PATH

client_id

Yes

  • ASCII string (100)

  • This is the Client ID given in the Developer User Account section

BODY

amount_requested

Yes

  • Number (18,2)

  • Checkout total

 

Example Request:

Response Parameters:

Type

Parameter

Details

BODY

enable_payment_gateway

  • Boolean

  • True/False value for whether Flexiti payment should be enabled as an option at checkout

Success Response: