# Test the Full Onboarding Workflow in Sandbox Use this page to validate the full merchant onboarding workflow in Sandbox, from application creation through signer completion, status tracking, webhook validation, and final boarded merchant confirmation. This guide uses the immediate-submit path: ```json { "submitImmediately": true } ``` When `submitImmediately` is `true`, Bead creates the application and immediately starts the signer flow. This is the easiest path for a first full workflow test because you do not need to manage Draft status or attachments. This guide applies to both: ```http POST /merchant-onboarding/applications POST /merchant-onboarding/applications-short ``` For most teams, the fastest Sandbox test path is the short application flow, because it lets the hosted onboarding experience collect most of the remaining merchant information. This page intentionally focuses on the workflow. For exact request schemas and full payload examples, use Submit Application, Fee Configuration for Onboarding Applications, and Sample Payload. ### What this test should prove A successful end-to-end Sandbox test should confirm that your integration can: * create an onboarding application * trigger the signer flow using `submitImmediately: true` * send the signer into the hosted onboarding experience * complete all required signer steps * track application progress by polling status, receiving webhooks, or both * handle the Sandbox-specific manual advance step * confirm that the merchant reaches a boarded state ### Before you begin Before running this test: * use a valid, deliverable email address that you can access * use a unique signer email address for each test application * use unique merchant identifiers, such as `partnerExternalId` or `partnerMid` * set `cryptoEnvironment` to `sandbox` * set `submitImmediately` to `true` * store the returned `applicationId` and `envelopeId` * decide whether you will track progress through polling, webhooks, or both * if you plan to test webhooks, configure your Sandbox webhook endpoint before submitting the application For true end-to-end testing, let Bead deliver the signer email through the standard flow. This validates the same email-driven path a merchant signer will use. ### Recommended Sandbox test path A practical end-to-end Sandbox test usually looks like this: 1. Create an application with `submitImmediately: true`. 2. Wait for the signer email. 3. Open the hosted onboarding package and complete the signer flow. 4. After submit, watch for a second signature page for the Funds Transfer Agreement and complete that step as well. 5. Track the application using `GET /merchant-onboarding/applications/{applicationId}`. 6. If webhooks are enabled, confirm your endpoint receives lifecycle events. 7. After the signer submits, contact your Bead team with the merchant name so the Sandbox application can be manually advanced. 8. Continue checking status until the application is boarded and an `onboardedMerchantId` is returned. ### Draft and attachment note This page uses `submitImmediately: true` because it is the simplest workflow test. If your test requires attachments, use the Draft flow instead: ```json { "submitImmediately": false } ``` Then upload attachments while the application is in Draft status and submit the Draft application for signature. ```http POST /merchant-onboarding/applications/{applicationId}/submit ``` Use Application Attachments for the full Draft and attachment workflow. ### Step 1: Create the application You can test with either onboarding entry point. Use the full application endpoint when you already have most merchant data and want to prefill the application as much as possible. ```http POST /merchant-onboarding/applications ``` Use the short application endpoint when you want the hosted onboarding flow to collect most of the remaining information from the signer. ```http POST /merchant-onboarding/applications-short ``` For a basic Sandbox workflow test, the short flow is usually the quickest path. #### Example short application request ```json { "merchantName": "Northwind Coffee Roasters", "partnerId": "{partnerId}", "partnerMid": "northwind-sandbox-001", "signerFirstName": "Morgan", "signerLastName": "Reed", "signerEmail": "morgan.reed+test001@example.com", "isSettlementOnly": false, "isCommissionMerchant": false, "feeInformation": { "achSettlementFixedFee": { "sellRate": 0.79, "isBilledByPartner": false }, "settlementReturnFixedFee": { "sellRate": 25, "isBilledByPartner": false }, "monthlyMaintenanceFee": { "sellRate": 19.99, "isBilledByPartner": false } }, "cryptoEnvironment": "sandbox", "submitImmediately": true } ``` #### Example response ```json { "applicationId": "app-123exampleid", "envelopeId": "env-1111-2222-3333-4444", "status": "sent" } ``` After a successful create call, store these fields immediately: * `applicationId` * `envelopeId` * `status` You will use `applicationId` to check status, correlate webhooks, troubleshoot the application, and support the Sandbox manual advance step. ### Step 2: Complete the signer flow Once the application is created with `submitImmediately: true`, Bead sends the onboarding package to the signer using the signer details from your request. For the short application flow, signer details are provided with: * `signerFirstName` * `signerLastName` * `signerEmail` For the full application flow, the application signer is identified in `merchantData.stakeholders`. Use an email address you can access so you can complete the flow yourself during testing. The signer should: 1. open the email invitation 2. review and complete the hosted onboarding package 3. sign all required documents and consents 4. click submit to finish the application flow #### Important Sandbox note After you click submit for the application, a second signature page for the Funds Transfer Agreement may appear. Do not stop after the first submit action. To complete the Sandbox workflow successfully, make sure the signer also completes the Funds Transfer Agreement signature step if it appears. ### Step 3: Track status Use the application status endpoint as your main source of truth for the current application state. ```http GET /merchant-onboarding/applications/{applicationId} ``` Start with these response fields first: * `id` * `merchantName` * `status` * `onboardedMerchantId` A common pattern is: * use `status` to understand where the application is in the process * use `merchantName` for support and reconciliation * use `onboardedMerchantId` once the merchant is successfully boarded For this Sandbox workflow, keep checking status as the signer completes the application and after the manual Sandbox advance step is performed. ### Step 4: Test webhooks Webhooks are optional for a basic test, but recommended for a complete integration test. To test webhooks end to end: 1. Configure your onboarding webhook for the correct partner. 2. Use a simple HTTPS endpoint that logs requests and returns `2xx`. 3. Submit a test application with `submitImmediately: true`. 4. Capture the real webhook events generated by the application lifecycle. 5. Use `applicationId` from the webhook to fetch full application state when needed. Treat onboarding webhooks as event notifications, not as the full application record. Your webhook consumer should: * use the webhook event `id` as the event-level idempotency key * use `applicationId` as the application correlation key * return `2xx` quickly * call Get Status when full detail is needed Depending on your flow, you may observe lifecycle moments such as signing complete, submitted, approved, declined, or needs more information. ### Step 5: Complete the Sandbox-only manual advance step In Sandbox, the application does not automatically move through the full internal workflow after signer submission. After the signer completes the onboarding package and submits it, contact your Bead team and provide the merchant name used on the application. Your Bead team can then coordinate the manual Sandbox advance needed to continue the end-to-end workflow. This is a Sandbox testing requirement and should not be treated as the expected Production workflow. ### Step 6: Confirm the boarded result After the manual Sandbox advance is completed, continue checking the application status. Your end goal is to confirm that: * the application reaches its final boarded state * `onboardedMerchantId` is returned * your system can store and use that identifier for downstream workflows At that point, you have validated the full application and onboarding workflow in Sandbox. ### Expected results A successful Sandbox workflow test should prove that: * your system can create an onboarding application * `submitImmediately: true` starts the signer flow without requiring a separate submit command * the signer receives and completes the hosted onboarding package * the Funds Transfer Agreement step is not missed * your system can correlate `applicationId` across polling and webhook events * your team understands the Sandbox-only manual advance step * your integration can recognize when the merchant is boarded ### Troubleshooting #### The signer did not receive the email Check that: * the email address is valid and deliverable * the email address is unique for this application * the mailbox is one your team can access * your organization does not block tagged or plus-addressed emails * `submitImmediately` was set to `true` * the application create request returned a successful response #### The signer submitted the application, but the workflow is not complete Check that: * the signer completed every page in the hosted flow * the Funds Transfer Agreement signature page was completed if it appeared * you are checking status using the correct `applicationId` * the Sandbox manual advance step has been requested from your Bead team #### I received a webhook but need more detail Use `applicationId` from the webhook and call: ```http GET /merchant-onboarding/applications/{applicationId} ``` #### The application never reaches boarded in Sandbox This is the expected point to involve your Bead team. Provide the merchant name used on the application so the Sandbox workflow can be manually advanced. #### I need to test attachments This page uses the immediate-submit path and does not require attachments. To test attachments, create the application with: ```json { "submitImmediately": false } ``` Then follow the Application Attachments page before submitting the Draft application for signature. ### Best practices * Use the short application flow for fast Sandbox testing unless your production integration depends on full prefill. * Set `submitImmediately` to `true` for the easiest end-to-end workflow test. * Use `submitImmediately: false` only when you need to test Draft status and attachments. * Save `applicationId` and `envelopeId` immediately after application creation. * Use a real mailbox your team controls. * Use a unique email address for every test application. * Use a unique merchant name or partner reference for every test. * Test both polling and webhooks where possible. * Make webhook processing idempotent. * Treat the Sandbox manual advance step as a test-environment exception, not a production dependency. ### Related pages * [Submit Application](/onboarding/submit-application.md) * [Fee Configuration for Onboarding Applications](/onboarding/fee-configuration-for-onboarding-applications.md) * [Application Attachments](/onboarding/application-attachments.md) * [Get Status](/onboarding/get-status.md) * [Webhooks for Application Events](/onboarding/webhooks-for-application-events.md) * [Sample Payload](/onboarding/sample-payload.md) * [Test data: email address requirements](/faqs-and-troubleshooting/environment-and-testing/test-data-email-address-requirements.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.