Before you start
First ask official support to open an integration app. You will get the three values below; every system on this site uses the same set.
| Value | Notes |
|---|---|
| Gateway domain | The payment gateway from support, e.g. https://gateway-domain |
Merchant ID (pid) | Your app's merchant ID |
Merchant key (key) | Your app's key, used for MD5 signing. Keep it secret |
Payment settings
Sign in as an administrator, open system settings and find the EPay block in the payment and top-up settings (called “Epay Gateway” in the current UI). Fill in the table below and save. Older versions may label the fields slightly differently; match them by meaning.
| Setting | What to enter |
|---|---|
| Epay endpoint | https://gateway-domain. Enter just the domain; /submit.php is appended automatically |
| Epay merchant ID | pid |
| Epay secret key | key |
| Callback address | Your site origin, e.g. https://api.example.com, with no path. Leave blank to use the server address |
| Top-up price | How much users pay for each 1 USD of balance, e.g. 7.3 |
| Min Top-up | The smallest USD amount per top-up |
Either the callback address or the server address must be the public URL users actually visit. New-API builds the notify URL https://your-domain/api/user/epay/notify from it; if it is wrong, payments succeed but balances are not credited.
Top-up methods
Top-up methods are stored as a PayMethods JSON. The type value is sent to EPay as the payment method code, so use alipay for Alipay and wxpay for WeChat Pay:
[
{ "name": "Alipay", "type": "alipay" },
{ "name": "WeChat Pay", "type": "wxpay" }
]New-API places orders by page redirect (/submit.php), so no API IP allowlist is needed.
Test a top-up
- Sign in as a regular user and open the top-up page.
- Enter an amount and choose Alipay or WeChat Pay. You should land on the checkout page.
- After paying, return to your site. If the balance has increased, the setup works.
Common problems
| Symptom | Cause and fix |
|---|---|
| No online top-up option on the top-up page | Online top-up stays disabled if any of Epay endpoint, merchant ID or secret key is empty. Fill in all three and save |
| Paid, but the balance did not change | The notification did not arrive. Check that the callback or server address is your public site origin and that your reverse proxy allows /api/user/epay/notify |
| “Signature verification failed” after redirect | The Epay secret key is wrong or has stray spaces. Copy key again and save |
| “No product configured for payment method xxx” | That method is not enabled yet, or its code is wrong (WeChat Pay is wxpay, not wechat). If the code is right, ask support to enable it |
For other errors see Troubleshooting; for protocol details see Signing and Async notification.
More integration docs
Get your merchant ID and key
Contact official support to open an integration app. Your gateway URL, pid and key are issued directly, with hands-on help during testing.
Contact support