Payment API
All paths below are relative to https://pay.appconnect.cn/payment/v1. For example, create a payment session with POST https://pay.appconnect.cn/payment/v1/payment-sessions.
Use the API key for this target. This page describes the target contract; confirm activation for your application.
Download OpenAPI · Object reference
For a complete integration, start with the checkout walkthrough or a payment method guide. The reference below defines the wire contract.
Find an order by your business reference
GET /orders
Look up the exact app_id and external_order_id pair after a lost create response. This is not the Business API order-list endpoint.
Required scope: payments:read.
| Parameter | Location | Required | Type and constraints |
|---|---|---|---|
app_id | query | Yes | string Min length: 1. Max length: 40. |
external_order_id | query | Yes | string Min length: 1. Max length: 128. |
Response: 200
| Field | Type | Required | Description |
|---|---|---|---|
data | array of CnOrder | 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: payments: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 | CnOrder | Yes | The response resource or resource list. |
meta | Meta | Yes | Response correlation and freshness metadata. |
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.
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.
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.
Create a payment session
POST /payment-sessions
Create a WeChat or Alipay order and receive client invocation instructions when ready. Calculate the amount on your server.
| Entry | Client integration |
|---|---|
alipay_app | Pass sdk_string to the Alipay SDK. |
wechat_app | Map sdk_fields into the WeChat SDK. |
wechat_h5 | Open redirect_url in the mobile browser flow. |
wechat_native | Encode qr_url as a WeChat payment QR code. |
alipay_page | Open redirect_url for desktop checkout. |
alipay_qr | Encode the cashier redirect_url as an Alipay QR code. |
alipay_wap | Handle the activated adapter's browser invocation in the mobile web guide. |
Always check the returned discriminator and expiry. HMS uses its separate purchase verification flow.
Required scope: payments:write.
| Parameter | Location | Required | Type and constraints |
|---|---|---|---|
Idempotency-Key | header | Yes | string Min length: 1. Max length: 191. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
app_id | string | Yes | The platform application ID authorized by the credential. Min length: 1. Max length: 40. |
amount_minor | integer | Yes | An integer in the smallest currency unit: fen for CNY or cents for USD. Minimum: 1. Maximum: 9007199254740991. |
currency | CNY | Yes | The three-letter uppercase currency code. |
external_order_id | string | Yes | Your business order ID, unique within the application. Available through the Payment API; omitted from US reporting and customer webhooks. Min length: 1. Max length: 128. |
description | string | Yes | A concise customer-facing purchase description. Min length: 1. Max length: 128. |
scene | object | No | Entry-specific payment context. wechat_h5 requires client_ip and return_url_id. |
scene.client_ip | string (ipv4) or string (ipv6) | No | The IP address of the customer initiating the payment. |
scene.return_url_id | string | No | The ID of an approved return-URL configuration. Do not send an arbitrary URL. Min length: 1. Max length: 40. |
payment_entry | wechat_app, wechat_h5, wechat_native, alipay_app, alipay_wap, alipay_page, alipay_qr | Yes | The payment provider and entry method, such as wechat_h5 or alipay_qr. |
For wechat_h5, scene, scene.client_ip, and scene.return_url_id are required.
Response: 202
| Field | Type | Required | Description |
|---|---|---|---|
data | PaymentSession | 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.
Close an unpaid order
POST /orders/{order_id}/close
Request closure using the latest order version. Follow the returned operation and reconcile the final order state.
Required scope: payments: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 |
|---|---|---|---|
expected_version | integer | Yes | The resource version you most recently read, used to prevent overwriting a concurrent change. Minimum: 1. Maximum: 9007199254740991. |
Response: 202
| Field | Type | Required | Description |
|---|---|---|---|
data | Operation | 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.
Verify an HMS purchase
POST /hms/verifications
Submit the configured product mapping, customer reference, and provider evidence for verification.
Required scope: purchases:write.
| Parameter | Location | Required | Type and constraints |
|---|---|---|---|
Idempotency-Key | header | Yes | string Min length: 1. Max length: 191. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
app_id | string | Yes | The platform application ID authorized by the credential. Min length: 1. Max length: 40. |
product_id | string | Yes | The platform HMS product mapping ID, separate from the provider product ID. Min length: 1. Max length: 40. |
client_user_id | string | Yes | A stable, opaque user identifier from your application for HMS ownership verification. Processed in China; do not send names, email addresses, or phone numbers. Min length: 1. Max length: 191. |
external_order_id | string | Yes | Your business order ID, unique within the application. Available through the Payment API; omitted from US reporting and customer webhooks. Min length: 1. Max length: 128. |
purchase_evidence | string | Yes | Original provider evidence encoded for the activated adapter. The proposed v1 wrapper requires adapter implementation before live use. Min length: 1. Max length: 65536. |
Response: 202
| Field | Type | Required | Description |
|---|---|---|---|
data | Verification | 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.
Retrieve an HMS verification
GET /hms/verifications/{verification_id}
Inspect the original verification until it is verified, rejected, or otherwise requires recovery.
Required scope: purchases:read.
| Parameter | Location | Required | Type and constraints |
|---|---|---|---|
verification_id | path | Yes | string Min length: 1. Max length: 40. |
Response: 200
| Field | Type | Required | Description |
|---|---|---|---|
data | Verification | Yes | The response resource or resource list. |
meta | Meta | Yes | Response correlation and freshness metadata. |
Failures use the shared error object. See recovery guidance.
Restore an HMS purchase
POST /hms/restorations
Verify a previously purchased product for restoration. Reuse durable ownership and fulfillment records to avoid duplicate delivery.
Required scope: purchases:write.
| Parameter | Location | Required | Type and constraints |
|---|---|---|---|
Idempotency-Key | header | Yes | string Min length: 1. Max length: 191. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
app_id | string | Yes | The platform application ID authorized by the credential. Min length: 1. Max length: 40. |
product_id | string | Yes | The platform HMS product mapping ID, separate from the provider product ID. Min length: 1. Max length: 40. |
client_user_id | string | Yes | A stable, opaque user identifier from your application for HMS ownership verification. Processed in China; do not send names, email addresses, or phone numbers. Min length: 1. Max length: 191. |
external_order_id | string | Yes | Your business order ID, unique within the application. Available through the Payment API; omitted from US reporting and customer webhooks. Min length: 1. Max length: 128. |
purchase_evidence | string | Yes | Original provider evidence encoded for the activated adapter. The proposed v1 wrapper requires adapter implementation before live use. Min length: 1. Max length: 65536. |
Response: 202
| Field | Type | Required | Description |
|---|---|---|---|
data | Verification | 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.
Retrieve channel confirmation
GET /orders/{order_id}/channel-confirmation
Read the confirmation state and version before attesting HMS delivery.
Required scope: purchases: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 | ChannelConfirmation | Yes | The response resource or resource list. |
meta | Meta | Yes | Response correlation and freshness metadata. |
Failures use the shared error object. See recovery guidance.
Attest fulfillment
POST /orders/{order_id}/fulfillment-attestations
Report that your business has durably delivered the purchase. expected_version is the channel-confirmation version you just read.
Required scope: purchases: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 |
|---|---|---|---|
expected_version | integer | Yes | The resource version you most recently read, used to prevent overwriting a concurrent change. Minimum: 1. Maximum: 9007199254740991. |
fulfilled_at | string (date-time) | Yes | An RFC 3339 timestamp with an explicit offset. Financial business dates use Asia/Shanghai. |
fulfillment_reference | string | Yes | Your durable business fulfillment reference. Min length: 1. Max length: 191. |
Response: 202
| Field | Type | Required | Description |
|---|---|---|---|
data | ChannelConfirmation | 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.
Retrieve the original payment session
GET /orders/{order_id}/payment-session
Retrieve instructions for the existing order after a lost response or a temporarily unavailable invocation.
Required scope: payments: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 | PaymentSession | Yes | The response resource or resource list. |
meta | Meta | Yes | Response correlation and freshness metadata. |
Failures use the shared error object. See recovery guidance.