Test data: uniqueness requirements

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:

{
  "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:

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: uniqueness requirements for recommended patterns

• use a distinct registered business name for each test application — the system 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 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 system 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:

[e-mail]

See Test data: uniqueness requirements 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 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 simple approach is to append a numeric suffix to a base last name:

Morgan Reed 01
Morgan Reed 02

The signer name does not need to be a real person's name, but it should be unique per application to avoid duplicate 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:

{
  "submitImmediately": false
}

Then upload attachments while the application is in Draft status and submit the Draft application for signature.

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.

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.

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 for complete, copy-ready request bodies, and Fee Configuration for Onboarding Applications for fee structure guidance.

{
  "merchantName": "Northwind Coffee Roasters 001",
  "partnerId": "{partnerId}",
  "partnerMid": "northwind-sandbox-001",
  "signerFirstName": "Morgan",
  "signerLastName": "Reed 01",
  "signerEmail": "[e-mail]",
  "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

{
  "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.

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 system 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

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

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:

{
  "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.

• 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

• Fee Configuration for Onboarding Applications

• Application Attachments

• Get Status

• Webhooks for Application Events

• Sample Payload

• Test data: uniqueness requirements