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.

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

To also fetch your public key:

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

Response:

{
  "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.

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": "[e-mail]",
      "business_phone": "5551234567",
      "business_address": "123 Main Street",
      "business_city": "Austin",
      "business_state": "TX",
      "business_zip": "78701",
      "business_country": "US"
    }
  }'

Response:

{
  "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.

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:

{
  "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.