GuidesAPI Reference
Log In
Guides

Flex Capital Implementation Guide

Flex Capital Integration Guide

This guide walks you through the complete end-to-end integration process for Flex Capital, from initial account registration through to taking advances.

Overview

Flex Capital is not a specific type of advance - it's a facility that provides merchants with a pre-authorised limit that can be used across all Liberis products. Once a merchant has Flex Capital activated, they can apply for BCA advances with streamlined eligibility checks and simplified contracts.

Integration Flow

1. Account Registration and Provisioning

Start by registering and provisioning the merchant's account using the business registration API:

POST /v3/business/register_and_provision

This creates and provisions a capital account for the merchant in the Liberis system, making it immediately ready for use.

2. Check Flex Capital Eligibility

After registration, check if the account has Flex Capital upgrade actions available:

GET /v3/business/{liberisId}/capital_account

Look for availableActions in the response. If the merchant is eligible for Flex Capital, you'll see an action with actionType: "UPGRADE_TO_FLEX_CAPITAL".

Important: Handling Frozen Accounts

If the account has been frozen (due to payment issues, compliance concerns, or other business reasons), the merchant will not be eligible for Flex Capital upgrades. Frozen accounts will:

  • Not have UPGRADE_TO_FLEX_CAPITAL in their availableActions
  • Receive marketing offers with doNotMarket: true
  • Need to resolve the underlying issues before being eligible again

Check the statusFlags in the capital account response for any freeze indicators.

3. Marketing Offer Webhook

You'll also receive a marketing offer webhook indicating the merchant's eligibility for a Flex Capital upgrade. The offer is reported at offerLevel: "ACCOUNT" with type: "FLEX_UPGRADE", and includes:

  • limits.min / limits.max - the amount range the merchant may be eligible for
  • approvalStatus - one of SPECULATIVE, ELIGIBLE, PRE_APPROVED, NO_DECISION_NEEDED

This offer does not itself contain specific split percentages or a firm pre-authorised limit - it only signals that the merchant may be eligible for an upgrade within that amount range. Use it to decide whether to prompt the merchant that they may be eligible for a Flex Capital upgrade.

4. Quote Flex Capital Upgrade Options

Only once the merchant indicates they want to apply for the upgrade should you quote the available options:

POST /v3/business/{liberisId}/capital_account/flex_capital/upgrade/options

Provide creditBureauCheckConsent in the request. The response contains an options array, where each option has an optionId, splitPercentage, and preAuthorisedLimit. This is the point at which the merchant is given the different split percentages to choose between - not at the marketing offer stage.

5. Present Options to Merchant

Each option returned by the quote call has a different:

  • Split percentage - the percentage of daily revenue that goes toward payment
  • Pre-authorised limit - the maximum amount available for instant advances

Present these options to the merchant so they can pick the one they want to apply for.

6. Test Pricing (Optional)

Before the merchant commits to an option, you can test pricing for specific amounts:

POST /v3/business/{liberisId}/capital_account/flex_capital/upgrade/price_test

This allows merchants to see exactly what different amounts would cost before upgrading. Provide an optionId and amount to get detailed fee breakdowns and estimated payment times.

7. Apply for Flex Capital Upgrade

Once the merchant selects an option, apply for the upgrade:

POST /v3/business/{liberisId}/capital_account/flex_capital/upgrade/apply

Provide the selected optionId from the quoted options.

8. Contract Signing

The response includes a contractPackId that needs to be signed. Use the Contracts API to present the documents to the merchant for signing:

GET /v3/contract_packs/{contractPackId}

Follow the contract signing flow as documented in the Contracts API guide.

9. Liberis Decision Process

After contract signing, Liberis will:

  1. Review the application
  2. Make a final decision on the upgrade
  3. Update the account status

10. Flex Capital Activation

Once approved, the merchant's capital account will be updated with pre-authorised limit information. You can verify this by checking the capital account:

GET /v3/business/{liberisId}/capital_account

11. Understanding Pre-Authorised Limits

The Flex Capital facility provides two key metrics for managing available funding:

  • Pre-authorised Limit - The total amount approved for the merchant (e.g., $10,000)
  • Remaining Limit - How much of that limit is still available to use

For example:

  • If a merchant has a $10,000 pre-authorised limit
  • And they've taken a $3,000 advance that's still being paid back
  • Their remaining limit would be $7,000

This remaining amount represents what they can immediately access for new advances without additional underwriting.

12. Using Flex Capital for Advances

Now the merchant can apply for BCA advances with streamlined processing:

POST /v3/business/{liberisId}/capital_account/advances/bca/quote
POST /v3/business/{liberisId}/capital_account/advances/bca/apply_by_quote_id

Benefits of Flex Capital for advances:

  • Automatic eligibility - no additional underwriting needed for amounts within remaining limit
  • Simplified contracts - reduced documentation requirements
  • Instant approval - for amounts within the remaining pre-authorised limit
  • Consistent terms - split percentage already agreed

The advance will be processed using the existing Flex Capital terms. The amount taken will reduce the remaining limit until the advance is paid back.

13. Limit Management

As advances are taken and paid back:

  • Taking an advance reduces the remaining limit
  • Making payments increases the remaining limit back toward the total pre-authorised amount
  • The total pre-authorised limit stays constant unless the merchant upgrades to a higher tier

Monitor the remaining limit to help merchants understand their available funding capacity.

Upgrade and Downgrade Flows

