Payments API reference
Use the Payment API for payment sessions and authoritative payment data. Use the Business API for application and financial views and the target business refund workflow. Authenticate each request with the key assigned to that API.
| Reference | Download |
|---|---|
| Payment API endpoints | Payment API OpenAPI 3.1 |
| Business API endpoints | Business API OpenAPI 3.1 |
| Objects and fields | Schemas are included in both contracts. |
The CN Payment API base URL is https://pay.appconnect.cn/payment/v1. Its examples and OpenAPI download use this production address. The US Business API URL is supplied separately; replace the example server in its OpenAPI download with the assigned address.
These are target contracts based on version 2.4.5 and the documented production-only update. They describe the intended complete interface. Confirm capability activation for your application before making live requests. See release notes.
Conventions
- Send and receive JSON over HTTPS. Use
Authorization: Bearer YOUR_API_KEY. - Send monetary amounts as integers in the currency's smallest unit. Consumer charges use CNY.
- Read the business status in the response. HTTP
202acknowledges acceptance. - Persist an idempotency key and original request before sending a command that requires it.
- Use RFC 3339 timestamps with an explicit offset. A deadline ending at a timestamp is exclusive where documented.
- Preserve identifiers as opaque strings and check the application associated with each resource.
Response objects marked as extensible in OpenAPI can gain fields. Tolerate unknown fields when reading those resources; send only documented fields in request bodies. Handle unknown enum values conservatively rather than treating them as success.
Pagination
Business list endpoints accept cursor and limit where shown. The default limit is 25 and the maximum is 100. Follow next_cursor, including after an empty page, until it is null. Keep filters, credential context, and page size stable while using a cursor.
For date filters, created_from includes the start instant and created_before excludes the end instant. If a deployment cannot provide the requested source field, handle its availability error instead of substituting a different timestamp.
See Authentication, Retry requests safely, and Errors and recovery for shared behavior.