# 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 applies to both: * full applications created with `POST /merchant-onboarding/applications` * minimal applications created with `POST /merchant-onboarding/applications-short` For most teams, the fastest Sandbox test path is the minimal 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 payload examples, use [Submit Application](https://developers.bead.xyz/onboarding/submit-application) and [Sample Payload](https://developers.bead.xyz/onboarding/sample-payload). ### What this test should prove A successful end-to-end Sandbox test should confirm that your integration can: * create an onboarding application * send the signer into the hosted onboarding flow * 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 application * 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, it is best to let Bead deliver the signer email through the standard flow. If a `signingUrl` is returned, you can also use it for directed testing, but email is still the primary path to validate. ### Recommended Sandbox test path A practical end-to-end Sandbox test usually looks like this: 1. Create an application. 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 the 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. ### Step 1: Create the application You can test with either onboarding entry point. Use `POST /merchant-onboarding/applications` when you already have most merchant data and want to prefill the application as much as possible. Use `POST /merchant-onboarding/applications-short` when you want the hosted onboarding flow to collect most of the remaining information from the signer. For a basic Sandbox workflow test, the minimal flow is usually the quickest path. After a successful create call, store these fields immediately: * `applicationId` * `envelopeId` * `status` * `signingUrl` if present ### Step 2: Complete the signer flow Once the application is created, Bead sends the onboarding package to the signer using the email in `signerInfo`. Use an email address you can access so you can complete the flow yourself during testing. The signer should: * open the email invitation * review and complete the hosted onboarding package * sign all required documents and consents * 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: `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. 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 * 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 #### 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: `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. ### Best practices * use the minimal flow for fast Sandbox testing unless your production integration depends on full prefill * save `applicationId` and `envelopeId` immediately after application creation * use a real mailbox your team controls * use a unique email address for every test application * 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](https://developers.bead.xyz/onboarding/submit-application) * [Get Status](https://developers.bead.xyz/onboarding/get-status) * [Webhooks for Application Events](https://developers.bead.xyz/onboarding/webhooks-for-application-events) * [Sample Payload](https://developers.bead.xyz/onboarding/sample-payload) * [Test data: email address requirements](https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/test-data-email-address-requirements)