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:

• Payments endpoints use a terminal API key and require X-Api-Key: <apiKey>

• Most other endpoints use OAuth and require Authorization: Bearer <access_token>

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 (non Payments APIs and legacy Payments):

• 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

Payments auth header:

• X-Api-Key: <apiKey>

OAuth auth header:

• 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 and paymentUrls
GET	/Payments/tracking/{trackingId}	Get payment status by trackingId

Onboarding (OAuth)

These endpoints use OAuth authentication.

Method	Path	Summary
POST	/merchant-onboarding/application	Create application and send signer link
GET	/merchant-onboarding/application/{applicationId}	Get application status
PUT	/merchant-onboarding/{partnerId}/webhook	Register onboarding webhook
POST	/merchant-onboarding/{applicationId}/feedback	Submit manual review decision

Locations (OAuth)

These endpoints use OAuth authentication.

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
DELETE	/Locations/{id}	Delete a location that has no terminals
GET	/Locations/{id}/terminals	List terminals for a location

Terminals and webhooks (OAuth)

These endpoints use OAuth authentication.

Method	Path	Summary
GET	/Terminals/{id}	Get a single terminal
POST	/Locations/{id}/terminals	Create a terminal under a location
PUT	/Terminals/{id}/webhook	Set or update the terminal webhook
GET	/Terminals/{id}/webhook	Retrieve the current terminal webhook configuration
DELETE	/Terminals/{id}/webhook	Remove the terminal webhook configuration
DELETE	/Terminals/{id}	Delete a terminal

Terminal webhook body:

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

Reporting payment history (OAuth)

These endpoints use OAuth authentication.

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

Common query parameters for payment history:

Name	Type	Notes
from	string (ISO 8601)	Inclusive start timestamp in UTC
to	string (ISO 8601)	Exclusive end timestamp in UTC
status	string	Payment status filter
tenderType	string	Tender filter
locationId	string	Merchant history only, filter to a location
page	integer	One based page number
pageSize	integer	Items per page

Typical response envelope:

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

Partners and merchants (OAuth)

These endpoints use OAuth authentication.

Method	Path	Summary
GET	/Partners/{id}	Get a single partner
POST	/Partners/{parentId}/partners	Create a child partner under a parent partner
GET	/Merchants/{id}	Get a single merchant
POST	/Merchants	Create a merchant

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

Payments notes:

• 401 usually means X-Api-Key is missing or invalid

• 403 usually means apiKey is valid but not permitted for the merchantId or terminalId context, or environment mismatch

OAuth notes:

• 401 usually means access token missing or expired

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

Next steps

• If you are starting with Payments, go to Create Payment and Payment Statuses.

• If you are starting with onboarding, go to Quick Start and Onboarding.

• If you are building reconciliation, go to Reporting and Settlement.