This page describes the onboarding workflow from the first API call to a merchant that is ready to activate FlexFactor on your platform. Each step names the endpoint or webhook it uses and links to the reference page for that endpoint.

Before you start

You need two things in place before you send the first invite:

---

Workflow

%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#3C3C42', 'actorTextColor': '#FFFFFF', 'actorBorder': '#56565E', 'noteBkgColor': '#F8F8F8', 'noteTextColor': '#3C3C42', 'activationBkgColor': '#FF5B5B', 'activationBorderColor': '#E7575B', 'signalColor': '#56565E', 'signalTextColor': '#3C3C42', 'loopTextColor': '#3C3C42', 'labelBoxBkgColor': '#E6E6E6', 'labelTextColor': '#3C3C42'}}}%%
sequenceDiagram
    participant P as Partner
    participant A as Applicant
    participant FF as FlexFactor

    P->>FF: POST /v1/onboarding/application/invite
    FF-->>P: {id, status: "DRAFT"}
    Note over P: Store id. It is the application ID<br/>and the merchant ID (mid).
    FF->>A: Invitation to complete the boarding form
    A->>FF: Completes and submits the application
    FF--)P: webhook: application.submitted
    Note over FF: Risk review (IN_REVIEW)

    opt Status check without webhooks
        P->>FF: GET /v1/onboarding/application/{id}
        FF-->>P: {status}
        Note over P: No more than 1 request per hour<br/>per application
    end

    alt Approved
        FF--)P: webhook: application.approved
        P->>FF: POST /v1/merchants/{mid}/api-keys
        FF-->>P: {appKey, appSecret, clientId}
        Note over P: Store appKey and appSecret<br/>on the merchant record
        opt Partner uses site IDs
            P->>FF: GET /v1/merchants/{mid}
            FF-->>P: {sites: [{id, descriptor}]}
            Note over P: Map each site id to the merchant record
        end
        Note over P: Merchant is ready to activate FlexFactor
    else Declined or canceled
        FF--)P: webhook: application.declined<br/>or application.canceled
        Note over P: Treat the merchant as rejected.<br/>A new invite starts a new application.
    end

---

Steps

1. Invite the applicant

Send the legal entity name, DBA, and primary contact of the merchant you want to onboard. You can also send the full application object to pre-fill the boarding form for the applicant.

The response returns the application id with the status DRAFT. Store the id. It is the application ID for the status endpoint, and after approval it is the merchant ID (mid) on every merchant endpoint.

FlexFactor invites the primary contact to complete the boarding form.

Invite an applicant via POST /onboarding/application/invite

2. The applicant completes and submits the application

The applicant completes the boarding form and submits it. Acceptance of the FlexFactor terms, which authorizes the assignment of rescued receivables, is captured during submission as part of the e-signature step. No separate signature step follows approval.

The application stays in DRAFT until the applicant submits it. When the applicant submits, the status changes to SUBMITTED and FlexFactor sends the application.submitted webhook. No action is required from you at this step.

3. FlexFactor reviews the application

FlexFactor risk reviews the submitted application. During the review the status is IN_REVIEW. The review ends in one of the three outcomes in the table, and FlexFactor sends a webhook for each one.

After approval, FlexFactor converts the application into a merchant account and sends the application.converted webhook. No API call is required from you for the conversion.

See the full list of application statuses

4. Create the merchant API credentials

When you receive application.approved, create the API credentials for the merchant. Call POST /v1/merchants/{mid}/api-keys with the application id as {mid}, and send name, description, and overwriteExistingKey: false in the body.

The response returns the appKey and appSecret of the merchant. Store both on the merchant record in your platform. The merchant uses them at /oauth2/token to authenticate every transaction call. Anyone holding the appKey and appSecret can authenticate as that merchant, so store them as you store any other secret.

Create the credentials via POST /v1/merchants/{mid}/api-keys

5. Map the merchant sites (only if you use site IDs)

If your integration sends siteId on /v1/evaluate, retrieve the sites of the merchant with GET /v1/merchants/{mid}. The sites array in the response lists every site under the merchant with its id, name, and descriptor. Store each site id on the merchant record and map it to the matching brand or descriptor on your platform.

If your integration does not send siteId, skip this step.

Retrieve the sites via GET /v1/merchants/{mid}

6. Activate the merchant

The merchant record on your platform now holds the mid, the appKey, the appSecret, and any site IDs. The merchant is ready to activate FlexFactor on your platform.

For the full credential set and how each value is used, see Integration workflows

---

Checking the application status by polling

Webhooks are the primary way to learn the status of an application. If your platform cannot receive webhooks, or you want to reconcile against the webhook events, call GET /v1/onboarding/application/{id}. The status field in the response carries the current status.

Poll no more than 1 time per hour for each application.

Retrieve an application via GET /v1/onboarding/application/{id}

---

Testing the workflow in Sandbox

In Sandbox, approval, decline, cancellation, and conversion are FlexFactor actions. Contact [email protected] to move a submitted Sandbox application to the outcome you want to test.

See Application status events for how each event is triggered in Sandbox