Fully embedded API

Endpoints

This specification describes Flowpay API suite supporting the Fully Embedded (Native) flow, including customer onboarding, account data integration, offer management and financing operations. You can implement fully featured embedded lending solution directly within your web app.

Customers

Handles onboarding and identity verification. Enables activating or cancelling services, updating representatives and retrieving customer profile data—laying the foundation for a compliant lending relationship.
Open Banking

Supports seamless integration with customers’ bank accounts. These endpoints provide transaction and account data, essential for real-time creditworthiness assessments and offer personalization.
Offers

Manages financing offers dynamically. Allows requesting, recalculating, and retrieving personalized loan offers based on up-to-date customer and financial data.
Financings

Covers the full financing lifecycle—from applying for a loan and document signing to managing active financings, prolongations and repayments.

Configuration and authorization

Our API endpoints are secured by a standard OAuth 2.0 Client Credentials Flow suitable for machine-to-machine authorization, so no end-user authorization is needed. Your should only access our secured API endpoints from within a secure backend environment.

As part of partner onboarding process we will provide you with respective credentials enabling you to generate access tokens to access our secured endpoints. These include YOUR_PARTNER_CODE, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET and YOUR_WEBHOOK_SECRET.

Note

Each runtime environment includes its own configuration settings and is secured with separate credentials.

API environment configuration

TestingProduction

API_URL_BASE:  https://api.test.my.flowpay.io
API_TOKEN_URL: https://flowpay-test.eu.auth0.com/oauth/token
API_AUDIENCE:  https://api.test.partner.flowpay.io

API_URL_BASE:  https://api.my.flowpay.io
API_TOKEN_URL: https://flowpay.eu.auth0.com/oauth/token
API_AUDIENCE:  https://api.partner.flowpay.io

Request access token

To access our API, your app must request an access token for it. To do so, you will need to POST to the token URL.

RequestSuccess ResponseError Response

curl --request 'POST' \
--url 'API_TOKEN_URL' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type='client_credentials' \
--data client_id='YOUR_CLIENT_ID' \
--data client_secret='YOUR_CLIENT_SECRET' \
--data audience='API_AUDIENCE'

HTTP 200 OK response with a payload

{
    "access_token":"eyJz93a...k4laUWw",
    "token_type":"Bearer",
    "expires_in":86400
}

HTTP 401 Unauthorized response with a payload

{"error":"access_denied","error_description":"Unauthorized"}

Call API endpoint

To call an API endpoint, your application must pass the retrieved access token as a Bearer token in the Authorization header of the HTTP request.

RequestSuccess ResponseError Response

curl --request 'GET' \
--url 'API_URL_BASE/partner-api/v1/financings' \
--header 'authorization: Bearer ACCESS_TOKEN' \
--header 'content-type: application/json'

HTTP 200 OK response with a payload

[
    {
        "id": "5687646c-6862-4bf2-93e8-47909ba3fa88",
        "customerId": "3e6fe776-8b0c-4329-8980-8efa1ef52778",
        "state": "NEW",
        "createdAt": "2025-02-05T16:42:53.586618Z"
    }
]

HTTP 401 Unauthorized response with a payload

