Skip to main content

​
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": "test@example.com",
      "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.