> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md).

# 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,
  "skipPartnerReview": true
}
```

When `submitImmediately` is `true`, Bead creates the application and submits it in the same call. The application moves to `preparing` while Bead gathers business information, then to `prepared`. When `skipPartnerReview` is `true`, Bead then sends the application to the signer automatically. This is the easiest path for a first full workflow test because you do not need to manage Draft status, attachments, or a separate send call.

If you leave `skipPartnerReview` out, Bead applies the default for the environment. If the application waits in `prepared`, call `POST /merchant-onboarding/{applicationId}/send-to-applicant` to send it. See [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md).

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
* submit the application with `submitImmediately: true` and get it to the signer, either automatically or with the send call
* 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. See [Test data: uniqueness requirements](https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/test-data-uniqueness-requirements.md) for recommended patterns
* use a distinct registered business name for each test application. The sponsor bank enforces business name uniqueness even in Sandbox, and reusing the same business name across applications can cause rejections
* use a varied signer name for each test application. Reusing the same signer name across many applications can trigger duplicate-identity checks at the boarding layer
* use unique merchant identifiers, such as `partnerExternalId` or `partnerMid`
* set `cryptoEnvironment` to `sandbox`
* set `submitImmediately` to `true`
* set `skipPartnerReview` explicitly, to `true` for the automatic send or `false` if you want to test the send call
* store the returned `applicationId`
* 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.

#### Test data uniqueness requirements

The sponsor bank applies uniqueness checks to several fields at the boarding layer. These checks apply even in Sandbox. Reusing the same values across test applications is the most common source of unexpected rejections during integration testing.

**Signer email**

Use a unique email address for every test application. The recommended approach is plus-addressing with a timestamp:

```
qa+20260127143015@yourcompany.com
```

See [Test data: uniqueness requirements](https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/test-data-uniqueness-requirements.md) for full patterns, including handling for parallel test runs.

**Business name**

Use a distinct registered business name for every test application. A simple approach is to append a numeric suffix or short identifier to a base name:

```
Northwind Coffee Roasters 001
Northwind Coffee Roasters 002
```

Avoid reusing the exact same business name across applications, even across different test runs.

**Signer name**

Use a varied signer name for every test application. A lightweight approach is to combine a fixed first name with a sequenced or randomized last name:

```
Morgan Reed-001
Morgan Reed-002
```

Or use a short random suffix:

```
Morgan Reed-8f3a
Morgan Reed-2c91
```

The signer name does not need to be a real person's name, but it should be unique per application to avoid duplicate-identity checks at the boarding layer.

#### Recommended Sandbox test path

A practical end-to-end Sandbox test usually looks like this:

1. Create an application with `submitImmediately: true` and `skipPartnerReview: true`.
2. Check status. The application moves to `preparing`, then `prepared`, and is then sent to the signer.
3. If the application stays in `prepared`, call `POST /merchant-onboarding/{applicationId}/send-to-applicant`. The status moves to `signing`.
4. Wait for the signer email.
5. Open the hosted onboarding package and complete the signer flow.
6. After submit, watch for a second signature page for the Funds Transfer Agreement and complete that step as well.
7. Track the application using `GET /merchant-onboarding/applications/{applicationId}`.
8. If webhooks are enabled, confirm your endpoint receives lifecycle events.
9. After the signer submits, contact your Bead team with the merchant name so the Sandbox application can be manually advanced.
10. 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.

```http
POST /merchant-onboarding/applications/{applicationId}/submit
```

The application then moves to `preparing` and `prepared`. You can also add attachments while it is in `prepared`. Use Application Attachments for the full 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**

The example below uses a timestamped email, a sequenced business name, and a suffixed signer name, all following the uniqueness patterns described above.

> **This is an abbreviated workflow example, not a complete payload.** The `feeInformation` block below contains only three fees for illustration. A production application requires a full fee configuration aligned to the merchant's commercial agreement. Use [Sample Payload](https://developers.bead.xyz/onboarding/sample-payload.md) for complete, copy-ready request bodies, and [Fee Configuration for Onboarding Applications](https://developers.bead.xyz/onboarding/fee-configuration-for-onboarding-applications.md) for fee structure guidance.

```json
{
  "merchantName": "Northwind Coffee Roasters 001",
  "partnerId": "{partnerId}",
  "partnerMid": "northwind-sandbox-001",
  "signerFirstName": "Morgan",
  "signerLastName": "Reed-001",
  "signerEmail": "qa+20260127143015@yourcompany.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,
  "skipPartnerReview": true
}
```

**Example response**

```json
{
  "applicationId": "app-123exampleid"
}
```

After a successful create call, store `applicationId` immediately. The response does not include a status. Read it with `GET /merchant-onboarding/applications/{applicationId}`.

You will use `applicationId` to check status, correlate webhooks, troubleshoot the application, and support the Sandbox manual advance step.

#### Step 2: Get the application to the signer

Once the application is created with `submitImmediately: true`, it moves to `preparing` and then `prepared`.

* With `skipPartnerReview: true`, Bead sends the onboarding package to the signer automatically when the application reaches `prepared`. The status moves to `signing`.
* Without it, the application waits in `prepared`. Call `POST /merchant-onboarding/{applicationId}/send-to-applicant` to send it. The status moves to `signing`.

Bead sends the 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`.

