> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fractalpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Onboarding

> SAML authentication and hosted merchant onboarding flow

# Fractal SAML Authentication & Onboarding

Steps for integrating Fractal SAML authentication and launching the hosted onboarding flow.

All endpoints require Basic Auth on every request:

* **Username** = Client ID
* **Password** = Secret Key

***

## Step 1: Create a Session

Call the create-session endpoint to authenticate and receive a session token. Optionally pass `?is_publickey=true` to also retrieve your client's shared public key.

```bash theme={null}
curl -X GET 'https://{baseURL}/api/v1/auth/create-session' \
  -u "{client_id}:{secret_key}"
```

To also fetch your public key:

```bash theme={null}
curl -X GET 'https://{baseURL}/api/v1/auth/create-session?is_publickey=true' \
  -u "{client_id}:{secret_key}"
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "SAML authentication successful",
  "data": {
    "sessionToken": "<session_token>",
    "public_key": "<your_public_key>"
  }
}
```

Store the `sessionToken` — it is required in Step 2.

***

## Step 2: Initiate the Hosted Onboarding Form

Pass the `session_token` from Step 1 as a URL parameter. The body fields are optional — include any merchant data you have available.

```bash theme={null}
curl -X POST 'https://{baseURL}/api/v1/auth/onboarding/{session_token}' \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "{internal_company_id}",
    "BusinessInfo": {
      "business_name": "Test Pay LLC",
      "business_email": "test@example.com",
      "business_phone": "5551234567",
      "business_address": "123 Main Street",
      "business_city": "Austin",
      "business_state": "TX",
      "business_zip": "78701",
      "business_country": "US"
    }
  }'
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "Merchant onboarding successfully",
  "data": {
    "merchant_id": "<merchant_id>",
    "company_id": "<your_company_id>",
    "onboarding_link": "<one_time_onboarding_url>"
  }
}
```

The `onboarding_link` is a one-time URL to send to the merchant to complete the form. Store the `merchant_id` — it is required for future API calls.

***

## Step 3: Merchant Completes the Onboarding Form

Send the `onboarding_link` from Step 2 to the merchant. When they open the link, they will be presented with a hosted onboarding form to complete their business and banking details.

The link is **one-time use** — it expires once submitted or after a set period. Once the merchant submits the form, their application will move into a pending review state.

***

## Step 4: Check Merchant Status

Once the merchant submits the onboarding form, use this endpoint to poll their approval status.

The `merchant_key` here is the merchant's **Fractal API key** — found in their Fractal dashboard. This is distinct from the `merchant_id` (the `m_` prefixed GUID) and the `public_key` returned by the merchant list endpoint.

```bash theme={null}
curl -X POST 'https://{baseURL}/api/v1/auth/get-onboarding-status' \
  -u "{client_id}:{secret_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "{fractal_api_key}"
  }'
```

**Response:**

```json theme={null}
{
  "result": true,
  "message": "merchant status found",
  "data": {
    "merchantStatus": "pending"
  }
}
```

`merchantStatus` will be either `"pending"` or `"completed"`. You can also use webhooks to track `merchant_status` for real-time updates instead of polling.