New-API EPay Setup Guide

New-API has EPay top-ups built in, so no plugin is needed. Enter the PoPoPay gateway URL, merchant ID and key in system settings and users can top up their balance with Alipay or WeChat Pay.

  • New-API
  • Online top-up
  • EPay V1
  • Updated

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.

ValueNotes
Gateway domainThe 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.

SettingWhat to enter
Epay endpointhttps://gateway-domain. Enter just the domain; /submit.php is appended automatically
Epay merchant IDpid
Epay secret keykey
Callback addressYour site origin, e.g. https://api.example.com, with no path. Leave blank to use the server address
Top-up priceHow much users pay for each 1 USD of balance, e.g. 7.3
Min Top-upThe 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

  1. Sign in as a regular user and open the top-up page.
  2. Enter an amount and choose Alipay or WeChat Pay. You should land on the checkout page.
  3. After paying, return to your site. If the balance has increased, the setup works.

Common problems

SymptomCause and fix
No online top-up option on the top-up pageOnline 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 changeThe 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 redirectThe 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