Onboarding Sessions

Bootstraps the frame-onboarding embedded Web Component from a client_secret. Pass the onb_sess_* credential as a Bearer token. Returns session metadata, ordered step list, and full account context in one call.

Bootstrap an embedded onboarding session

Bootstraps the frame-onboarding embedded Web Component from a client_secret. Pass the onb_sess_* credential as a Bearer token. Returns session metadata, ordered step list, and full account context in one call.

Parameters

No parameters.

Returns

Bootstrap payload returned

GET/v1/onboarding_sessions/bootstrap
curl --request GET \
  --url https://api.framepayments.com/v1/onboarding_sessions/bootstrap \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "9bdf2327-de2f-414d-9b31-483ebe71732a",
  "account_id": "ad4cdb34-1939-4214-a72e-3e5a9a9773a5",
  "client_secret": "onb_sess_z3cm8vQLBJ4bnLiJZPrgG1OGSZrbwEFY",
  "return_url": null,
  "object": "onboarding_session",
  "expires_at": 1781117680,
  "livemode": false,
  "steps": [
    "phone_verification",
    "id_verification"
  ],
  "account": {
    "id": "ad4cdb34-1939-4214-a72e-3e5a9a9773a5",
    "status": "pending",
    "external_id": null,
    "metadata": {},
    "payout_payment_method_id": null,
    "type": "individual",
    "object": "account",
    "terms_of_service": null,
    "profile": {
      "individual": {
        "email": "dacia@becker.test",
        "ssn_last_four": null,
        "name": {
          "first_name": "Angel",
          "middle_name": null,
          "last_name": "Friesen",
          "suffix": null
        },
        "phone": {
          "number": null,
          "country_code": null
        },
        "address": null,
        "birthdate": null
      }
    },
    "capabilities": [],
    "created": 1781115879,
    "updated": 1781115879,
    "livemode": false
  }
}

Get onboarding session by account ID

Retrieves the onboarding session for a specific account using the account_id query parameter. Returns the session object if one exists, including the URL the account holder can be redirected to.

Each account has only one active onboarding session at a time. Returns 404 if no session exists for the account or if the account is not found. A redirect to the session URL does not guarantee all requirements have been met — retrieve the account and inspect its requirements to confirm onboarding is complete.

Query parameters
account_idstringrequired

The ID of the account to retrieve the onboarding session for. The account must already exist and belong to the authenticated merchant.

Returns

Returns the onboarding session object for the given account

GET/v1/onboarding_sessions
curl --request GET \
  --url https://api.framepayments.com/v1/onboarding_sessions \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "33cc6340-93f8-4f65-aadf-fb41b1985042",
  "account_id": "d4ba44aa-1c2e-407c-8bd7-4480d99a5443",
  "client_secret": "onb_sess_pf1zNEzZ5pDpteuiR7LC0AsyZtHJurOY",
  "return_url": null,
  "steps": [
    "id_verification"
  ],
  "object": "onboarding_session",
  "expires_at": 1781117680,
  "livemode": false,
  "url": "https://framepayments.test/onboarding?client_secret=onb_sess_pf1zNEzZ5pDpteuiR7LC0AsyZtHJurOY"
}

Create an onboarding session

Creates an onboarding session for an existing account. Returns a session object containing a URL you can redirect the account holder to in order to complete onboarding.

The session URL is single-use and expires after 30 minutes for security reasons. If a session expires before the account holder completes onboarding, create a new session and redirect them again. Never share session URLs via email, SMS, or other external channels — always redirect the authenticated account holder within your application.

Body parameters
account_idstringrequired

The ID of the account to onboard. The account must already exist before creating a session.

stepsarrayoptional

Optional list of step keys to include. If omitted, all pending steps on the account are used. Valid keys: id_verification, geo_compliance, payment_method

return_urlstringoptional

The URL Frame redirects the account holder to after they complete the onboarding flow. A redirect to this URL does not indicate that all requirements have been fulfilled — always retrieve the account to verify its status after redirect.

Returns

Returns an onboarding session object containing a url to redirect the account holder to

POST/v1/onboarding_sessions
curl --request POST \
  --url https://api.framepayments.com/v1/onboarding_sessions \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "account_id": null
}'
RESPONSE
{
  "id": "c6f2fd35-0ee2-4d43-87e9-0e3745dc66ee",
  "account_id": "8667a649-6613-4255-82be-c9491ac7d2d4",
  "client_secret": "onb_sess_HUB9cBkGuxMrX1dlpNMbjNseSM3xWp6O",
  "return_url": "https://example.com/callback",
  "steps": [
    "id_verification"
  ],
  "object": "onboarding_session",
  "expires_at": 1781117680,
  "livemode": false,
  "url": "https://framepayments.test/onboarding?client_secret=onb_sess_HUB9cBkGuxMrX1dlpNMbjNseSM3xWp6O"
}