Overview

Flexiti’s API provides merchants integration with Flexiti both at the point of sale and existing eCommerce platforms.

With a quick and easy integration, merchants can:

• Have customers apply for financing towards products during the checkout flow

• Post transactions, cancel pending transactions, as well as perform full or partial returns

• Look up customer accounts and retrieve historical transactions on a per store basis

This guide will help you identify the steps required to use the Flexiti’s API. The information provided by the API will allow a comprehensive integration of the Flexiti features with your system, and provide a real-time back and forth between your system and Flexiti’s.

Channels

Our API is designed to work for both in-store and ecommerce integrations and we have two “channels” to support this. Each channel uses the same endpoints with slight changes in paramters.

• “In-store” - denotes in-store point of sale integrations where the customer is present

• “Online” - denotes online ecommerce integrations where the customer is not present

Technology

Flexiti’s API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes that indicate errors in simple language.

Environments

Developers have access to three different environments: TRAINING, MERCHANT INTEGRATION, and PRODUCTION.

All API requests exist in TRAINING, MERCHANT INTEGRATION, and PRODUCTION environments. All objects - customers, plans, transactions, etc. created in one environment do not exist in the others.

Our TRAINING environment:

• For most implementations, our Training environment will be all you need to launch your project with Flexiti.

• This environment is a sandbox for testing that uses the same code base as our current production environment.

• Transactions and customer accounts generated in this environment are treated as test objects and is test data is scrubbed daily.

• References: https://posapi-training.flexiti.fi/flexiti/pos-api/

Our MERCHANT INTEGRATION environment:

• This environment is a sandbox for integrating new features for upcoming Flexiti releases.

• We introduce pre-release code to this environment to give Merchants an opportunity to integrate the new features and functionality ahead of our Production release.

• Here is our API Changelog & Release Schedule

• References: https://posapi-mi.flexiti.fi/flexiti/pos-api/

Our PRODUCTION environment:

• This environment is the “Live” production environment.

• Customer accounts generated in this environment hit the Credit Bureau and any Transactional data generated is real.

• References: https://posapi.flexiti.fi/flexiti/pos-api/

Authentication

The Flexiti API uses API keys to authenticate requests. Your keys consist of a Client ID and a Client Secret. You can view and manage your API keys in the Development Portal. If you do not include your keys when making an API request, or use one that is incorrect, Flexiti returns an error.

Every account is provided with sets of keys for each environment.

Please note that the API requires a series of steps for the purpose of securing the connection between servers; as well as define certain parameters such as the Trust URL (or IP.)

All API requests must be made over HTTPS from your trust URL performed via HTTP Basic Auth. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Provide your API keys to generate a Bearer Token that needs to be used as part of every future request.

Obtaining your Flexiti API Keys

• Create a Developer Portal Account(s) to receive your API keys:

  • Developer Portal - Training Environment

  • Developer Portal - Merchant Integration Environment

• Review the API documentation

• Use your credentials using Postman or Swagger

• Implement the TRAINING (test) version on your Staging environment and test thoroughly

• Implement the PROD (live) version on your Production environment and review

Errors

Flexiti uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a transaction failed, etc.). Codes in the 5xx range indicates an error with Flexiti's servers.

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

Error Handling

Our API libraries raise exceptions for many reasons, such as a failed transactions, invalid parameters, authentication errors, and customer account statuses. We recommend writing code that gracefully handles all possible API exceptions.

Flexiti API Parameter Types

• Header [HEADER]

  • These are the parameters which need to be included in the request header

• Path [PATH]

  • These parameters are variable parts within the path of the endpoint.

  • The URL can have several path parameters and are used to point to a specific resource within a collection, such as a Customer identified by ID.

  • They should be placed before the query string (?) and are set off within curly braces { }

  • Each path parameter must be substituted with an actual value when the client makes an API call.

• Query [QUERY]

  • Query parameters appear at the end of the request URL after a question mark (?), with different name=value pairs separated by ampersands (&).

  • Query parameters can be required and optional. Required values are noted in the documentation below.

• Request Body [BODY]

  • These are parameters are values included in the request body.

  • They are submitted as JSON

Versioning

When we make backwards-incompatible changes to the API, we release new versions. The current version is version 2.5. A Change log can be found here -https://flexiti.atlassian.net/wiki/x/GQCRAg

We strive to avoid making any changes to our API that will break the contract, but we do make changes over time that may result in changes to the data that you request from us.

We consider the following changes to be backwards compatible:

• Adding new API endpoints

• Adding new parameters to existing endpoints

• Adding new data elements to existing response schema

• Adding new error types and error response codes

• Changing the length or content of any API parameter