Merchant Integration Endpoints - POS API

Owned by PC (Unlicensed)
Last updated: Jun 28, 2022 by Arthur Zhao
12 min read

These endpoints support Merchant integrations of Flexiti services.

POST /oauth/token

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}/terms-and-conditions

  • POST /client-id/{client_id}/customers/driverslicense

  • POST /client-id/{client_id}widget/init

  • POST /client-id/{client_id}/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

Type

Parameter

Required

Details

FORMDATA

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

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

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:

{ "client_id": "flexitidemo", "client_secret": "77xde15a-9d33-4c15-930a-3se4b3as33e9", "grant_type": "client_credentials", "scope": "merchant" }

 

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

 

GET /client-id/{client_id}/i18n

Or

  • 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

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

lang



  • ASCII string (5)

  • Customer Preferred language

  • Available values: (en=English) or (fr=French)

  • Default value: en

QUERY

{key}



  • ASCII string (1000)

  • Specific values can be used to filter the response

  • Not passing a value will response with all messages.

  • Available values:

    • salutation

    • provinces

    • security_id

    • govid_type

    • govid_issued_by

    • occupation

    • transaction_type

    • plan_id

    • qcpa_disclosure

    • insurance

    • insurance_tc

    • annual_fees

    • housing_type

Success Response:

 

POST /client-id/{clientId}/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