Table View (All APIs)

This page is a quick lookup for common endpoints and paths across Bead APIs. Use the correct environment base URL for the API you are calling, then append the paths listed below.

Authentication depends on the API family, but current Bead integrations generally use an API key sent in the X-Api-Key header.

For current integrations:

• Payments APIs use X-Api-Key: <apiKey>

• Onboarding APIs use X-Api-Key: <apiKey>

• Management, reporting, and settlement APIs generally use X-Api-Key: <apiKey> unless Bead has provided different endpoint-specific guidance

• Some legacy or specialized endpoint families may still use OAuth 2.0 Bearer tokens

See Authentication for details and examples.

Base URLs and token URL

API base URLs:

• Sandbox: https://api.test.devs.beadpay.io

• Production: https://api.devs.beadpay.io

OAuth token URL format for legacy or OAuth-based APIs:

• POST https://identity.beadpay.io/realms/{realm}/protocol/openid-connect/token

Realm examples:

• Sandbox: nonprod

• Production: prod

Standard headers

For JSON APIs:

• Accept: application/json

For requests with a JSON body:

• Content-Type: application/json

Primary Bead API authentication header:

• X-Api-Key: <apiKey>

OAuth authentication header, when specifically required:

• Authorization: Bearer <access_token>

Payments (API key)

These endpoints use API key authentication.

Method	Path	Summary
POST	/Payments/crypto	Create a hosted payment page and receive trackingId, paymentPageId, and paymentUrls
GET	/Payments/tracking/{trackingId}	Get payment status by trackingId

Onboarding (API key)

These endpoints use API key authentication.

Method	Path	Summary
POST	/merchant-onboarding/applications	Initiate merchant onboarding with full merchant data
POST	/merchant-onboarding/applications-short	Initiate merchant onboarding with minimal information
GET	/merchant-onboarding/applications	List merchant onboarding applications with filters
GET	/merchant-onboarding/applications/{applicationId}	Retrieve a merchant onboarding application
PUT	/merchant-onboarding/applications/{applicationId}	Resubmit a merchant onboarding application
POST	/merchant-onboarding/applications/{applicationId}/submit	Submit a Draft application for signature
GET	/merchant-onboarding/applications/{applicationId}/history	Retrieve application history and audit events
POST	/merchant-onboarding/applications/{applicationId}/attachments	Upload an attachment to a Draft application
GET	/merchant-onboarding/applications/{applicationId}/attachments	List attachments for an application
GET	/merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}	Download a single attachment
DELETE	/merchant-onboarding/applications/{applicationId}/attachments/{attachmentId}	Delete an attachment from a Draft application
POST	/merchant-onboarding/{applicationId}/cancel	Cancel the signing process by revoking the signing token
POST	/merchant-onboarding/{partnerId}/webhook	Register an onboarding webhook configuration
PUT	/merchant-onboarding/{partnerId}/webhook	Register or update an onboarding webhook configuration
DELETE	/merchant-onboarding/{partnerId}/webhook	Remove an onboarding webhook configuration

Common query parameters for onboarding application lists:

Name	Type	Notes
PartnerId	string	Filter by partner
From	date-time	Filter by updated date from this timestamp
To	date-time	Filter by updated date to this timestamp
Statuses	array	Filter by application status
Search	string	Free text search, such as merchant name, signer email, or partner external ID
Page	integer	Zero-based page number
PageSize	integer	Items per page, maximum 100
SortBy	string	Field to sort by
SortDirection	string	Sort direction

Locations (API key)

These endpoints use API key authentication unless Bead has provided different endpoint-specific guidance.

Method	Path	Summary
POST	/Merchants/{id}/locations	Create a new location under a merchant
GET	/Merchants/{id}/locations	List locations for a merchant
GET	/Locations/{id}	Get a single location
PUT	/Locations/{id}	Update a location
PATCH	/Locations/{id}/enabled	Enable or disable a location
DELETE	/Locations/{id}	Delete a location that has no terminals
GET	/Locations/{id}/terminals	List terminals for a location

Terminals and webhooks (API key)

These endpoints use API key authentication unless Bead has provided different endpoint-specific guidance.

Method	Path	Summary
POST	/Terminals	Create a terminal
GET	/Terminals/{id}	Get a single terminal
PUT	/Terminals/{id}	Update a terminal
DELETE	/Terminals/{id}	Delete a terminal
GET	/Merchants/{id}/terminals	List terminals for a merchant
GET	/Locations/{id}/terminals	List terminals for a location
POST	/Terminals/{id}/clone	Clone a terminal
GET	/Terminals/{id}/api-keys	Retrieve a terminal API key
POST	/Terminals/{id}/api-keys	Reset a terminal API key
PUT	/Terminals/{id}/webhook	Set or update the terminal webhook
DELETE	/Terminals/{id}/webhook	Remove the terminal webhook configuration

Terminal webhook body:

Field	Type	Required	Notes
url	string	Yes	HTTPS endpoint that receives payment events

Reporting payment history (API key)

These endpoints use API key authentication unless Bead has provided different endpoint-specific guidance.

Method	Path	Summary
GET	/Partners/{id}/payments	Partner payment history with pagination and filters
GET	/Merchants/{id}/payments	Merchant payment history with pagination and filters
GET	/Terminals/{id}/payments	Terminal payment history with pagination and filters

Common query parameters for payment history:

