# Newlink payment gateway setup

Import `database/payment-gateway.sql` once, after the main schema and PDF migration. Back up existing installations first.

Requires PHP 8.1+, PDO MySQL, cURL, sodium, fileinfo, and MySQL 8. Configure HTTPS and a public `APP_URL` such as `https://courses.example.com` (without a trailing path). Set a unique base64-encoded 32-byte `GATEWAY_MASTER_KEY` in server environment variables. Generate it locally with `php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'`. Keep it in a secret manager/server configuration and retain a secure backup; losing it prevents decrypting saved credentials.

Default allowed API host: `newlink.click`. Default allowed payment-link host: `planapi.online`. Set comma-separated `GATEWAY_ALLOWED_HOSTS` / `PAYMENT_ALLOWED_HOSTS` to explicitly authorize other gateway domains. Admin can change the base URL/path within approved hosts. API requests require HTTPS, pin a resolved public IPv4 address, verify TLS and refuse redirects. Only approve trusted gateway hosts, as they receive the API secret.

In Admin → Payment gateway, set API base URL `https://newlink.click/api/v1`, username and key, then enable payments. Keys are encrypted at rest with sodium; no secret is echoed back or written to audit records. Versioned gateway records preserve existing order configuration. New endpoints/usernames require entering the corresponding key again. Pending old orders require their old credentials to remain valid at the provider.

The customer selects a published plan, supplies a mobile number, and creates an order. Price, referral recipients, commission amounts and gateway version are snapshotted server-side. Duplicate concurrent checkouts for the same user are serialized by a database row lock; unresolved orders are reused instead of blindly retried. Failed/uncertain creation remains in review and blocks another same-plan order. Support reconciliation and recovery tooling is still required; do not clear or retry these blindly.

Redirect callbacks are untrusted navigation only. The same-site status page requires the logged-in owner, queries check_status automatically on landing, and supports manual retries plus optional validate_utr. UTR validation alone never activates an account: check_status must confirm SUCCESS with the exact local order ID, amount and a unique 12-digit UTR. A different order ID returned by create_order is rejected for review (the provided documentation's examples show inconsistent IDs; confirm provider behavior in sandbox).

Verified settlement locks the order, activates the account, grants the purchased plan's PDF access and inserts four-level commission entries atomically. Commission entries are pending; release/withdrawal and refund/reversal policies are not implemented. Missing/inactive uplines at order creation receive no entry and amounts do not roll up. The stored rule snapshot prevents later admin price/commission changes from altering that order. Repeated verification of a paid order cannot duplicate entries. A transaction's UTR cannot settle a second order.

## Verification and remaining launch work

Implemented from the documentation supplied in chat. No live API calls or payments were made. PHP/MySQL runtime is unavailable in this workspace; syntax and integration tests remain required. Verify sandbox success/pending/failure responses, exact order-ID echo, duplicate callbacks, concurrent status checks, amount mismatch, reused UTR, gateway URL changes, timeout recovery, blocked users, PDF authorization and all four recipients before enabling production payments.

No asynchronous provider webhook is documented. Automatic activation occurs when the owner returns/visits payment status; payment completed without returning needs a later visit or a future scheduled reconciliation worker. Confirm signed webhook support with the provider if background activation is required. Dashboard wallet UI, order-history/recovery tooling, admin MFA, refunds/commission reversals, payout release, and production security validation remain outstanding. This integration has not established legal approval of the compensation model.