From Deployment to First Payment
This guide covers how to get from a successful deployment to your first payment through, via the required configuration steps.
- The walk-through uses the sandbox environment of Alipay (direct); no real funds move. Steps for switching to production after sandbox verification are at the end of this page
- Only the required flow is covered; optional items are flagged separately. The UI fields and actions in each section match the current system version
- Daily operations (orders, refunds, allocation, etc.) are covered in the Business Features chapters
Prerequisites:
- The system has been deployed following Run or One-Click Deployment, and the health check
{"status":"UP"}passes - The initialization SQL has been imported, and you can sign in to the admin panel with the development-environment super administrator account
- You have registered an Alipay Open Platform account (the sandbox stage uses its sandbox environment; no business verification required)
The whole flow takes about 30–60 minutes; the time per step is listed below.
Go-Live Flow Overview
The go-live process has two phases: admin panel configuration makes the system ready to accept payments, and merchant panel configuration completes the integration signature and verifies payment.
| Step | Console | Menu entry | Time |
|---|---|---|---|
| 1. Account security | Admin panel | System Management → User Management | 5 min |
| 2. Endpoint configuration | Admin panel | System Management → System Configuration → Platform Configuration | 5 min |
| 3. Sandbox environment | Admin panel | Access Configuration → Payment Product Configuration | 2 min |
| 4. Create merchant | Admin panel | Merchant Management → Merchant List | 5 min |
| 5. Provision channel merchant | Admin panel | Merchant Workbench → Channel Merchants | 5 min |
| 6. Configure channel keys | Admin panel | Channel Merchants → App Management | 15 min (including Alipay-side operations) |
| 7. Integration signature setup | Merchant panel | Merchant Center → Business Configuration → API Credentials | 5 min |
| 8. First payment | Merchant panel | Development & Debug → Payment Debug (Standard) | 5 min |
For an item-by-item checklist see the Go-Live Checklist.
Step 1: First Login and Account Security
Sign in to the admin panel with the super administrator account initialized at deployment. The default development-environment account is described in Run - Default Login (account bootx; it can only sign in to the admin panel in the dev environment).
Super administrator is for development environments only
The super administrator is controlled by the config item daxpay.platform.starter.auth.enable-admin — enabled by default in dev, forcibly disabled in prod. In production, confirm this config is false after finishing this section; see Configuration - Super Administrator.
Recommended immediately: use the super administrator to create a proper operations administrator account under "System Management → Permissions → User Management", assign roles and menu permissions, and use that account for daily work. For details see User Management.
Step 2: Configure Platform Endpoints
Menu path: admin panel → System Management → System Configuration → Platform Configuration → Endpoint Configuration
Endpoint configuration tells the system the external access URLs of each side. Click "Edit" in the upper-right corner to enter edit mode, fill in the values, and click "Save" (a confirmation dialog appears before saving; "Cancel" reverts the changes).
| Config item | Purpose |
|---|---|
| Admin panel URL | Base URL of the operations admin panel; used to build callback URLs for third-party login when client=admin |
| Merchant panel URL | Base URL of the merchant panel; must match the merchant frontend access origin and be registered in the open platform whitelist |
| Payment gateway frontend URL | URL of the payment cashier / gateway pages; payment page redirects depend on this item |
| Backend API URL | Base API URL of the backend service; backend-initiated scenarios such as payment callback notifications depend on this item |
Example formats: https://admin.daxpay.com, https://pay.daxpay.com, https://api.daxpay.com.
Each URL has a "Check" button on its right: for the backend API URL the check invokes the deployment self-check probe (verifies the callback endpoint is reachable); the other URLs are checked for HTTP reachability, and the latency is shown when the check passes (e.g. Connectivity check passed (35ms)).
What to fill in for local development
When you have no public URL locally: first fill in format-valid placeholder domains (e.g. https://pay.example.com) so API calls do not error; when you actually need to receive callbacks, set up an intranet tunnel per Local Debugging and replace the placeholders with the tunnel URL.
The other tabs at the same level are all optional; configure as needed:
| Tab | Content | Notes |
|---|---|---|
| Site configuration | System name, logo, ICP filing and copyright info | Display-facing configuration |
| OSS configuration | S3-compatible object storage | Storage for files such as reconciliation statements; see Storage Configuration |
| Email configuration | SMTP email service | Notification scenarios such as password recovery |
| Sensitive word policy | Enable/disable sensitive word detection | Usually keep the default |
Step 3: Confirm the Sandbox Environment
The sandbox environment uses test accounts and keys provided by Alipay, letting you verify the complete payment flow without moving real funds — strongly recommended for a first go-live.
The sandbox is controlled by two layers:
| Layer | Control | Notes |
|---|---|---|
| Global switch | Config item daxpay.platform.config.sandbox-enabled | Enabled by default in development; forcibly disabled in production, and the sandbox entry in the UI is hidden accordingly |
| Product environment | Admin panel "Access Configuration → Payment Product Configuration" | Each payment product switches between production / sandbox individually |
Action: open Access Configuration → Payment Product Configuration, find the "Alipay (direct)" product, and click the environment badge at the upper-right corner of the product card to switch it to sandbox.
Switch the environment before creating channel merchants (important)
A channel merchant freezes a snapshot of the product's environment at creation time (sandbox / production); after that:
- Switching the product environment does not affect channel merchants already created;
- Channel merchants whose environment does not match the product are excluded from routing; initiating a payment reports an environment-mismatch error;
- The tooltip of the "Environment" column in the channel merchant list says the same: "environment flag frozen at creation; does not change with product switching".
So the order of operations must be: switch the product to sandbox in product configuration first, then run Step 5 to create the channel merchant. When you switch back to production after sandbox verification, you must re-create production channel merchants and configure production keys.
Two additional notes:
- Only products that support the sandbox show the environment switch: "Alipay (direct)" supports sandbox; "Alipay (ISV)" does not.
- The payment products, payment channels, and payment capabilities under "Payment Management → Payment Master Data" are built-in master data, read-only with no creation — you do not need to worry about their creation order; the "Payment Product Configuration" page is what handles enable/disable and environment switching.
Step 4: Create a Merchant
Menu path: admin panel → Merchant Management → Merchant List → Add
The form has two groups, "Merchant Info" and "Administrator Info":
| Field | Required | Description |
|---|---|---|
| Merchant name | Yes | Full name of the merchant |
| Merchant short name | Yes | Short name shown in lists and pages |
| Entity type | Yes | Micro merchant / sole proprietor / enterprise |
| Account | Yes | Login account of this merchant's administrator (used to sign in to the merchant panel) |
| Name | Yes | Display name of the administrator |
| Password / Confirm password | No | If left blank, the system generates a random initial password; if filled in, enter the same value twice |
After clicking "Save", the system automatically does four things — no manual action needed:
- Generates a globally unique merchant number (starting with
M); - Creates the merchant's administrator account, bound to the merchant super-admin role (can sign in to the merchant panel);
- Creates the default app (an appId starting with
A; used by default when a payment does not specify an appId); - Creates the default store.
After creation the drawer switches to a result view: a green banner at the top says "Copy this now and pass it to the user securely; the user must change the password after first login", and the panel shows the account and initial password (in plain text) with a "Copy" button next to the password.
The initial password is shown only once
The initial password is displayed only on this result page; after closing the drawer it cannot be viewed again — the only remedy is a password reset. Copy and store it immediately.
Step 5: Provision a Channel Merchant
A channel merchant is a merchant's provisioning record on a specific payment product (channel); at least one must be provisioned before payments can be initiated.
Menu path: admin panel → Merchant Management → Merchant List → "Manage" in the actions column → Merchant Workbench → Payment Configuration group → Channel Merchants
Take a moment to get familiar with the merchant workbench — it is the admin panel's entry for managing all of a merchant's configuration, grouped into tiled cards:
| Group | Features |
|---|---|
| Basic Management | Merchant profile, merchant users, store management, system terminals |
| Payment Configuration | Channel Merchants, App Management, Payment Apps (WeChat), Payment Apps (Douyin) |
| Business Configuration | API credentials, domain verification files |
| Dangerous Operations | Delete merchant (double confirmation; only merchants with no transaction data can be deleted) |
Open the "Channel Merchants" list page and click "Create Channel Merchant" on the toolbar; creation has two steps:
Step 1 Pick a payment product: the page lists all enabled products as cards (product logo, product name, owning channel), with the product's current environment badge at the upper-right (orange "Sandbox" / blue "Production"; shown only for sandbox-capable products). Pick "Alipay (direct)" and click "Next".
Step 2 Fill in channel info (Alipay direct):
| Field | Description |
|---|---|
| Payment product | Read-only echo of the picked product |
| Channel merchant name | Custom name for easy identification in the list |
| Alipay merchant user ID | Partner ID of the Alipay account (starting with 2088); in sandbox, fill the sandbox merchant account (see the next step for obtaining sandbox parameters) |
Click "Create Channel Merchant"; on success a green check mark and the message "Channel merchant created successfully" appear — click "Close Page" to return to the list. The channel merchant number is generated by the system (channel prefix + random digits) and cannot be changed after creation.
WeChat (direct) for comparison
WeChat direct takes "channel merchant name + WeChat Pay merchant number (the mchId seen in the merchant platform)". The WeChat transfer scene is not part of the creation wizard: after creation, configure it in the "Transaction Configuration" group of the channel merchant detail ("Transfer Scene" and "Transfer Initiating App").
To open H5 / JSAPI payment pages or the unified cashier inside WeChat, you must also upload the domain verification file issued by WeChat (MP_verify_*.txt) under "Business Configuration → Domain Verification Files" in the merchant workbench to complete domain ownership verification.
Notes on the list page:
- The "Environment" column shows the sandbox/production flag frozen for each channel merchant;
- The "Enabled" switch can temporarily disable a channel merchant (its payments become unavailable while disabled);
- The global "Channel Merchants" list at the top level (Merchant Management → Channel Merchants) is a cross-merchant aggregate view; creation still must go through the merchant workbench.
Step 6: Configure Channel Keys
Creating a channel merchant only registers the merchant identity; you still need to configure the channel keys (the Alipay-side app credentials) before the system can call Alipay APIs.
Alipay (direct) key configuration
Menu path: Merchant Workbench → Channel Merchants → "Manage" → Alipay direct merchant management → App Management group → App Management → "Manage" on the app card → Key Configuration tab
Before entering key configuration, the top of the page shows a read-only "Environment" badge (production / sandbox) with the note "the environment is fixed when the channel merchant is created and cannot be switched here" — environment correctness was ensured in Step 3.
Get the sandbox parameters first: sign in to the Alipay Open Platform console and open the "Sandbox" page (in the development/integration section), where you can find:
- Sandbox app APPID (e.g. starting with
9021000000000000) - Sandbox Alipay public key (for the "Alipay public key" field)
- Sandbox buyer account (for test payments, with a download entry for the sandbox wallet app)
The app private key is generated with Alipay's official key tool (downloadable from the open platform doc center; choose "public key mode" to generate an RSA2 key pair). Keep the private key yourself and configure the public key back into the Alipay Open Platform.
Then configure in the system: on the Key Configuration tab, first choose the authentication mode under "Basic Configuration":
| Authentication mode | Fields to configure |
|---|---|
Public key (public_key) | App ID, Alipay public key, app private key |
Certificate (cert) | App ID, app public key certificate, Alipay public key certificate, Alipay root certificate (three .crt files uploaded), app private key |
Public key mode is the simplest for sandbox integration. There is also a "Communication Key" group (an AES key used for encrypting/decrypting some API messages; obtain it from the open platform console).
No gateway URL configuration needed
The system automatically selects the Alipay gateway based on the channel merchant's environment (sandbox openapi-sandbox.dl.alipaydev.com / production openapi.alipay.com); there is no gateway field in the UI and nothing to care about.
Click "Edit" in the upper-right corner → fill in → "Save" (with a confirmation dialog). The current version has no "connection test" button; whether the keys are correct is verified when a payment is initiated in Step 8.
The most common misconfiguration
The "Alipay public key" is the Alipay-side public key (the one the open platform shows you, used to verify Alipay's messages) — not the "app public key" you generated yourself. Swapping the two is the number-one cause of integration failure.
WeChat (direct) keys for comparison
WeChat direct key configuration is shallower: channel merchant detail → Basic Management → the "Direct Key Configuration" drawer. Fields:
| Group | Fields |
|---|---|
| API key | API V3 key (set in the merchant platform under "API Security") |
| Payment certificates | API certificate (apiclient_cert.pem), API certificate private key (apiclient_key.pem), certificate serial number, payment public key (pub_key.pem), payment public key ID |
See the Alipay channel and WeChat channel docs for the complete key parameters of each channel.
Step 7: Merchant Integration Configuration (Exchange Signature Public Keys)
Business systems call the unipay open APIs with RSA signatures; the signature is merchant-level (shared by all apps of the same merchant):
- Merchant requests: signed with the merchant private key → the platform verifies with the "merchant public key";
- Platform responses and callbacks: signed with the platform private key → the merchant verifies with the "platform public key".
So the public keys need to be exchanged once.
Menu path: merchant panel → Merchant Center → Business Configuration → API Credentials (a banner at the top of the page reads: "Merchant API credentials are used for authentication and data encryption/decryption on API calls; keep the keys safe")
| Section | Action | Purpose |
|---|---|---|
| Platform public key | Read-only; click "Copy" and bring it back to your business system | The business system uses it to verify signatures of platform responses and callbacks |
| Merchant public key | Click "Generate Key Pair" to auto-fill, or paste an existing public key | The platform uses it to verify signatures of merchant requests |
| Communication key | Optional; click "Generate Key" | Data encryption (AES) on API calls |
Procedure:
- Click "Generate Key Pair" — if a public key already exists, confirm the overwrite first;
- A dialog titled "RSA Key Pair" opens, showing the generated private key, with a yellow warning bar: "The private key is shown only this once; store it securely — it cannot be recovered if lost". Copy the private key immediately and store it safely (the payment debug in the next step and your business system signing both need it);
- Close the dialog (the public key has been auto-filled into the form) and click "Save" (with a confirmation dialog).
The admin panel can also manage this configuration on behalf of the merchant: Merchant Workbench → Business Configuration → API Credentials (the admin-side entry of the same feature).
Step 8: Initiate the First Payment
The built-in development debug page can simulate a real unipay call and verify the entire payment chain without writing any code.
Menu path: merchant panel → Development & Debug → Payment Debug (Standard) (the page is labeled "Merchant API simulator"; submitting actually calls the /unipay/pay API)
Steps:
- Set the merchant private key: click the "Set Private Key" button and paste the merchant private key saved in Step 7 into the dialog (helper text: "Used only to generate request signatures; stored only in the browser's local cache"). Once set, a green "Set" badge appears in the button area;
- Choose the payment mode:
- Follow channel routing (recommended): pick "merchant + app + pay method"; the app routing resolves the channel merchant and pay capability;
- Specify directly: manually pick "channel merchant + pay capability", skipping channel routing (for troubleshooting);
- Fill in order info: order number (click "Generate" to auto-fill), amount (unit: cents, minimum 1), and title; in the "Payment Parameters" area select a pay method such as
Alipay QR(alipay_qr); - Submit the payment: click the red "Submit Payment" at the bottom. The page assembles the parameters, signs them, and calls the unified pay API;
- View the result: a dialog shows the response — QR-type payments display the payment QR code and payment link, JSAPI-type payments show the parameter JSON, and the "Full DaxResult Response" at the bottom can be copied;
- Complete the payment: sign in with the sandbox buyer account in the Alipay sandbox wallet app and scan the QR code in the result dialog to pay.
After the payment succeeds, check the order:
- On the merchant panel under "Trade Orders → Payment Orders → Normal Orders" or "Payment Trades" you can find the order, with business status "Success";
- If your local environment cannot receive the channel callback, the order stays in pending payment — run the "Sync" action on that order in the order list to pull the latest status.
Gateway payment debug
To exercise the unified cashier or aggregate scan (QR terminal, one QR for multiple wallets) flow, first complete "Gateway Payment Configuration" in the app workbench, then use "Development & Debug → Payment Debug (Gateway)": pick the gateway payment type (unified cashier / aggregate scan) and, after submitting the pre-order, you get a gateway landing page URL (scan or open it) to verify the cashier page. See Gateway Payment.
Step 9 (optional): Callback Verification and Signature Integration
After the sandbox payment works, it is recommended to also verify callbacks and signatures; after that you are ready for real integration:
- Async callback: fill your receiving URL into the "Async Notification URL" field of payment debug and initiate a payment, to verify message reception and signature verification; the callback format is in Async Callback. App-level unified notification configuration ("Async Notify Config" in the app workbench, supporting payment/refund event subscriptions) is under construction in the current version and will open in an upcoming release.
- Signature troubleshooting: when API signature verification fails, use "Development & Debug → Signature Debug": the "Generate Signature" tab takes a parameter JSON and the private key and reproduces the string-to-sign and signature value (RSA2); the "Verify Signature" tab verifies in reverse with a public key. A common failure cause is the time field not transmitted in the UTC+8
yyyy-MM-dd HH:mm:ssformat. - Real integration: integrate the unipay APIs per the API docs, or use the official SDK directly (Go / Java / Node.js / PHP / Python, with signing logic built in).
Switching to Production
After sandbox verification passes:
- In "Access Configuration → Payment Product Configuration" switch the product environment back to production;
- Re-run Steps 5 and 6: create channel merchants in the production environment (a production snapshot will be frozen), and configure production keys obtained from your official app on the Alipay Open Platform;
- Confirm the deployment config
sandbox-enabled=false(mandatory in production; at startup the system resets leftover sandbox products to production automatically); - It is recommended to run one end-to-end verification with a small real payment first.
FAQ
| Symptom | Cause and handling |
|---|---|
| Payment reports "channel merchant environment mismatch" | The environment frozen at channel merchant creation does not match the product's current environment (merchant created before switching the environment). Re-create the channel merchant in the correct order |
| Signature verification fails / wrong signature | Merchant public key not saved or private key mismatch; check with the "Signature Debug" page; confirm the time field uses the UTC+8 format |
| Alipay API reports a key error | The "Alipay public key" was mistakenly filled with your own generated "app public key", or the public key/certificate mode does not match the setting on the open platform side |
| QR code appears but the order stays pending | The channel callback cannot reach your local environment. Use order "Sync" to pull the status; in production, check that the "Backend API URL" is publicly reachable |
| Cannot find the "Create" channel merchant button | Creation lives in the channel merchant list inside the merchant workbench; the global channel merchant list is view/enable-disable only |
| Initial password lost | It cannot be recovered; reset that merchant administrator's password (admin panel user management, or the merchant panel password-recovery channel) |
Next Steps
- Go-Live Checklist: verify go-live completeness item by item
- Business Features: daily operations — orders, refunds, transfers, allocation, callbacks, etc.
- Admin Panel Getting Started / Merchant Panel Getting Started: feature overviews of each console
- Payment Channels: parameter details of each channel