Overview

Liberis offers a V2 to V3 migration service that enables Partners to gradually transition an existing V2 merchant base onto Capital Platform.

This document describes the external interface of the migration service and provides guidance on how to integrate with it.

Migration Order

The complexity of migrating a merchant will depend on how far they have progressed on the BCA Platform rails.

We will therefore divide the merchant base into several cohorts that can be incrementally migrated in order of least to most complex.

Availability will follow this order:

1. New merchants – never onboarded to BCA Platform (i.e no quotes).
2. Merchants never funded - started applying for BCA Platform advance, but never funded.
3. Previously funded merchants - have one or more previously funded BCA Platform advances, but not currently funded or applying.
4. Active merchants – mid way through applying for or repaying a BCA Platform advance

ℹ️

When is a merchant considered to be on the BCA Platform?

For Partners using create, a merchant will be considered on the BCA Platform at the moment when an offer is generated via a POST request to create/v2/offers

Communicating Migrations via Webhook

Migration Sync Mechanism

To ensure there is no ambiguity as to which rail a merchant should be routed to, Liberis will send a webhook notification whenever a merchant is migrated to Capital Platform.

Unlike more ad-hoc approaches a webhook will provide consistency whilst still being flexible enough to migrate merchants at whatever pace is mutually sustainable.

Webhook Flow

• For each merchant, the partner should keep track of which rail the merchant is on
• Liberis triggers migration of a merchant:
  • BCA Platform rails go into read only mode
  • A new Capital Account is created on the Capital Platform rails.
  • Migration completed webhook is fired.
• Partner marks the merchant as being on the new Capital Platform rails, taking note of any IDs contained in capitalAccountIdentifiers
• The next interaction from the merchant should then be directed to the new rails. If capitalAccountIdentifiers was not null, then registration must be skipped, otherwise proceed as normal.

ℹ️

Past advances made on the BCA Platform

Advances or applications made on the BCA Platform are not carried across to Capital Platform. The migrator service will create a new, empty account.

Webhook payload

Once a merchant has been migrated and is ready to use the new Capital Platform, Liberis will send the following webhook.

{
  "eventId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventDate": "2025-02-01T12:01:02-05:00",
  "type": "liberis.capitalAccounts.v3.accountMigrated",
  "data": {
    "migrationDate": "2025-02-01T12:01:02-05:00",
    "partnerClientIds": [
      "string"
    ],
    "legacyIdentifiers": {
      "liberisId": "string"
    },
    "capitalAccountIdentifiers": {
      "liberisId": "string",
      "capitalAccountId": "string",
      "merchantPaymentAccountId": "string"
    },
    "businessSummary": {
        "previouslyFunded": false
    }
  }
}

Note: capitalAccountIdentifiers may be null. See below for an explanation.

Handling multiple partnerClientIds

The Capital Platform has stricter validation rules than the BCA Platform. This presents us with the interesting edge case of discovering mid-migration that two or more partnerClientIDs refer to the same business. In these situations we reserve the right to merge these two identities by including both partner client IDs in the migration webhook response.

This is not functionality that is currently implemented, but the webhook has been designed with this future enhancement in mind. Confirmation of the correct way to handle this behaviour will be confirmed as and when it is implemented.

Handling null capitalAccountIdentifiers

capitalAccountIdentifiers may be null. This can be for several reasons including:

• Not enough data in the BCA Platform to provision a Capital Account
• The merchant's data is old enough to fall outside our data retention policy
• Policy prevents merchants in a particular region from registering on Capital Account

In these cases we require that the existing routing of the merchant to be forgotten. That is, if they subsequently return they must be directed straight to Capital Platform as if being introduced to Liberis for the first time.

ℹ️

Synonyms of partnerClientId

On the BCA Platform, you may have heard partner client ID called 'merchant ID' or 'merchant reference'

Subsequent calls to the BCA Platform Rails

There are two edge cases to be aware of.

• If a merchant returns to the BCA Platform while a migration is in progress, calls to the old API will return an error message indicating temporary unavailability and that the caller should try again shortly.
• If a merchant returns to the BCA Platform after a migration is completed, calls to the old API will return an error message indicating that this merchant has been migrated. This accounts for the race condition in which the webhook has not been fully processed in time.

ℹ️

How long will a migration take?

Migration should happen in near real time, i.e. measured in seconds, not minutes.

Cohorts

In this section we will explore in more detail the strategy for migrating each cohort.

New merchants

Definition: Never onboarded to BCA Platform (no quotes).

Strategy: No migration needed, should already be directed to new platform.

Merchants never funded

Definition: Merchants who started applying for a BCA Platform advance, but were never funded. The earliest point a merchant is considered for this cohort will be if they received a quote. Merchants who dropped out before quoting are not considered to be on the BCA Platform.

Strategy:

• During migration, Liberis will:
  • Migrate business details across to the Capital Platform
  • Provision capital accounts for these businesses
  • Not migrate existing quotes.
• Partners should:
  • Store the new Capital Platform ID and new Liberis ID against the merchant
  • Configure merchant to be routed to Capital Platform
• When a merchant re-enters the journey (e.g. reacts to marketing or otherwise attempts to apply) the partner should:
  • If capitalAccountIdentifiers for the migration webhook was not null, then:
    • Skip provisioning new capital account or registering a business (i.e /v3/register_business_and_provision_capital_account )
    • Provide up to date business details via PUT to v3/business/{liberisId}
    • Using the Capital Platform Liberis ID that was returned in the webhook (data.capitalAccountIdentifiers.liberisId)
    • Continue the rest of the journey as normal
  • Otherwise register as normal

sequenceDiagram
  actor merchant as Merchant
  participant partner as partner
  participant old_rails as Liberis (BCA Platform)
  participant new_rails as Liberis (Capital Platform)
  
  merchant ->> partner: Start journey
  activate merchant
  merchant ->> old_rails: Get offers
  deactivate merchant
  note over merchant: Merchant drops out of journey
  note over merchant, new_rails: v3 APIs launched
  note over new_rails: Migration triggered
  destroy old_rails
  new_rails ->> old_rails: Retrieve data
  new_rails ->> new_rails: Provision <br/>Capital account
  new_rails ->> partner: Send migration webhook
  partner ->> partner: Switch merchant to new rails and<br/> persist capitalAccountIdentifiers if present
  merchant ->> partner: Start new journey
  activate merchant
  alt capitalAccountIdentifiers was present
    partner ->> new_rails: Provide latest business details
  else capitalAccountIdentifiers was null
    partner ->> new_rails: Register as if new merchant
  end
  deactivate merchant
  note over merchant, partner: New journey continues as normal

Previously funded merchants

Definition: Has one or more paid off BCA Platform advances, currently inactive

Strategy: To be determined

Active merchants

Definition: Midway through first application, or midway through an advance on BCA Platform

Strategy: To be determined