Merchant Status

Important Notice The Merchant Status API is currently undergoing upgrades and enhancements. Before beginning integration, please contact our developer support team at [e-mail] for the latest guidance and timelines.

The Merchant Status API allows integrators to verify the onboarding status of merchants during the KYB (Know Your Business) process. By periodically checking this status, integrators can ensure merchants complete onboarding efficiently.

Overview

Check the current KYB onboarding progress and status details for a specific merchant using the merchant ID obtained during onboarding.

Authentication

Merchant Status API requires username/password-based OAuth2 authentication. See Authentication for details.

Checking Merchant Status

To retrieve the status of a merchant, issue the following request:

Request Example

GET https://api.test.devs.beadpay.io/merchants/{merchantId}/status
Authorization: Bearer {access_token}

Replace {merchantId} with the actual merchant ID obtained during merchant onboarding.

Response Example

{
  "merchantId": "merchant-001",
  "status": "under_review",
  "missingFields": [
    "taxIdDocument",
    "ownerSignature"
  ],
  "nextStepUrl": "https://boarding.beadpay.io/onboarding/merchant-001",
  "lastUpdated": "2025-03-04T14:20:00Z"
}

Response Fields

Field	Description
merchantId	Unique identifier of the merchant.
status	Current onboarding status (pending, under_review, completed, rejected).
missingFields	Array of fields/documents still required from the merchant.
nextStepUrl	URL where the merchant can submit remaining required details or documents.
lastUpdated	Timestamp when the status was last updated.

Merchant Status Definitions

Status	Meaning	Recommended Action
pending	Merchant started onboarding, but has not completed all steps.	Provide merchant the nextStepUrl to finalize onboarding.
under_review	Merchant has submitted required information and is under review.	Wait for status update; no immediate action required.
completed	Merchant onboarding is complete and ready to accept transactions.	Proceed to terminal creation and setup.
rejected	Merchant onboarding has failed due to compliance or validation issues.	Review rejection reasons with compliance team, re-initiate onboarding as needed.

Next Steps

• If merchant onboarding is complete (completed), proceed to Terminal Management.

• If onboarding is incomplete (pending or under_review), ensure merchant finalizes their KYB process.

For onboarding support, contact [e-mail].