The diagrams below summarise the end-to-end sequence of calls and webhooks for taking a Flex Capital upgrade, and for a merchant's terms being downgraded afterwards. The upgrade decision flow is reported through the upgradeStatusChanged webhook (PENDING, UPGRADED, REJECTED, CANCELLED), while a completed upgrade or downgrade is signalled at the account level through the accountStatusChanged webhook (changeType: UPGRADED / DOWNGRADED) — see Key Integration Points below.

Upgrade Flow

sequenceDiagram
    actor M as Merchant
    participant P as Partner
    participant L as Liberis

    P->>L: GET /v3/business/{liberisId}/capital_account
    L-->>P: availableActions includes UPGRADE_TO_FLEX_CAPITAL
    L-->>P: marketingOfferCreated webhook (offerLevel: ACCOUNT, type: FLEX_UPGRADE, limits min/max, approvalStatus)
    P->>M: Merchant may be eligible for a Flex Capital upgrade
    M->>P: Wants to apply
    P->>L: POST .../flex_capital/upgrade/options {creditBureauCheckConsent}
    L-->>P: options[] (optionId, splitPercentage, preAuthorisedLimit)
    P->>M: Present upgrade options
    opt Price testing
        P->>L: POST .../flex_capital/upgrade/price_test
        L-->>P: Fee breakdown for amount
    end
    M->>P: Selects an option
    P->>L: POST .../flex_capital/upgrade/apply {optionId}
    L-->>P: contractPackId, status: PENDING
    L-->>P: upgradeStatusChanged webhook (status: PENDING)
    P->>M: Present contract pack for signing
    M->>P: Signs documents
    P->>L: GET /v3/contract_packs/{contractPackId} (signing flow)
    L-->>L: Reviews application, makes decision
    alt Upgrade approved
        L-->>P: upgradeStatusChanged webhook (status: UPGRADED)
        L-->>P: accountStatusChanged webhook (changeType: UPGRADED)
        L-->>P: accountStatusChanged webhook (changeType: PRE_AUTHORISED_LIMIT_CHANGED)
        P->>L: GET /v3/business/{liberisId}/capital_account
        L-->>P: preAuthorisedLimit active
    else Upgrade rejected
        L-->>P: upgradeStatusChanged webhook (status: REJECTED)
    else Merchant cancels before a decision is made
        P->>L: POST .../flex_capital/upgrade/cancel
        L-->>P: upgradeStatusChanged webhook (status: CANCELLED)
    end

Downgrade Flow

sequenceDiagram
    actor M as Merchant
    participant P as Partner
    participant L as Liberis

    Note over P,L: Downgrade can only happen after an upgrade has already completed
    M->>P: Requests to downgrade (or partner/Liberis initiates)
    P->>L: POST /v3/business/{liberisId}/capital_account/flex_capital/upgrade/downgrade
    L-->>L: Reverts split percentage and pre-authorised limit
    L-->>P: accountStatusChanged webhook (changeType: DOWNGRADED)
    L-->>P: accountStatusChanged webhook (changeType: PRE_AUTHORISED_LIMIT_CHANGED)
    P->>L: GET /v3/business/{liberisId}/capital_account
    L-->>P: Updated (reverted) pre-authorised limit and split
    P->>M: Confirms new terms

Key Integration Points

Webhooks to Monitor

  • liberis.capitalAccounts.v3.marketingOfferCreated - Flex Capital upgrade eligibility (offerLevel: ACCOUNT, type: FLEX_UPGRADE, amount range, approvalStatus) - call the quote options endpoint to get specific split percentages and limits
  • liberis.capitalAccounts.v3.upgradeStatusChanged - Upgrade decision updates (PENDING, UPGRADED, REJECTED, CANCELLED) — see the Upgrade and Downgrade Flows above
  • liberis.capitalAccounts.v3.advanceStatusChanged - Advance status for flex-enabled accounts
  • liberis.capitalAccounts.v3.accountStatusChanged - Account-level changes, including freeze/unfreeze, pre-authorised limit changes (PRE_AUTHORISED_LIMIT_CHANGED), and completed upgrades and downgrades (changeType: UPGRADED / DOWNGRADED)

Error Handling

  • UPGRADE_NOT_ELIGIBLE - Merchant doesn't qualify for Flex Capital
  • INVALID_OPTION_ID - Selected option is no longer available
  • AMOUNT_OUT_OF_RANGE - Requested amount exceeds remaining pre-authorised limit
  • FROZEN - Account is frozen and cannot access Flex Capital

Testing Considerations

  • Use the price test endpoint to validate calculations before presenting to merchants
  • Verify contract signing flow works with Flex Capital contract packs
  • Test the complete flow from upgrade through to taking advances
  • Test scenarios with frozen accounts to ensure proper error handling
  • Verify limit calculations work correctly as advances are taken and paid back

Summary

Flex Capital provides a powerful way to offer merchants pre-authorised funding with transparent terms. The integration involves:

  1. Registration - Create and provision the merchant account
  2. Eligibility - Check for upgrade actions and handle frozen accounts
  3. Selection - Present options and allow price testing
  4. Application - Apply for the chosen Flex Capital option
  5. Contracts - Complete document signing
  6. Activation - Verify the pre-authorised limit is active
  7. Usage - Take streamlined advances using the remaining facility
  8. Management - Monitor and communicate available limits

This creates a seamless experience where merchants get fast access to funding with predictable terms across all Liberis products, while maintaining clear visibility into their available capacity.

Updated 4 days ago

Did this page help you?