{
    "message": "Unauthorized",
    "logref": "0d3d0bde-6d73-9d37",
    "_embedded": {
        "errors": [
            {
                "message": "Unauthorized"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "/partner-api/v1/financings",
            "templated": false
        }
    }
}

Principles and standards

Flowpay API follows REST approach with resource oriented URLs, JSON encoded request and response messages, standard HTTP verbs and response codes.

Error handling

Flowpay API uses standard HTTP response codes to indicate the success or failure of an API request.

HTTP 400 Bad RequestHTTP 401 UnauthorizedHTTP 403 ForbiddenHTTP 404 Not FoundHTTP 422 Unprocessable Entity

We return an HTTP 400 Bad Request response for requests that do not pass syntactic validation. E.g. invalid string size, etc. The payload contains the respective errors.

{
    "message": "Bad Request",
    "logref": "2f6d9e4d-0dba-fe11",
    "_embedded": {
        "errors": [
        {
            "message": "dto.company.country: size must be between 2 and 2"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/customers/service-activation",
        "templated": false
        }
    }
}

We return an HTTP 401 Unauthorized response for requests that lack valid authentication credentials or fail to provide any authentication information when it is required.

{
    "message": "Unauthorized",
    "logref": "6a127f89-795e-2369",
    "_embedded": {
        "errors": [
        {
            "message": "Unauthorized"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/financings/000e788d-85db-4ab7-bb63-2712c84c4d6a",
        "templated": false
        }
    }
}

We return an HTTP 403 Forbidden response for requests that are authenticated but do not have the necessary permissions to access the requested resource.

{
    "message": "Forbidden",
    "logref": "345a3136-08f5-2c3b",
    "_embedded": {
        "errors": [
        {
            "message": "Forbidden"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/financings/000e788d-85db-4ab7-bb63-2712c84c4d6a",
        "templated": false
        }
    }
}

We return an HTTP 404 Not Found response to requests to non existing resources.

{
    "message": "Not Found",
    "logref": "1997634a-f538-12a2",
    "_embedded": {
        "errors": [
        {
            "message": "Not found"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/financings/dee4f1e0-8a08-4484-bcc7-e785479b4bad",
        "templated": false
        }
    }
}

We return an HTTP 422 Unprocessable Entity response to requests that failed business validations. E.g. form submit that cannot be processes as the data are not valid. The payload contains the respective errors.

{
    "message": "Unprocessable Entity",
    "logref": "63f993f1-e0d0-d28d",
    "_embedded": {
        "errors": [
        {
            "message": "INVALID_BUSINESS_ID"
        }
        ]
    },
    "_links": {
        "self": {
        "href": "/partner-api/v1/customers/service-activation",
        "templated": false
        }
    }
}

Webhooks

Webhooks enable your system to receive instant notifications about important events from our API. When key events occurs, our system automatically sends updates to your specified endpoint, allowing your application to respond in real-time. This creates a seamless and efficient integration between our services.

Completion of customer scoring
Changes in financing status
Identity verification results

To receive webhook events from Flowpay in your web application, you must:

Implement HTTP endpoints to handle incoming webhook requests
Verify the authenticity of each webhook by implementing message authentication
Share the endpoint URL with Flowpay

Best practice for webhook handler implementation

Respond with HTTP 200 OK immediately upon receiving the webhook, before processing the payload
Process the webhook payload asynchronously to avoid blocking the response
Handle webhook processing errors gracefully without rejecting the webhook request
Verify the webhook signature before processing
Check the timestamp to prevent replay attacks
Return HTTP 200 even if signature verification fails to prevent unnecessary retries

Webhook message authentication and replay attack prevention

To verify authenticity and integrity of the events that Flowpay sends to your webhook endpoints we include x-flowpay-sig header with a message signature in each request. To prevent replay attacks we include x-flowpay-ts header with a message timestamp in each request.

The signature is generated using a hash-based message authentication code (HMAC) with SHA-256 hash function, the secret YOUR_WEBHOOK_SECRET shared with you during onboarding process as the key and the actual JSON payload from the webhook request concatenated with the message timestamp from request header as the message. To construct the message for HMAC calculation concatenate the actual JSON payload of the webhook request with the timestamp from request header x-flowpay-ts.

To verify the signature, compare the result of your HMAC calculation with the content of x-flowpay-sig header.

Webhook message and signature example

Let's assume YOUR_WEBHOOK_SECRET = secret

Received webhook request payload

{"id":"5653fdfe-8b71-4c2d-b070-d0fda1d10000","state":"NEW","effectiveAt":"2023-06-30T12:05:28.466076Z"}

Received webhook request headers

x-flowpay-ts: 2023-06-30T12:05:28.521071Z
x-flowpay-sig: 460d5701cb35f9dfc699423a76a952c747f32a6ccdf5da18f8f9955f03ebd8b7