2.8 KiB
Stripe Checkout payments
Virt Cloud uses Stripe-hosted Checkout for card and Alipay payments. Card data never enters the panel. A browser return is informational only; wallet and invoice settlement happens only after a verified Stripe Webhook event.
Database and encryption key
Fresh installs already include the Stripe tables in sql/ss.sql and the wider
invoice-payment status contract in sql/cloud.sql. For an existing database,
import sql/stripe_payment.sql once after its cloud schema is current. Before
saving Stripe credentials, configure an independent 32-byte encryption key in
the PHP runtime environment:
env[STRIPE_CREDENTIAL_KEY] = "generated-base64-value"
Generate a suitable value with:
php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'
Do not reuse the site data key or another payment driver's credential key. Changing this key without re-saving the Stripe credentials makes the stored ciphertexts unreadable.
Stripe Dashboard
- Open Admin -> Stripe payment and keep test mode enabled.
- Save a matching
sk_test_...Secret key and the fixed HTTPS panel URL. - In Stripe Workbench, create a Webhook endpoint at
https://panel.example.com/stripe/webhookand subscribe to:checkout.session.completedcheckout.session.async_payment_succeededcheckout.session.async_payment_failedcheckout.session.expired
- Save the endpoint's
whsec_...signing secret in the panel. - Enable Alipay in Stripe Dashboard Payment methods when it is supported for the Stripe account's business country. The panel switch cannot grant a payment-method capability that Stripe has not enabled for the account.
- Test card and Alipay Checkout, Webhook delivery, wallet credit, invoice settlement and duplicate-event handling before switching to live mode.
Live mode requires a matching sk_live_... key and the live Webhook endpoint's
own signing secret. Test and live Webhook signing secrets are not interchangeable.
Accounting and safety contract
- The panel's wallet and cloud invoices are denominated in USD, so Stripe
Checkout is fixed to
usd. There is no implicit currency conversion. - Card and Alipay are separate panel methods and can be enabled independently.
- Every Checkout Session is created with a stable Stripe idempotency key, but a request with an uncertain transport result is still fenced locally and is not automatically replayed.
- Webhooks are verified against the exact raw request body and
Stripe-Signature, limited to a five-minute timestamp tolerance and deduped by Stripe event ID. - Amount, currency, live/test mode, payment method, local order number, Checkout Session and PaymentIntent ownership are checked before settlement.
- Stripe may retry failed Webhook deliveries. Replayed events cannot credit the wallet or settle an invoice twice.