Name	Type	Notes
From	date-time	Filter by payment date from this timestamp
To	date-time	Filter by payment date to this timestamp
TrackingId	string	Filter by tracking ID
PageId	string	Filter by payment page ID
ReqCurrencyId	integer	Filter by requested currency ID
PayCurrencyId	integer	Filter by payment currency ID
CustomerId	string	Filter by customer ID
DescriptionSearch	string	Search payment description
PaymentCode	string	Filter by payment code
Reference	string	Filter by payment reference
StatusCode	array	Filter by one or more payment statuses
TenderType	array	Filter by one or more tender types
LocationName	string	Filter by location name
TerminalName	string	Filter by terminal name
Page	integer	Zero-based page number
PageSize	integer	Items per page, maximum 100
SortBy	string	Field to sort by
SortDirection	string	Sort direction

Typical response envelope:

Field	Type	Notes
data	array	Page of results
total	integer	Total matching records
page	integer	Current page

Settlement and reconciliation (API key)

These endpoints use API key authentication unless Bead has provided different endpoint-specific guidance.

Use these APIs when you need settlement records, grouped payment batches, funded deposits, merchant settlement batches, or payment-level settlement detail.

Settlement records

Method	Path	Summary
GET	/Settlements	List settlement records with filters
GET	/Settlements/{id}	Get a single settlement record
GET	/Settlements/{id}/batches	List batches associated with a settlement
GET	/Settlements/{id}/deposits	List deposits associated with a settlement

Common query parameters for settlement records:

Name	Type	Notes
From	date	Filter by settlement date from this date
To	date	Filter by settlement date to this date
Status	string	Filter by settlement status
Type	string	Filter by settlement type, such as crypto, wallet apps, or fiat
MerchantIds	array	Filter by one or more merchant IDs
Page	integer	Zero-based page number
PageSize	integer	Items per page, maximum 100
SortBy	string	Field to sort by
SortDirection	string	Sort direction

Batches

Method	Path	Summary
GET	/Batches	List payment batches with filters
GET	/Batches/{id}	Get a single batch
GET	/Batches/merchants/{merchantId}	List batches for a merchant
GET	/Settlements/{id}/batches	List batches associated with a settlement

Common query parameters for batches:

Name	Type	Notes
From	date	Filter by batch date from this date
To	date	Filter by batch date to this date
Status	string	Filter by batch status
Type	string	Filter by batch type
MerchantIds	array	Filter by one or more merchant IDs
SettlementIds	array	Filter by one or more settlement IDs
Page	integer	Zero-based page number
PageSize	integer	Items per page, maximum 100
SortBy	string	Field to sort by
SortDirection	string	Sort direction

Deposits

Method	Path	Summary
GET	/Deposits	List deposit records with filters
GET	/Deposits/{id}	Get a single deposit record
GET	/Settlements/{id}/deposits	List deposits associated with a settlement

Common query parameters for deposits:

Name	Type	Notes
From	date	Filter by deposit date from this date
To	date	Filter by deposit date to this date
Status	string	Filter by deposit status
Method	string	Filter by deposit method, such as ACH or wire
MerchantIds	array	Filter by one or more merchant IDs
SettlementIds	array	Filter by one or more settlement IDs
Page	integer	Zero-based page number
PageSize	integer	Items per page, maximum 100
SortBy	string	Field to sort by
SortDirection	string	Sort direction

Merchant settlements

Method	Path	Summary
GET	/MerchantSettlements/merchant/{merchantId}	List merchant settlements for a merchant
GET	/MerchantSettlements/{merchantSettlementId}	Get a single merchant settlement
GET	/MerchantSettlements/payment-ids/merchant-settlement	List payment IDs associated with a merchant settlement
GET	/MerchantSettlements/settlement-info/{merchantSettlementId}	Get payment-level detail for a merchant settlement
GET	/MerchantSettlements/merchant/between	Get payment and merchant payment settlement records for a merchant and time window
GET	/MerchantSettlements/merchant-payment-settlements/merchant	List merchant payment settlement records for a merchant

Payment settlements

Method	Path	Summary
GET	/Merchants/{merchantId}/payment-settlements	List payment settlement records for a merchant

Common query parameters for merchant and payment settlements:

Name	Type	Notes
merchantId	string	Merchant identifier
merchantSettlementId	string	Merchant settlement identifier
status	string	Filter by settlement status where supported
startTime	date-time	Start of the settlement window where supported
endTime	date-time	End of the settlement window where supported
page	integer	Zero-based page number
pageSize	integer	Items per page
sortByDirection	string	Sort direction where supported

Partners and merchants (API key)

These endpoints use API key authentication unless Bead has provided different endpoint-specific guidance.

Method	Path	Summary
GET	/Partners/all	List partners with pagination and filters
GET	/Partners/{id}	Get a single partner
POST	/Partners/{parentId}/partners	Create a child partner under a parent partner
GET	/Partners/{id}/api-keys	List API keys for a partner
POST	/Partners/{id}/api-keys	Create a partner API key
GET	/Merchants/all	List merchants with pagination and filters
GET	/Merchants/{id}	Get a single merchant
POST	/Merchants	Create a merchant
PUT	/Merchants/{id}	Update a merchant
DELETE	/Merchants/{id}	Delete a merchant
GET	/Partners/{id}/merchants	List merchants for a partner when supported
GET	/Partners/{id}/representing-merchant	Get the merchant represented by a partner when supported

Error interpretation

Status	What it usually means
400	Invalid input or validation failed
401	Missing or invalid credential
403	Authenticated but not permitted for the resource or relationship
404	Not found or not visible in the current context
409	Duplicate or state conflict
422	Business rule failure
500	Unexpected server error

API key notes:

• 401 usually means X-Api-Key is missing, invalid, sent using the wrong header name, or tied to the wrong environment.

• 403 usually means the API key is valid but not permitted for the merchant, partner, terminal, or resource context.

• Do not send masked API keys or deprecated request body API key fields.

OAuth notes:

• OAuth may still apply to legacy or endpoint-specific use cases.

• 401 usually means the access token is missing or expired.

• 403 usually means the caller does not have permission for the target resource.