Get Status

Use this endpoint to retrieve the current state of a merchant onboarding application. The response includes:

  • Overall onboarding status for the merchant

  • Agreement application status and events

  • Merchant onboarding details, including fee information

  • Compliance application status

  • Banking and settlement application status

  • Crypto services and digital wallet services status, when applicable

This applies to both:

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

  • Minimal applications created with POST /merchant-onboarding/application-short

When to use Get Status

Use Get Status when you want to:

  • Show real time onboarding status in your portal for a specific merchant

  • Confirm whether the agreement has been completed, declined, or is still in progress

  • Inspect the business, ownership, banking, and fee information that Bead has on file

  • See the status of downstream services such as compliance, banking, and crypto services

  • Drive internal workflows based on states like approved, boarded, or customer activated

Endpoint

Path parameter

  • applicationId The onboarding application identifier returned when you created the application.

Authentication and headers

All onboarding endpoints require a valid OAuth access token.

If the token is missing or invalid, the API returns an unauthorized response.

Response overview

The response is a single object that groups onboarding status across several areas.

Top level fields

  • id Unique identifier for the onboarding application.

  • merchantName Merchant name associated with this application.

  • partnerName Name of the partner that submitted the application.

  • partnerId Identifier of the partner in Bead.

  • status Overall onboarding status for the merchant, for example Boarded.

  • onboardedMerchantId Identifier of the merchant record created after successful onboarding.

  • agreementApplication Details of the DocuSign or agreement application.

  • complianceApplication Details of the compliance or KYB decision for this merchant.

  • bankingApplication Details of the banking or settlement account status.

  • cryptoServicesApplication Details of the crypto services status.

  • digitalWalletServicesApplication Details of digital wallet service status, if present.

Agreement application

The agreementApplication object contains:

  • envelopeId Identifier of the signing envelope.

  • templateId Identifier of the template used for the agreement.

  • partnerExternalId External identifier used by the partner for this application.

  • status Status of the agreement envelope, for example completed.

  • signer Object with signer information:

    • email

    • name

    • position

    • declinedReason (if the signer declined)

  • events List of envelope events, each with:

    • id

    • envelopeId

    • eventType such as envelope-sent, envelope-delivered, envelope-completed

    • eventDate

    • status

  • completedDate When the agreement was completed, if applicable.

  • merchantOnboardingApplicationDetails Nested object with all onboarding details for the merchant.

  • fundsTransferAgreementDetails Information about the funds transfer agreement, when applicable.

  • detailsSnapshots Optional list of historical snapshots of the details object.

Merchant onboarding application details

merchantOnboardingApplicationDetails includes:

  • Business identity and registration

    • registeredName

    • dbaName

    • proofOfBusinessType

    • proofOfBusinessDocument

    • registrationDate

    • legalEntityType

    • otherLegalEntity

    • federalTaxIdType

    • federalTaxId

    • naicsCode

    • merchantCategoryCode

    • additionalMerchantCategoryCode

    • businessDescription

    • isSeasonal

    • operationalMonths

  • Revenue and volume profile

    • grossAnnualRevenue

    • highestMonthlyVolume

    • averageTicketSize

    • maxTicketSize

  • Addresses

    • registeredLegalAddress

    • proofOfLegalAddressType

    • proofOfLegalAddressDocument

    • sameAsRegisteredAddress

    • businessMailingAddress

  • Main point of contact

    • mainPointOfContact with firstName, lastName, email, and phoneNumber

  • Ownership and stakeholders

    • hasNoOwners

    • stakeholders list, where each stakeholder has:

      • firstName, lastName, and optional middleName and suffix

      • dateOfBirth

      • citizenship

      • ownershipPercentage

      • ownershipType

      • idType and idNumber

      • countryOfIssuance

      • taxIdType and taxIdNumber

      • proofOfIdentityType and proofOfIdentityDocument

      • proofOfAddressType and proofOfAddressDocument

      • address with full address fields

      • email

      • phoneNumber

      • jobTitle

  • Banking and settlement details

    • bankName

    • routingNumber

    • accountNumber

    • accountType

    • bankDepositMethod

    • bankAddress

    • proofOfBankAccountType

    • proofOfBankAccountDocument

  • Signed documents and consent

    • signedDocumentUrl for the main application

    • merchantApplicationSigner with:

      • name

      • position

      • consent fields such as termsConsent, privacyConsent, businessCommunicationsConsent, phoneConsent, partnerConsent, bridgeConsent

      • signedDate

  • Fee information

    • feeInformation block:

      • achSettlementFixedFee

        • sellRate

        • isBilledByPartner

      • wireSettlementFixedFee

        • sellRate

        • isBilledByPartner

      • settlementReturnFixedFee

        • sellRate

        • isBilledByPartner

      • cryptoFees

        • transactionRate with sellRate and isBilledByPartner

        • perItemFee with sellRate and isBilledByPartner

      • digitalWalletsFees list, where each entry has:

        • tenderType such as klarna

        • paymentLocationType such as inStore or online

        • transactionRate, perItemFee, refundFee, and chargebackFee, each with sellRate and isBilledByPartner

Funds transfer agreement details

fundsTransferAgreementDetails includes:

  • signedDocumentUrl for the funds transfer agreement

  • fundsTransferAgreementSigner with:

    • name

    • position

    • signedDate

Compliance application

complianceApplication contains:

  • businessId

  • status such as approved

  • stakeholderVerifications list, with:

    • stakeholderId

    • flowId

    • feedbackInfo list for any compliance feedback

  • requestedAt timestamp for the compliance request

Banking application

bankingApplication contains:

  • status such as boarded

  • clientAccountId

  • errorMessage if any error occurred

  • exception when there is an exception description

Crypto services application

cryptoServicesApplication contains:

  • businessId

  • status such as customerActivated

  • errorMessage

  • exception

Digital wallet services application

digitalWalletServicesApplication may contain status and identifiers for digital wallet services when present. It may be null if digital wallet services are not yet configured or not part of the program.

Example request

Example response

PreviousSubmit ApplicationNextResend Application

Last updated