Business API

All paths below are relative to BUSINESS_API_BASE. The current US deployment prefix is /api/business/v1.

Use the API key for this target. This page describes the target contract; confirm activation for your application.

Download OpenAPI · Object reference

List applications

GET /apps

List applications visible to this credential. Inspect enabled_payment_entries before choosing a payment entry.

Required scope: apps:read.

Parameter	Location	Required	Type and constraints
cursor	query	No	string Max length: 1024.
limit	query	No	integer Minimum: 1. Maximum: 100. Default: 25.

Response: 200

Field	Type	Required	Description
data	array of App	Yes	The response resource or resource list. Max items: 100.
meta	Meta	Yes	Response correlation and freshness metadata.
next_cursor	string or null	Yes	Pass this value unchanged to fetch the next page. Null ends the list.

Failures use the shared error object. See recovery guidance.

Retrieve an application

GET /apps/{app_id}

Read the application state, enabled entries, and platform bindings visible to the credential.

Required scope: apps:read.

Parameter	Location	Required	Type and constraints
app_id	path	Yes	string Min length: 1. Max length: 40.

Response: 200

Field	Type	Required	Description
data	App	Yes	The response resource or resource list.
meta	Meta	Yes	Response correlation and freshness metadata.

Failures use the shared error object. See recovery guidance.

List orders

GET /orders

Read a cursor-paginated reporting view of orders, with optional filters. Check response freshness.

Required scope: orders:read.

Parameter	Location	Required	Type and constraints
cursor	query	No	string Max length: 1024.
limit	query	No	integer Minimum: 1. Maximum: 100. Default: 25.
app_id	query	No	string Min length: 1. Max length: 40.
status	query	No	pending, processing, unknown, paid, failed, closed
created_from	query	No	string (date-time)
created_before	query	No	string (date-time)

Response: 200

Field	Type	Required	Description
data	array of Order	Yes	The response resource or resource list. Max items: 100.
meta	Meta	Yes	Response correlation and freshness metadata.
next_cursor	string or null	Yes	Pass this value unchanged to fetch the next page. Null ends the list.

Failures use the shared error object. See recovery guidance.

Retrieve an order

GET /orders/{order_id}

Read the order, its payment amounts, state, and version. Use the Payment API for authoritative payment reconciliation; the Business API returns a reporting view.

Required scope: orders:read.

Parameter	Location	Required	Type and constraints
order_id	path	Yes	string Min length: 1. Max length: 40.

Response: 200

Field	Type	Required	Description
data	Order	Yes	The response resource or resource list.
meta	Meta	Yes	Response correlation and freshness metadata.

Failures use the shared error object. See recovery guidance.

List refunds

GET /refunds

List refund reporting records by review or execution state. Date filtering is part of the target contract; rollout support must be confirmed.

Required scope: refunds:read.

Parameter	Location	Required	Type and constraints
cursor	query	No	string Max length: 1024.
limit	query	No	integer Minimum: 1. Maximum: 100. Default: 25.
app_id	query	No	string Min length: 1. Max length: 40.
review_status	query	No	received, needs_materials, under_review, awaiting_funds, approved, rejected, cancelled
execution_status	query	No	not_submitted, accepted, submitting, processing, unknown, succeeded, failed, cancelled
created_from	query	No	string (date-time)
created_before	query	No	string (date-time)

Response: 200

Field	Type	Required	Description
data	array of Refund	Yes	The response resource or resource list. Max items: 100.
meta	Meta	Yes	Response correlation and freshness metadata.
next_cursor	string or null	Yes	Pass this value unchanged to fetch the next page. Null ends the list.

Failures use the shared error object. See recovery guidance.

Retrieve a refund

GET /refunds/{refund_id}

Read the stable refund request ID, review status, execution status, and estimated or actual economics.

Required scope: refunds:read.

Parameter	Location	Required	Type and constraints
refund_id	path	Yes	string Min length: 1. Max length: 40.

Response: 200

Field	Type	Required	Description
data	Refund	Yes	The response resource or resource list.
meta	Meta	Yes	Response correlation and freshness metadata.

Failures use the shared error object. See recovery guidance.

Check refund eligibility

GET /orders/{order_id}/refund-eligibility

Perform an authoritative point-in-time eligibility check. Submission rechecks capacity, version, and policy.

Required scope: refunds:read.

Parameter	Location	Required	Type and constraints
order_id	path	Yes	string Min length: 1. Max length: 40.

Response: 200

Field	Type	Required	Description
data	RefundEligibility	Yes	The response resource or resource list.
meta	Meta	Yes	Response correlation and freshness metadata.

Failures use the shared error object. See recovery guidance.

Request a refund

POST /orders/{order_id}/refunds

Submit principal for a full or partial refund using the current order version. Acceptance starts the refund workflow; it does not confirm provider completion.

Required scope: refunds:write.

Parameter	Location	Required	Type and constraints
order_id	path	Yes	string Min length: 1. Max length: 40.
Idempotency-Key	header	Yes	string Min length: 1. Max length: 191.

Request body

Field	Type	Required	Description
amount_minor	integer	Yes	An integer in the smallest currency unit: fen for CNY or cents for USD. Minimum: 1. Maximum: 9007199254740991.
reason	customer_request, duplicate, fraud, service_issue, consumer_complaint, other	Yes	The refund reason.
expected_order_version	integer	Yes	The current order version used to check concurrency. Minimum: 1. Maximum: 9007199254740991.

Response: 202

Field	Type	Required	Description
data	Refund	Yes	The response resource or resource list.
meta	Meta	Yes	Response correlation and freshness metadata.

Response headers: Location, Retry-After. Follow a returned status location on the assigned service.

Failures use the shared error object. See recovery guidance.

List balances

GET /balances

Read balances by application and currency. Each balance and response metadata records its reporting time.

Required scope: finance:read.

Parameter	Location	Required	Type and constraints
app_id	query	No	string Min length: 1. Max length: 40.
cursor	query	No	string Max length: 1024.
limit	query	No	integer Minimum: 1. Maximum: 100. Default: 25.

Response: 200

Field	Type	Required	Description
data	array of Balance	Yes	The response resource or resource list. Max items: 100.
meta	Meta	Yes	Response correlation and freshness metadata.
next_cursor	string or null	Yes	Pass this value unchanged to fetch the next page. Null ends the list.

Failures use the shared error object. See recovery guidance.

List release stages

GET /release-stages

Read the amounts, due dates, and reasons that can block a scheduled release.

Required scope: finance:read.

Parameter	Location	Required	Type and constraints
app_id	query	No	string Min length: 1. Max length: 40.
cursor	query	No	string Max length: 1024.
limit	query	No	integer Minimum: 1. Maximum: 100. Default: 25.

Response: 200

Field	Type	Required	Description
data	array of ReleaseStage	Yes	The response resource or resource list. Max items: 100.
meta	Meta	Yes	Response correlation and freshness metadata.
next_cursor	string or null	Yes	Pass this value unchanged to fetch the next page. Null ends the list.

Failures use the shared error object. See recovery guidance.

Retrieve an operation

GET /operations/{operation_id}

Follow an asynchronous command. Inspect its resource reference to retrieve the resulting business object.

Required scope: operations:read.

Parameter	Location	Required	Type and constraints
operation_id	path	Yes	string Min length: 1. Max length: 40.

Response: 200

Field	Type	Required	Description
data	Operation	Yes	The response resource or resource list.
meta	Meta	Yes	Response correlation and freshness metadata.

Failures use the shared error object. See recovery guidance.