Cancel Application

Use this endpoint to cancel the signing process for an existing onboarding application by revoking the signer's active token.

This endpoint applies to both:

• Full applications created with POST /merchant-onboarding/applications

• Short applications created with POST /merchant-onboarding/applications-short

Cancel revokes the signing token so the signer can no longer complete the current session. It does not delete the application record.

{% hint style="warning" %} Cancel is only available while an application is in viewed or signing status. Once an application has been submitted — including submitted, changesRequested, resubmitted, and every status beyond — the cancel window is closed. Calling this endpoint on an application outside viewed/signing returns an error; it is not a judgment call to make case by case. {% endhint %}

Cancel vs. Resend

These two commands are related but serve different purposes.

Action	Endpoint	Use when
Cancel the signing process	POST /merchant-onboarding/{applicationId}/cancel	You need to stop the active signing session and prevent the current signer from completing the package.
Resend to the same signer	PUT /merchant-onboarding/applications/{applicationId}	The application should continue and the same signer needs another opportunity to complete the package.

If you want to send the application back to the same signer without stopping the process, use Resend Application instead.

When to use Cancel Application

Use Cancel Application when you need to:

• stop the current signer from completing the package

• prevent a signing session that was sent to the wrong recipient from being completed

• halt onboarding for a merchant that has withdrawn from the process

• stop the signing flow before creating a corrected application

• revoke access for a signer whose details were entered incorrectly

Typical examples include:

• the application was sent to the wrong email address

• the signer is no longer the correct point of contact

• the merchant has asked to stop onboarding

• your operations team needs to halt the process before it progresses further

All of the above only apply before submission — while the application is still in viewed or signing status. If the application has already been submitted, Cancel Application is no longer the right tool; see When not to use Cancel Application below.

When not to use Cancel Application

Do not use this endpoint once an application has been submitted. This includes:

• the application is in draft status and has not yet been sent to a signer — there is no signing token to revoke

• the application has been submitted and is in submitted, changesRequested, or resubmitted status — the submission window has closed

• the application has already been signed and is in review or boarding (signed, reviewing, reviewed, boarding)

• the application is already in a terminal state (boarded, withdrawn, rejected)

• you want to send the package back to the same signer — use Resend Application instead

For Draft applications that need to be discarded, coordinate with your Bead team.

Endpoint

POST /merchant-onboarding/{applicationId}/cancel

Path parameter

Parameter	Description
applicationId	The onboarding application identifier returned when the application was created.

Authentication and headers

Onboarding requests use API key authentication.

X-Api-Key: {apiKey}
Accept: application/json

No request body is required.

What this endpoint does

Cancel Application revokes the active signing token for the specified application. After the token is revoked, the current signer can no longer access or complete the hosted onboarding and signing experience.

The application record is preserved. Retrieve the application status after cancelling to confirm the resulting state before deciding on next steps.

Typical request pattern

A common cancel pattern is:

1. Retrieve the current application status with GET /merchant-onboarding/applications/{applicationId}.

2. Confirm the application is in viewed or signing status.

3. Call POST /merchant-onboarding/{applicationId}/cancel.

4. Retrieve the updated status to confirm the application state.

5. Decide on next steps — whether to create a new application, coordinate with your Bead team, or take no further action.

Example request

POST /merchant-onboarding/{applicationId}/cancel
X-Api-Key: {apiKey}
Accept: application/json

No request body is required.

Example response

A successful cancel returns HTTP 200 with no response body.

Status handling

Cancel is only valid while the application is in viewed or signing status. Retrieve the current application status before cancelling — do not attempt this call against any other status.

GET /merchant-onboarding/applications/{applicationId}

Status	Cancellable?	Cancel guidance
draft	No	The application has not been sent to a signer yet. No signing token exists to revoke.
submitted	No	The application has been submitted. The cancel window has closed — this is a submission-stage status, not a pre-submission one.
signing	Yes	The signer has not yet completed the package. Cancel is appropriate to stop the signing session.
viewed	Yes	The signer has opened but not completed the package. Cancel is appropriate to stop the signer from proceeding.
changesRequested	No	The application has been submitted and returned for changes. This is a post-submission status — cancel is not applicable.
resubmitted	No	The application has been resubmitted after changes. This is a post-submission status — cancel is not applicable.
signed	No	The application has already been signed. Cancelling is not applicable.
reviewing	No	The application is under review. Coordinate with your Bead team if the process needs to stop.
boarding	No	The application is in downstream boarding. Coordinate with your Bead team if the process needs to stop.
boarded	No	Onboarding is complete — a terminal state.
withdrawn	No	Already in a terminal state.
rejected	No	Already in a terminal state.

After calling cancel, retrieve the application again to confirm the status before taking further action.

Cancel and creating a new application

Cancelling an application stops the current signing process but does not automatically create a replacement application.

If you need to restart onboarding with a different signer or corrected merchant data, create a new application after confirming the cancel succeeded.

Reuse the same partnerId and merchant reference when the underlying merchant relationship continues.

Error handling

Scenario	Expected result
Unknown applicationId	404 Not Found.
Application is not in viewed or signing status (already submitted, already terminal, or still Draft)	409 Conflict — cancel is not valid for the application's current status.
Malformed request	400 Bad Request.
API key is missing or invalid	401 Unauthorized.
API key does not have access to the application	403 Forbidden.

If you need to stop an application that has already returned 409 Conflict on cancel, do not retry the call — the status has moved past the point where cancel applies. Coordinate with your Bead team on next steps instead.

Best practices

• Retrieve the current application status before cancelling — cancel is only valid for viewed or signing status.

• Do not call cancel on Draft applications — there is no signing token to revoke.

• Do not call cancel on an application that has already been submitted (submitted, changesRequested, resubmitted, or beyond) — it will return 409 Conflict.

• If you want an application to remain cancellable, request cancellation before the signer submits it. Once submitted, that window is closed and cannot be reopened from the API.

• After cancelling, retrieve the application status to confirm the resulting state before deciding on next steps.

• If the intent is to restart onboarding with the same signer, use Resend Application instead of cancel.

• If the intent is to restart onboarding with a different signer or corrected data, create a new application after confirming the cancel succeeded.

• Coordinate with your Bead team if you are unsure whether a cancellation is appropriate for a given status.

Related pages

• Submit Application

• Get Status

• Resend Application

• Webhooks for Application Events

• Sample Payload

• Reference Guide