> 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
}
```

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 — see [Test data: email address requirements](/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; 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`
* 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.

#### 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: email address requirements](/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`.
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**

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](/onboarding/sample-payload.md) for complete, copy-ready request bodies, and [Fee Configuration for Onboarding Applications](/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
}
```

**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 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: email address requirements](/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 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 — 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](/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-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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.