API credentials and authentication
Authenticate server-to-server requests with a Bearer API key:
Authorization: Bearer YOUR_API_KEY
Use HTTPS and send the key in the header. Mobile apps and browser code receive only the values needed for their client flow.
Choose the correct credential
| Credential | Use it for | Configuration variable |
|---|---|---|
| CN Payment API key | Payment sessions, authoritative orders, payment-side refunds, and HMS purchases | PAYMENT_API_KEY |
| US Business API key | Application views, reporting, eligibility, and Business API commands | BUSINESS_API_KEY |
| Webhook signing secret | Verify notifications received by your server | A server-side key store indexed by webhook key ID |
A key is bound to its target, application, environment, and scopes. A Business API key does not authenticate Payment API requests. A webhook secret does not authenticate outbound API calls.
Send CN Payment API requests to https://pay.appconnect.cn/payment/v1. The examples include the full URL, such as https://pay.appconnect.cn/payment/v1/payment-sessions.
NextAppMarket supplies the US Business API URL as part of activation. Store its full versioned URL in BUSINESS_API_BASE. The Business API deployment prefix is /api/business/v1; avoid adding that prefix a second time if it is already in your configured base.
Request the scopes you need
| Task | Scope | API |
|---|---|---|
| Create or close a payment session/order | payments:write | Payment |
| Read an order or payment session | payments:read | Payment |
| Verify or restore an HMS purchase; attest delivery | purchases:write | Payment |
| Read HMS verification or channel confirmation | purchases:read | Payment |
| Read applications | apps:read | Business |
| Read order reporting | orders:read | Business |
| Read refunds or refund eligibility | refunds:read | The API serving the endpoint |
| Request a refund | refunds:write | The API serving the endpoint |
| Read balances and release stages | finance:read | Business |
| Read an asynchronous operation | operations:read | The API serving the operation |
Granting a scope does not activate a payment channel or release a capability that has not been enabled for your application.
Manage Business API keys in Console
Open your application's Payments → China Payments area, then its credentials page. Creating, rotating, or revoking a key requires appropriate application permissions; sensitive changes also require the configured two-factor authentication step.
Save a new secret when it is issued. Routine credential views expose identifying information, not the complete secret. CN Payment credentials are issued separately for the Payment API target.
Production keys expire. Plan rotation before the configured expiry, deploy the replacement secret to your server, and confirm that your requests use it. A normal rotation may provide an overlap window of up to 24 hours, bounded by the original expiry. Use the expiry and overlap values recorded for the credential.
If a key is compromised, revoke it and obtain a replacement. Check unresolved payment commands before retrying with a newly created credential: a new credential can have a different idempotency identity.
Source restrictions
If source restrictions are configured, calls must originate from an allowed server IP range. The scene.client_ip payment field describes the customer's payment context; it does not authorize the API caller. When moving your backend, arrange the source-range update before switching traffic.
See Errors and recovery for UNAUTHENTICATED, SCOPE_DENIED, and configuration errors.