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.

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 two sets of keys. One for testing in our TRAINING environment and one for running live transactions in our PRODUCTION 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

• Go to our Developer Portal

• Create a Developer Portal Account to receive API keys and set up your trust URL (or IP).

  • Be sure to keep them secure!

• 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

TRAINING and PRODUCTION environments

All API requests exist in both TRAINING and PRODUCTION environments, and objects - customers, plans, transactions, and so forth created in one environment do not exist in the other. The TRAINING and PRODUCTION environments function almost identically, with a few necessary differences.

In our TRAINING environment:

• transactions and customer accounts generated in this environment are only treated as test objects.

• our training environment is scrubbed from time to time

• This environment is considered a “test” environment

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

In our PRODUCTION environment:

• Customer accounts generated in this environment hit the Credit Bureau

• Transactional data generated in this environment are stored in Flexiti’s production systems

• This environment is considered a “Live” production environment

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

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