---
updatedAt: 2026-10-09T17:51:48.000Z
agentTools:
  projectIndex: https://docs.preczn.com/llms.txt
---

# Greensky - Merchant Onboarding

Configure a Greensky connection and board merchants for B2B2C consumer lending.

## Overview

Greensky is a B2B2C lending provider that lets merchants — typically home-improvement contractors — offer point-of-sale financing to their customers. Boarding a merchant onto Greensky through Preczn takes three steps:

1. **Configure the connection** — add your Greensky credentials once, at the platform level.
2. **Configure the boarding form** — enable the Greensky-specific fields, owners, contacts, and terms.
3. **Board the merchant** — submit the form, then track status as Greensky returns it by webhook.

For the connection basics, see [Greensky](https://docs.preczn.com/docs/greensky). For general boarding, see [Boarding Forms](https://docs.preczn.com/docs/boarding-forms) and [Multi-Connection Boarding Forms](https://docs.preczn.com/docs/multi-connection-boarding-forms).

## Configuring the Connection

Go to **Connections → Add Connection** and select **Greensky**. Five fields are available; only the Channel is required.

| Dashboard field   | Required | Description                                                                                                                                                                                                                                                                         |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Channel**       | ✅ Yes    | Your Greensky-assigned channel identifier. Greensky provides this value — contact Greensky support if you don't have it.                                                                                                                                                            |
| API-Key           | No       | Optional. When provided, Preczn uses it to validate a Greensky merchant ID that's added manually. Without it, manually added merchant IDs can't be validated.                                                                                                                       |
| Authorization Key | No       | Not used for Greensky. Leave blank.                                                                                                                                                                                                                                                 |
| Program           | No       | Optional program identifier.                                                                                                                                                                                                                                                        |
| Sponsor ID        | No       | Partner-issued identifier — each Greensky partner has its own assigned value. Greensky uses it for API-key creation, partner revenue-share, and reporting attribution. When set, it's sent at merchant onboarding as `business.sponsor`; when blank, it's omitted from the request. |

> :warning: **Use a Sponsor ID that Greensky has issued**
>
> Only submit a Sponsor ID that Greensky has actually issued to your partner. If you send a made-up or invalid value, Greensky does **not** reject the request — it silently substitutes its own default sponsor (observed as `3217`), so the value stored on Greensky's side won't match what you submitted. Greensky applies this same default when no sponsor is sent at all. Confirm the value with Greensky before boarding real merchants.

Click **Verify and Save** to store the connection.

## Configuring Boarding Forms

Greensky requires several fields that are **not enabled by default**. When you build a form that includes a Greensky connection, turn on the following.

### Greensky-specific fields

Enable both fields in the form's field configuration — they are hidden by default:

| Field                                                                      | Notes                                                                                                                                           |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Annual Finance Volume** (`annualFinanceVolume`)                          | The merchant's expected annual financed volume.                                                                                                 |
| **Greensky Primary Business Category** (`greenskyPrimaryBusinessCategory`) | A single selection from Greensky's fixed category list (e.g. HVAC, Roofing, Solar, Plumbing, Remodeling). Validated against the allowed values. |

### Ownership requirement

Whenever a boarding form includes Greensky — whether it's a single-connection form scoped to Greensky, or a multi-connection form where Greensky is one of the selected connections — the merchant must add business owners until at least **51%** of total ownership is represented. A progressive counting bar on the owners step tracks progress toward the threshold, and the form will not advance until 51% is reached.

### Greensky Terms & Conditions

Greensky adds a dedicated **Terms & Conditions** step to the form with two requirements:

* **The terms must be scrolled.** The acceptance checkbox stays disabled until the applicant scrolls to the bottom of the Greensky terms content.
* **The person completing the application must be identified.** If that person is one of the listed owners, they can **Quick Fill** their details in one click. Otherwise, first name, last name, title, email, and phone can be entered manually.

### Required contacts

Greensky requires **four contact roles** on the account:

| Role        | Label on form      |
| ----------- | ------------------ |
| `account`   | Primary Contact    |
| `credit`    | Statements Contact |
| `sales`     | Sales Contact      |
| `marketing` | Marketing Contact  |

For each role, the merchant picks an existing owner, picks an existing contact, or adds a new one. **The same person can fill more than one role** — four separate people are not required.

### Funding bank account

Greensky receives one bank account per merchant: the account marked **Primary Account**. When a merchant adds more than one account, Greensky gets only the primary one.

* The first account on the form starts as primary.
* Checking **Primary Account** on another account moves the flag to that account. Only one account can be primary at a time.
* If no account is marked primary, Preczn sends the first account.

Keep the **Primary Account** field turned on in the form's field configuration. If it's hidden, merchants can't choose, and Greensky always gets the first account entered.

> :information\_source: **Explain Primary Account on the form**
>
> The form doesn't tell merchants that the primary account is the one Greensky funds, so a merchant with two accounts can leave the first one checked without realizing it matters. Add **Helper Text** to the **Primary Account** field in the form's field configuration, for example: "Greensky sends funding to this account." The helper text applies to every form built from that template, including forms for other connections, so word it to fit all of them.

## Boarding a Merchant

> :warning: **Greensky merchants must be boarded through boarding forms**
>
> You can start boarding through the Preczn API, but some required data — including Greensky's anti-fraud check — can only be collected by the boarding form. There is no fully API-only boarding path for Greensky. See the [FAQ](#faq) for details.

Once the merchant submits the form, Preczn sends the enrollment to Greensky and begins tracking a status webhook for that merchant.

```mermaid
sequenceDiagram
    participant M as Merchant
    participant V as Vertical SaaS Platform
    participant P as Preczn
    participant G as Greensky

    M->>P: Submit boarding form
    P->>G: Send enrollment<br/>(+ status webhook callback URL)
    G-->>P: Success response — no merchant ID returned
    P->>P: Set status = Sent
    P-->>V: Merchant status webhook (Sent)
    Note over P: Merchant has no<br/>Greensky MID yet

    Note over P,G: A few minutes later
    G-->>P: First webhook<br/>(includes Greensky merchant ID)
    P->>P: Store merchant ID,<br/>set status = Underwriting
    P-->>V: Merchant status webhook (Underwriting)

    loop On each subsequent Greensky status change
        G-->>P: Status webhook
        P->>P: Map Greensky status<br/>to Preczn status
        P-->>V: Merchant status webhook
    end
```

> :warning: **No merchant ID is returned on submit**
>
> Greensky does **not** return a merchant ID when the form is submitted. Instead, it sends an initial webhook a few minutes later carrying the assigned merchant ID. Preczn records that ID and moves the merchant into **Underwriting**. Until that first webhook arrives, the merchant has no Greensky merchant ID.

## Merchant Status Mapping

Preczn tracks Greensky status updates by webhook and maps each Greensky status to a Preczn connection status:

| Greensky status | Preczn status | What it means                                                                                           |
| --------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| Underwriting    | Underwriting  | Application received; Greensky is reviewing. First status after boarding.                               |
| RFI             | RFI           | Greensky requested more information before it can proceed.                                              |
| Active          | Active        | Approved — the merchant can begin submitting loan applications and servicing loans for their customers. |
| Rejected        | Rejected      | Greensky declined the application.                                                                      |
| Suspended       | Disabled      | Merchant temporarily suspended by Greensky.                                                             |
| Terminated      | Closed        | Merchant relationship ended by Greensky.                                                                |

> :information\_source: **Unrecognized statuses**
>
> If a webhook arrives with no status, Preczn defaults the merchant to **Underwriting**. An unrecognized status leaves the current status unchanged.

## Testing in the Sandbox

The Greensky sandbox **only** auto-progresses a merchant to **Underwriting**. It will not advance to Active, RFI, Rejected, Suspended, or Terminated on its own.

> :information\_source: **Testing other statuses**
>
> To test status progression beyond Underwriting, coordinate directly with Greensky: share your Greensky merchant ID and their team can trigger status changes manually in the sandbox.

> :warning: **Test with a real Sponsor ID**
>
> If your connection sets a **Sponsor ID**, use a value Greensky has issued — even in testing. A placeholder value won't error out; Greensky quietly falls back to its default sponsor (observed as `3217`), and the value on their end won't match what you submitted.

## FAQ

<Accordion title="Can I onboard Greensky merchants entirely through the API?">

No. You can start boarding through the Preczn API, but Greensky requires an anti-fraud check (the **Blackbox**) that is generated in the applicant's browser when they accept the Greensky terms. That only happens in the boarding form, so every Greensky merchant must complete a boarding form to finish onboarding.

</Accordion>

<Accordion title="What is the Blackbox field?">

The **Blackbox** is an anti-fraud code Greensky requires with every application. When the applicant accepts the Greensky terms on the boarding form, Greensky's fraud-prevention technology automatically generates it from the device being used, and Greensky checks it to decide whether the application can proceed.

You don't enter or manage this value — the boarding form captures it for you. It's also why onboarding has to go through the boarding form rather than the API alone.

</Accordion>

<Accordion title="I set a Sponsor ID but Greensky shows a different value — why?">

Greensky only honors Sponsor IDs it has issued. If the submitted value isn't valid, Greensky falls back to its default sponsor (observed as `3217`) — the same default it uses when no sponsor is sent at all — rather than returning an error. In one test, a made-up value of `2886` came through on Greensky's side as `3217`.

Double-check the Sponsor ID with Greensky, then re-save the Greensky connection so the correct value is sent on the next enrollment.

</Accordion>

<Accordion title="Why is my merchant stuck in Sent?">

Right after a successful submission, the merchant sits in **Sent** until Greensky's first webhook arrives and moves it to Underwriting. If it stays in **Sent**, that first webhook was never received — and because no Greensky merchant ID exists yet, Preczn has no way to look the merchant up and confirm it was created.

Reach out to Greensky directly to resolve it, with:

* the **merchant name**, and
* the **date and time the merchant was boarded** — the `onboardingSubmissionDate` property on the merchant record.

</Accordion>