Business System Integration
Steps 7 and 8 of From Deployment to First Payment already exercised the system's built-in payment debug; this page covers the next step — having your business system actually call the unipay open APIs: where the credentials come from, how to keep them safe, how to integrate callbacks, which SDK to choose, and where to look when something goes wrong.
This page covers operations and decisions; protocol details such as request parameters, signature algorithms, and message formats are in the API docs.
Credential Checklist
Integration needs the following four items, all from the API Credentials page (merchant panel: Merchant Center → Business Configuration → API Credentials; the admin panel can manage it on behalf: Merchant Workbench → Business Configuration → API Credentials):
| Credential | How to obtain | Purpose |
|---|---|---|
Merchant number mchNo | View in the merchant list / merchant profile | Request identity |
App number appId | View on the app management card (starting with A) | Isolation unit of the call; falls back to the default app when omitted |
| Merchant private key | API Credentials → "Generate Key Pair" in the merchant public key section; the private key is shown only once in the dialog | Your business system signs requests |
| Platform public key | API Credentials → "Copy" in the platform public key section | Your business system verifies signatures of platform responses and callbacks |
Optional: the communication key (AES), used for encrypting/decrypting sensitive API data — can be skipped during integration.
What if the private key is lost
The merchant private key is never shown a second time and is not retained on the platform side. If lost, the only option is to "Generate Key Pair" and "Save" again on the API Credentials page (the old public key is overwritten; requests signed with the old private key will fail verification) — save it securely right after generating.
Key Safekeeping Rules
- Never commit the private key to a code repository or hard-code it; inject it via environment variables or a configuration center — in production, manage it independently of the application configuration.
- The business system and the platform each keep only their own private key and the other side's public key; private keys are never exchanged.
- Isolate keys by environment: sandbox and production use different key pairs, so a test system never signs with a production private key.
Callback Integration
Payment / refund results are pushed to the business system via async callbacks (notifyUrl is passed per request when placing the order):
- Prepare the receiving end:
notifyUrlmust be an HTTP(S) URL reachable from the public internet — the same requirement as for the "Backend API URL"; for local integration, set up an intranet tunnel per Local Debugging; - Verify the callback chain: fill your receiving URL into "Async Notification URL" on the payment debug page and initiate a payment; confirm the server receives the message;
- Verify the signature before processing: callback messages carry a platform signature — always verify with the platform public key first, then process the business logic, to guard against forged notifications; the response format and retry rules are in Async Callback;
- Handle idempotently: the same order may receive multiple notifications (a retry mechanism exists); deduplicate by order number;
- Check push records: on the platform side, "Callback Notifications → Merchant Callback Push" shows each notification's send record and response; failed tasks can be manually resent — this is the first place to look when debugging.
When orders succeed locally but no callbacks arrive, check the merchant callback push page first: records exist and failed → check your receiving end; no records → check whether the notifyUrl in the order parameters is correct.
SDK Choice
The system ships official SDKs in five languages that wrap request signing, response verification, and callback verification — strongly recommended over hand-rolled signing:
| Language | Fit |
|---|---|
| Java | JVM business systems (Spring Boot, etc.) |
| Go | Go services / cloud-native deployments |
| Node.js | Node servers / middle layers |
| PHP | Traditional PHP business systems |
| Python | Python services / scripting tools |
How to import, initialize, and call each SDK is in the SDK Guide. For hand-rolled integration (other languages), implement per the Signature Mechanism and compare the string-to-sign with the "Signature Debug" page (see below).
Suggested Integration Flow
- The sandbox moves no real funds and behaves the same as production — cover both the happy path and exception flows (payment timeout, refund) there as much as possible;
- Sandbox is available for "Alipay (direct)" only; WeChat and other channels have no sandbox — verify with small real payments on production channel merchants;
- Switching to production replaces three things: the base URL (backend API URL), the merchant key pair (regenerating for production is recommended), and the channel merchants (production-environment channel merchants and keys);
- For the first production payment, run one small real end-to-end verification (including a real callback), and open up business only after it is confirmed.
Troubleshooting Tools
| Tool | Location | Purpose |
|---|---|---|
| Payment Debug (Standard/Gateway) | Development & Debug | Reproduce ordering, parameter assembly, and signing end to end without writing code |
| Signature Debug | Development & Debug | Reproduce the string-to-sign and signature value from parameters and the private key; the "Verify Signature" tab verifies in reverse — the first tool for signature failures |
| Signature self-check probe | POST /unipay/ping | Sends a minimal signed request: passing means the merchant number/app/private key/signature construction are all correct (see Health and Self-check) |
| Payment API logs | System Management → Log Management → Payment API Logs | Full request/response messages received by the platform |
| Merchant Callback Push | Callback Notifications | Send records and resends of platform → business system notifications |
| Channel Callback Records | Callback Notifications | Receipt records of channel → platform notifications |
Common Integration Errors
| Symptom | Cause and handling |
|---|---|
| Signature verification fails / wrong signature | The private key does not pair with the merchant public key saved on the platform (regenerated the key pair?); the time field not sent in UTC+8 yyyy-MM-dd HH:mm:ss; parameters not sorted lexicographically. Compare the string-to-sign on the Signature Debug page |
| Request rejected: missing required field | Check mchNo, reqId, reqTime, sign, and business-required fields; when appId is omitted, confirm the merchant has a default app configured |
| Merchant or app unavailable | Merchant disabled, app stopped, or appId not matching the merchant number (see the error semantics in Application Configuration) |
| Order succeeds but no callback | See step 5 of "Callback Integration"; in local environments, use order "Sync" to pull the status actively |
| Callback received but business not applied | No idempotent dedup, so duplicate processing was rejected by the business side; or a signature failure was swallowed by business code — check the receiving end's logs first |
| SDK reports a parse error | Base URL misconfigured (carrying the /unipay prefix or pointing at a frontend URL); check the environment configuration in the SDK docs |
Related Links
- API Docs: protocol and field reference
- SDK Guide: SDKs in five languages
- From Deployment to First Payment: the preceding main track