If the signer needs the email again while the application is in `signing`, call `POST /merchant-onboarding/{applicationId}/resend-to-applicant`. See [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md).

Use an email address you can access so you can complete the flow yourself during testing.

#### Step 3: Complete the signer flow

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 4: 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

A typical Sandbox status path looks like this:

```
preparing → prepared → signing → signed → reviewing → reviewed → boarding → boarded
```

For this Sandbox workflow, keep checking status as the signer completes the application and after the manual Sandbox advance step is performed.

#### Step 5: 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 6: 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 7: 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` submits the application without a separate submit command
* the application reaches the signer, automatically with `skipPartnerReview: true` or with the send call
* 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 application status. If it is `preparing`, wait. If it is `prepared`, the application has not been sent yet, so call `POST /merchant-onboarding/{applicationId}/send-to-applicant`, or set `skipPartnerReview` to `true` on the next test
* if the status is `signing`, use `POST /merchant-onboarding/{applicationId}/resend-to-applicant` to email the invitation again
* 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 application was rejected due to duplicate data**

The sponsor bank enforces uniqueness on several fields even in Sandbox. If your application is rejected and you are running repeated tests, check that:

* the signer email is unique for this application. See [Test data: uniqueness requirements](https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/test-data-uniqueness-requirements.md)
* the business name is distinct from previous test applications
* the signer name has not been reused across many applications

**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 you submit the Draft application.

#### 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.
* Set `skipPartnerReview` explicitly so your test does not depend on the environment default.
* Use `submitImmediately: false` only when you need to test Draft status and attachments.
* Save `applicationId` immediately after application creation.
* Use a real mailbox your team controls.
* Use a unique email address for every test application. Generate it with a timestamp tag.
* Use a distinct registered business name for every test application. Append a sequence number or short identifier.
* Use a varied signer name for every test application. Append a sequence number or short random suffix.
* 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](https://developers.bead.xyz/onboarding/submit-application.md)
* [Send to Applicant](https://developers.bead.xyz/onboarding/send-to-applicant.md)
* [Resend Application](https://developers.bead.xyz/onboarding/resend-application.md)
* [Fee Configuration for Onboarding Applications](https://developers.bead.xyz/onboarding/fee-configuration-for-onboarding-applications.md)
* [Application Attachments](https://developers.bead.xyz/onboarding/application-attachments.md)
* [Get Status](https://developers.bead.xyz/onboarding/get-status.md)
* [Webhooks for Application Events](https://developers.bead.xyz/onboarding/partner-webhooks.md)
* [Sample Payload](https://developers.bead.xyz/onboarding/sample-payload.md)
* [Test data: uniqueness requirements](https://developers.bead.xyz/faqs-and-troubleshooting/environment-and-testing/test-data-uniqueness-requirements.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/onboarding/test-the-full-onboarding-workflow-in-sandbox.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
