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/paytaro-payment.md

62 lines
2.2 KiB
Markdown

# Paytaro payment integration
Paytaro is disabled by default and starts in test mode. The user-facing entry
is labelled only as Alipay. Test mode exposes it only to administrators; when
test mode is disabled, the enabled switch controls whether users can see it.
## Database
Import the payment tables once before enabling Paytaro:
```bash
mysql -u USER -p DATABASE < sql/paytaro_payment.sql
```
The same tables are included in `sql/ss.sql` for fresh installations and in
the scheduled full-data backup list.
## Credential encryption
Generate a dedicated 32-byte key:
```bash
openssl rand -base64 32
```
Expose it to PHP-FPM in the pool configuration:
```ini
env[PAYTARO_CREDENTIAL_KEY] = "generated-base64-value"
```
Restart PHP-FPM after changing the environment. Keep this value unchanged
while the encrypted Paytaro merchant key remains stored in the database.
## Enable
The integration uses Paytaro's documented EPay MAPI endpoint at
`https://v3.paytaro.com/mapi.php`. The endpoint is pinned in server
code and is not editable from the browser.
Open `/admin/paytaro` and configure a public HTTPS callback base URL, the App
ID, merchant key, and the UUID of the Alipay payment method enabled for the
Paytaro application. The UUID is copied from the application's payment-method
list; the literal value `alipay` is not valid for MAPI. Save the settings and
test connectivity before enabling the payment method.
MAPI requests use the EPay MD5 signing rules and send amounts in yuan. Paytaro
returns an Alipay `payurl`; desktop browsers render it as a QR code, while
mobile browsers wrap it in the documented Alipay URL Scheme instead of opening
the QR content as a web page.
Paytaro must be able to reach these public callback routes:
- Balance recharge: `/paytaro/callback`
These routes must bypass authentication and CDN caching. Browser return routes
only bring the user back to the current panel page. They never credit a balance
or activate an account. Only a correctly signed EPay callback matching the PID,
local order, platform trade number, and amount can complete payment. Duplicate
callbacks are idempotent. Signed legacy MGate callbacks remain accepted only so
orders created immediately before an upgrade can still settle.