Vendor API reference
Manage the authenticated owner’s business workspace. These operations use a member session associated with the vendor owner, not a terminal integration key.
From application to live operation
- Sign in through the supported BEXO vendor flow. Read /vendor/me to resolve the current workspace.
- Submit business details and complete the compliance workflow. Keep identity documents private.
- Create plans, review their amounts and durations, and wait for required approval before publishing.
- Create or retrieve a hosted checkout URL for an active plan.
- Register readers, review verification events and reconcile supported reports.
Approval states are distinct from test keys
| State | Meaning for integrations |
|---|---|
| sandbox_only | The application has not completed production review. It does not mean a live integration credential exists. |
| entity_verified / control_verified / risk_reviewed | Intermediate review states. Continue the workspace’s requested steps. |
| production_active | Required by documented live publishing/checkout gates; other configuration can still be required. |
| suspended | Operations may be restricted. Do not bypass the state with cached results. |
Updating important business identity details can trigger another review and make previously accepted details or links require attention. Use the workspace for business-profile changes; this reference does not provide a generic PATCH contract for every legal or bank field.
Plan and reporting conventions
Amounts ending in Paise are integer minor units: 150000 means INR 1,500. Use integer arithmetic and currency from the server. Plan creation supports one_time or monthly; actual recurring payment availability depends on the configured provider journey. A plan record alone does not prove a subscription mandate is active.
For checkout-compatible plans use a positive duration of 1–366 days. Pending purchases keep a price/name/duration snapshot; editing a current plan is not an instruction to rewrite an existing purchase. Report data is operational application data and should be reconciled with payment-provider and banking records.
Compliance upload workflow
Upload one PDF, PNG or JPEG using multipart field file, up to 8 MiB. Accepted path kinds are business_registration, tax_id, pan_card, gst_certificate and authorized_signatory. Then submit documents for review. Review status and missing-document feedback are authoritative; submission does not activate the vendor.
curl --fail-with-body "$BEXO_API_BASE/vendor/documents/business_registration" \
-H "Authorization: Bearer $BEXO_OWNER_SESSION" \
-F "file=@/secure/path/business-registration.pdf"Keep source files in a controlled location. Never send identity documents to a public asset bucket, documentation tool or analytics system.
Reports and exports
The recent-subscriptions and recent-verifications endpoints cap at 100 records and do not expose cursor pagination. Device API logs use page and limit. Reports support JSON or CSV; query support is listed for each endpoint. CSV exports can include personal/business data and require the same access controls as the workspace.
curl --fail-with-body "$BEXO_API_BASE/vendor/reports/subscribers?range=last_30_days&format=csv" \
-H "Authorization: Bearer $BEXO_OWNER_SESSION" \
--output subscribers.csvConfirm date boundaries with the workspace; reporting-day boundaries follow server-side interpretation. Do not assume these reports use UTC days.
Endpoint reference
Paths below include the API prefix. The OpenAPI server URL already includes /api.
/api/vendor/meRead your vendor workspace
Private account data. Keep it out of public pages, analytics events and application logs. Resolves the tenant associated with the authenticated owner. Returns 404 when no application is associated.
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/me" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
tenant | Vendor | See the downloadable schema for nested fields. |
storefrontUrl | string · nullable | Public storefront URL. |
/api/vendor/applicationsSubmit a business application
Creates or updates the authenticated owner’s application. PAN, GST declaration, support email and registered business details are validated. This is not live activation. Complete compliance steps in the vendor portal.
Request template
Set the API base to include /api. Replace path placeholders and prepare request.json from the body fields below before running.
curl --fail-with-body -X POST "$BEXO_API_BASE/vendor/applications" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN" \
-H "Content-Type: application/json" \
--data @request.jsonRequest body
| Field | Type | Details |
|---|---|---|
legalNameRequired | string | Registered legal name. |
displayNameRequired | string | Customer-facing name. |
contactEmailRequired | string | Business email. |
supportEmailRequired | string | Customer support email. |
contactPhone | string | Business phone; optional. |
businessCategory | string | Business category.fitness · gym · coworking · education · retail · entertainment · healthcare · laundry · other |
registeredAddressRequired | string | Business address. |
authorizedRepresentativeRequired | string | Authorized representative name. |
serviceDescription | string | Description of the service. |
panRequired | string | Valid Indian PAN. Supply actual business details privately. |
gstExempt | boolean | Whether the business declares a GST exemption. |
gstin | string | Required when gstExempt is false. |
pincode | string | Six-digit PIN code, when supplied. |
city | string | City. |
state | string | State. |
websiteUrl | string | Website URL. |
refundPolicyUrl | string | Public refund policy URL. |
termsAccepted | boolean | Acceptance of the application terms. |
Response fields
| Field | Type | Details |
|---|---|---|
tenant | Vendor | See the downloadable schema for nested fields. |
/api/vendor/documentsList compliance documents
Lists document metadata for the current owner. Treat filenames and metadata as confidential. This reference does not expose reviewer download or biometric session APIs.
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/documents" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
documents | array | See the downloadable schema for nested fields. |
/api/vendor/documents/{kind}Upload a compliance document
Send multipart/form-data with one file field. Maximum 8 MiB; PDF, PNG or JPEG. Allowed kinds: business_registration, tax_id, pan_card, gst_certificate, authorized_signatory. Uploads are accepted only while the application is in a reviewable state.
Parameters
| Name | Location | Requirement |
|---|---|---|
kind | path | Required. Resource identifier. |
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X POST "$BEXO_API_BASE/vendor/documents/{kind}" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN" \
-F "file=@/path/to/business-document.pdf"Request body
| Field | Type | Details |
|---|---|---|
fileRequired | string | One PDF, PNG or JPEG up to 8 MiB. |
Response fields
| Field | Type | Details |
|---|---|---|
document | object | See the downloadable schema for nested fields. |
/api/vendor/documents/submitSubmit documents for review
Checks required business registration, signatory, PAN/tax and GST documentation. GST evidence depends on the exemption declaration. DOCUMENTS_REQUIRED identifies an incomplete submission. Uploading does not approve the vendor.
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X POST "$BEXO_API_BASE/vendor/documents/submit" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
success | boolean | Submission accepted. |
message | string | Acknowledgment. |
/api/vendor/plansList plans and checkout URLs
Lists plans for the authenticated vendor, including unpublished plans. A checkout URL in the response does not bypass vendor approval or the active-plan check.
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/plans" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
plans | array | See the downloadable schema for nested fields. |
/api/vendor/plansCreate a vendor plan
Creates a plan. one_time requires durationDays; monthly defaults to 30 if omitted. Use durations of 1–366 for checkout compatibility. The plan is active only for a production_active vendor. Provider provisioning is configuration-dependent.
Request template
Set the API base to include /api. Replace path placeholders and prepare request.json from the body fields below before running.
curl --fail-with-body -X POST "$BEXO_API_BASE/vendor/plans" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN" \
-H "Content-Type: application/json" \
--data @request.jsonRequest body
| Field | Type | Details |
|---|---|---|
nameRequired | string | Plan name. |
durationDays | integer | Positive duration. Checkout snapshots support 1–366 days. |
pricePaiseRequired | integer | Amount in integer INR paise; 100 paise equals INR 1. |
billingPeriod | string | Plan billing mode. A monthly value does not by itself prove recurring payments are enabled.one_time · monthly |
gstPercent | number | Tax percentage recorded for the plan; default in this reference is 18. |
taxInclusive | boolean | Whether the stated amount includes tax; defaults true. |
externalRef | string | Optional reference in your ERP. |
Example request body
{
"name": "Monthly access",
"durationDays": 30,
"pricePaise": 150000,
"billingPeriod": "one_time",
"taxInclusive": true
}Response fields
| Field | Type | Details |
|---|---|---|
plan | Plan | See the downloadable schema for nested fields. |
/api/vendor/plans/{planId}Update or pause a plan
Updates a plan belonging to the owner. Set isActive=false to pause new sales. Publishing again requires approval. Existing purchase snapshots are separate from changes to the current plan.
Parameters
| Name | Location | Requirement |
|---|---|---|
planId | path | Required. Resource identifier. |
Request template
Set the API base to include /api. Replace path placeholders and prepare request.json from the body fields below before running.
curl --fail-with-body -X PATCH "$BEXO_API_BASE/vendor/plans/{planId}" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN" \
-H "Content-Type: application/json" \
--data @request.jsonRequest body
| Field | Type | Details |
|---|---|---|
name | string | Replacement name. |
durationDays | integer | Positive duration. |
pricePaise | integer | Amount in integer INR paise; 100 paise equals INR 1. |
gstPercent | number | See the downloadable schema for nested fields. |
taxInclusive | boolean | Whether tax is included. |
isActive | boolean | Publishing requires production_active vendor approval. |
Example request body
{
"isActive": false
}Response fields
| Field | Type | Details |
|---|---|---|
plan | Plan | See the downloadable schema for nested fields. |
/api/vendor/owner/subscriptionsList recent memberships
Returns up to 100 recent memberships for the vendor, newest first. No pagination is documented for this endpoint. Use reporting endpoints for supported exports.
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/owner/subscriptions" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
subscriptions | array | See the downloadable schema for nested fields. |
/api/vendor/owner/verificationsList recent verification events
Returns up to 100 recent tenant-scoped events. Each event includes id, membershipId, decision, reason and createdAt.
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/owner/verifications" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
events | array | See the downloadable schema for nested fields. |
/api/vendor/terminalsList registered readers
Returns readers for the owner’s tenant. A reader serial identifies the device; it cannot authenticate a request alone.
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/terminals" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
terminals | array | See the downloadable schema for nested fields. |
/api/vendor/terminalsRegister a reader
Registers an owner-scoped terminal. Suspended vendors cannot register devices. Serial numbers must be unique; omit serialNumber to receive a generated identifier.
Request template
Set the API base to include /api. Replace path placeholders and prepare request.json from the body fields below before running.
curl --fail-with-body -X POST "$BEXO_API_BASE/vendor/terminals" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN" \
-H "Content-Type: application/json" \
--data @request.jsonRequest body
| Field | Type | Details |
|---|---|---|
label | string | Device label, e.g. Reception. |
serialNumber | string | Optional custom serial. If omitted, the service generates one. |
hardwareModel | string | Hardware model. |
firmwareVersion | string | Firmware version. |
Example request body
{
"label": "Reception"
}Response fields
| Field | Type | Details |
|---|---|---|
success | boolean | Created. |
terminal | Terminal | See the downloadable schema for nested fields. |
/api/vendor/terminals/{terminalId}Update a reader
Updates a terminal owned by the authenticated vendor. Returned status and revocation state should be reviewed before using a reader.
Parameters
| Name | Location | Requirement |
|---|---|---|
terminalId | path | Required. Resource identifier. |
Request template
Set the API base to include /api. Replace path placeholders and prepare request.json from the body fields below before running.
curl --fail-with-body -X PATCH "$BEXO_API_BASE/vendor/terminals/{terminalId}" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN" \
-H "Content-Type: application/json" \
--data @request.jsonRequest body
| Field | Type | Details |
|---|---|---|
label | string | Device label. |
status | string | Requested state.active · offline · suspended · revoked |
hardwareModel | string | Device model. |
Response fields
| Field | Type | Details |
|---|---|---|
success | boolean | Updated. |
terminal | Terminal | See the downloadable schema for nested fields. |
/api/vendor/api-logsRead paginated device logs
Returns masked card identifiers, operational decisions, timing and usage fields. Do not treat masked identifiers as credentials or access proof.
Parameters
| Name | Location | Requirement |
|---|---|---|
page | query | integer |
limit | query | integer |
terminalId | query | string |
decision | query | string · allow, deny, error |
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/api-logs" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
logs | array | See the downloadable schema for nested fields. |
pagination | object | See the downloadable schema for nested fields. |
/api/vendor/reports/subscribersExport subscribers
Membership records and total/active/grace/expired counts. Supports search and status filters. JSON is default; format=csv exports the report. Private account data. Keep it out of public pages, analytics events and application logs.
Parameters
| Name | Location | Requirement |
|---|---|---|
range | query | Preset reporting period. Presets take precedence over custom dates. · today, last_7_days, last_30_days, this_month |
startDate | query | Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation. |
endDate | query | Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation. |
format | query | csv returns text/csv; otherwise JSON. · json, csv |
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/reports/subscribers" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
subscribers | array | See the downloadable schema for nested fields. |
summary | object | See the downloadable schema for nested fields. |
/api/vendor/reports/financial-revenueExport financial revenue
Transaction and gross/commission/net summary fields. These are application reports, not proof of provider settlement or bank reconciliation. JSON is default; format=csv exports the report. Private account data. Keep it out of public pages, analytics events and application logs.
Parameters
| Name | Location | Requirement |
|---|---|---|
range | query | Preset reporting period. Presets take precedence over custom dates. · today, last_7_days, last_30_days, this_month |
startDate | query | Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation. |
endDate | query | Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation. |
format | query | csv returns text/csv; otherwise JSON. · json, csv |
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/reports/financial-revenue" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
transactions | array | See the downloadable schema for nested fields. |
summary | object | See the downloadable schema for nested fields. |
/api/vendor/reports/terminal-verificationsExport terminal verifications
Recorded verification events and operational usage summaries. JSON is default; format=csv exports the report. Private account data. Keep it out of public pages, analytics events and application logs.
Parameters
| Name | Location | Requirement |
|---|---|---|
range | query | Preset reporting period. Presets take precedence over custom dates. · today, last_7_days, last_30_days, this_month |
startDate | query | Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation. |
endDate | query | Custom date boundary when a preset is not used. Confirm timezone assumptions for reconciliation. |
format | query | csv returns text/csv; otherwise JSON. · json, csv |
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/reports/terminal-verifications" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
logs | array | See the downloadable schema for nested fields. |
summary | object | See the downloadable schema for nested fields. |
/api/vendor/reports/metered-billingExport metered billing
Recorded usage statements plus tenantDetails, platformDetails and summary. Confirm your contractual billing terms independently of display defaults. JSON is default; format=csv exports the report. Private account data. Keep it out of public pages, analytics events and application logs.
Parameters
| Name | Location | Requirement |
|---|---|---|
format | query | csv returns text/csv; otherwise JSON. · json, csv |
Request template
Set the API base to include /api. Replace path placeholders before running.
curl --fail-with-body -X GET "$BEXO_API_BASE/vendor/reports/metered-billing" \
-H "Authorization: Bearer $BEXO_MEMBER_TOKEN"Response fields
| Field | Type | Details |
|---|---|---|
statements | array | See the downloadable schema for nested fields. |
summary | object | See the downloadable schema for nested fields. |