You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/docs/yipay-payment.md

68 lines
2.5 KiB
Markdown

# Yipay payment integration
The integration defaults to disabled and test mode. Its user-facing payment
entries are Alipay and WeChat Pay. The administrator controls them from the
dedicated Yipay settings page.
## Database
Existing installations with the order and refund tables use the [payment currency migration](payment-currency-rollout.md).
The original migrations for these tables are:
```bash
mysql -u USER -p DATABASE < sql/yipay_payment.sql
```
All tables are also included in `sql/ss.sql` for fresh installations and in
the scheduled database backup list.
Existing installations that already imported the original payment tables must
also import the refund table once:
```bash
mysql -u USER -p DATABASE < sql/yipay_refund.sql
```
## Credential encryption
Generate a dedicated 32-byte key:
```bash
openssl rand -base64 32
```
Expose it to PHP-FPM in the pool configuration:
```ini
env[YIPAY_CREDENTIAL_KEY] = "generated-base64-value"
```
Restart PHP-FPM after changing the environment. Keep this key unchanged while
the encrypted Yipay merchant key remains stored in the database.
## Enable
Open `/admin/yipay`, enter the HTTPS gateway root URL, one public HTTPS panel
callback base URL, merchant PID and merchant key. Save and test the connection
before enabling the user-facing switch. Confirm that each enabled method
charges CNY. The panel presents the frozen CNY quote and accounts in USD.
The gateway must be able to send a GET request to the fixed
`/yipay/callback` URL. This route must bypass login and CDN caching. The browser
return URL uses the HTTPS domain from which the authenticated user created the
order, after that host is checked against `baseUrl` and `host_1` through
`host_7`. Only the verified asynchronous callback can credit an account;
`/yipay/return` only redirects the browser back to `/user/code` on the same
domain and never credits an account.
## Refunds
Enable the order refund API in the Yipay merchant backend before using the
refund button on `/admin/yipay`. Only full refunds of paid orders are allowed.
The gateway refunds the CNY amount collected for the order. The panel deducts
the original USD credit and reverses the associated referral entry once. A spent
recharge can leave the user with a negative balance. If the gateway confirms
the refund while local posting fails, complete the local posting from the
original order. An unconfirmed gateway result requires merchant reconciliation.
Invoice payments retain their separate service-period review workflow.