Onboarding Sessions
An onboarding session is Frame's secure, ready-made hosted flow for collecting everything needed to verify and activate an account. Create a session for an existing account, redirect the account holder to the session URL, and Frame guides them through KYC, identity verification, document collection, and compliance checks based on the capabilities you've requested.
frameOS adapts every onboarding flow to exactly what's required— no more, no less. Whether you're onboarding a new merchant onto your platform or verifying an end user before they transact, frameOS scopes the experience to the capabilities you've requested and handles everything from there: KYC, identity verification, document collection, and compliance checks, all through a hosted UI you can redirect to in minutes.
Onboarding sessions expire after 30 minutes for security reasons. If a session expires before the account holder completes onboarding, create a new session and redirect them again.
Before you begin
Before creating an onboarding session, you must create an account with at minimum the account type and any capabilities you want to enable. You can also prefill profile information to speed up the onboarding flow.
Capabilities
Capabilities define what an account can do on Frame. When you request a capability, frameOS knows exactly what information to collect during onboarding: accepting card payments, verifying identity, receiving payouts, and more. Request only the capabilities you need; the onboarding session automatically collects the required information for each one.
| Capability | Description |
|---|---|
| kyc | Configurable identity verification flows |
| phone_verification | Verify via SMS or voice |
| creator_shield | Fraud protection for creators |
| card_send | Accept card payments |
| card_receive | Receive payouts to a card |
| bank_account_send | Accept bank account payments |
| bank_account_receive | Receive payouts to a bank account |
| geo_compliance | Location-based rules |
| address_verification | Validate physical addresses |
| card_verification | Verify cards without charging |
| bank_account_verification | Verify bank account ownership |
| kyc_prefill | Pre-fill KYC with known data |
| age_verification | Confirm age for restrictions |
Create an account
Create an account with the account type, any capabilities you want to request, and any known profile information. Prefill as much as you know — this reduces the number of fields the account holder needs to complete and improves completion rates.
Generate the onboarding session only after you have finished creating and prefilling the account. You cannot update the account after the session URL has been shared with the account holder.
curl --request POST \
--url https://api.framepayments.com/v1/accounts \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"type": "individual",
"capabilities": ["kyc", "card_send"],
"profile": {
"individual": {
"email": "user@example.com",
"name": {
"first_name": "Jane",
"last_name": "Doe"
},
"phone": {
"number": "3107484186",
"country_code": "1"
}
}
}
}'
How it works
1. Create an API key in the Frame Dashboard and use it to authenticate your requests.
# Use your API key in the Authorization header for all requests
curl --header 'Authorization: Bearer YOUR_API_KEY' ...
2. Create an account with the account type, capabilities you want to enable, and any known profile information.
curl --request POST \
--url https://api.framepayments.com/v1/accounts \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"type": "individual",
"capabilities": ["kyc", "card_send"],
"profile": {
"individual": {
"email": "user@example.com",
"name": {
"first_name": "Jane",
"last_name": "Doe"
},
"phone": {
"number": "3107484186",
"country_code": "1"
}
}
}
}'
3. Create an onboarding session by sending a POST request to /v1/onboarding_sessions with the account ID and an optional return URL.
curl --request POST \
--url https://api.framepayments.com/v1/onboarding_sessions \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"return_url": "https://yourapp.com/onboarding/complete"
}'
4. Redirect the account holder to the session URL returned in the response. The session URL is single-use and expires after 30 minutes. Never share session URLs via email, SMS, or other external channels — always redirect the authenticated account holder within your application.
{
"id": "os_7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"object": "onboarding_session",
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"client_secret": "onb_sess_englLvt99jPZDYsAOvKqSQ91ei2vvsfe",
"return_url": "https://yourapp.com/onboarding/complete",
"url": "https://onboarding.framepayments.com/sessions/os_7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"expires_at": 1721012405,
"livemode": false
}
// Redirect the user to the session URL
window.location.href = response.url;
5. Handle the return — Frame redirects the account holder to your return_url after they complete or exit the flow. A redirect does not guarantee all requirements have been met. Retrieve the account and inspect its requirements to confirm onboarding is complete. If there are outstanding requirements, create a new onboarding session to collect the remaining information.
curl --request GET \
--url https://api.framepayments.com/v1/accounts/99c6b0da-2570-42a7-838a-5eaa318b07df \
--header 'Authorization: Bearer YOUR_API_KEY'
Use cases
Merchant onboarding
When bringing a new merchant onto your platform, frameOS collects the business and identity information required to process payments and stay compliant. Depending on the capabilities you request, the session may include KYC, business verification, document collection, and bank account setup, all handled by Frame with no custom form-building required.
This is particularly useful for platforms in regulated industries like gaming, cannabis, or adult content, where compliance requirements are high and onboarding friction can be a barrier.
Marketplace and platform end users
For marketplaces and platforms that move money to or from end users, frameOS handles identity verification, payment method setup, and any compliance requirements before a user transacts. This is useful for creator platforms paying out earnings, peer-to-peer marketplaces, or any platform where end users need to be verified before they can send or receive funds.
Incremental verification
You don't have to collect everything upfront. Start with minimal capabilities and request additional ones as users unlock new features on your platform. Each time new capabilities are added to an account, create a fresh onboarding session to collect only the additional information required.
API Reference
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.
Parameters
The ID of the account to onboard. The account must already exist before creating a session.
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.
curl --request POST \
--url https://api.framepayments.com/v1/onboarding_sessions \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df"
}'
{
"id": "os_7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"object": "onboarding_session",
"account_id": "99c6b0da-2570-42a7-838a-5eaa318b07df",
"client_secret": "onb_sess_englLvt99jPZDYsAOvKqSQ91ei2vvsfe",
"return_url": "https://yourapp.com/onboarding/complete",
"steps": ["kyc"],
"url": "https://onboarding.framepayments.com/sessions/os_7f3a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"expires_at": 1721012405,
"livemode": false
}